System.Security.SecurityElement Class

Assembly: Mscorlib.dll
Namespace: System.Security
Summary
Represents the XML object model for encoding security objects. This class cannot be inherited.
C# Syntax:
[Serializable]
public sealed class SecurityElement
Remarks
This class is intended to be a lightweight implementation of a simple XML object model for use within the security system, and not for use as a general XML object model. This documentation assumes a basic knowledge of XML.

The simple XML object model for an element consists of the following parts:

It is strongly suggested that attribute based XML representation is used to express security elements and their values. This means properties of an element are expressed as attributes and property values are expressed as attribute values. Avoid nesting text within tags. For any <tag>text</tag> representation a representation of type <tag value="text"/> is usually available. Using this attribute-based XML representation increases readability and allows easy WMI portability of the resulting XML serialization.

An attribute name must be one character or longer, and cannot be null. If element-based value representation is used, elements with a text string that is null are represented in the <tag/> form; otherwise, text is delimited by the <tag> and </tag> tokens. Both forms can be combined with attributes, which are shown if present.

The tags, attributes, and text of elements, if present, are always case-sensitive. The XML form contains quotations and escapes where necessary. String values that include characters invalid for use in XML result in an ArgumentException. These rules apply to all properties and methods.



Note For performance reasons, character validity is only checked when the element is encoded into XML text form, and not on every set of a property or method. Static methods allow explicit checking where needed.
See also:
System.Security Namespace

System.Security.SecurityElement Member List:

Public Constructors
ctor #1 Overloaded:
.ctor(string tag)

Initializes a new instance of the SecurityElement class with the specified tag.
ctor #2 Overloaded:
.ctor(string tag, string text)

Initializes a new instance of the SecurityElement class with the specified tag and text.
Public Properties
Attributes Read-write

Gets or sets the attributes of an XML element as name/value pairs.
Children Read-write

Gets or sets the array of child elements of the XML element.
Tag Read-write

Gets or sets the tag name of an XML element.
Text Read-write

Gets or sets the text within an XML element.
Public Methods
AddAttribute Adds a name/value attribute to an XML element.
AddChild Adds a child element to the XML element.
Attribute Finds an attribute by name in an XML element.
Equal Compares two XML element objects for equality.
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
Escape Replaces invalid XML characters in a string with their valid XML equivalent.
GetHashCode
(inherited from System.Object)
See base class member description: System.Object.GetHashCode

Derived from System.Object, the primary base class for all objects.
GetType
(inherited from System.Object)
See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
IsValidAttributeName Determines whether a string is a valid attribute name.
IsValidAttributeValue Determines whether a string is a valid attribute value.
IsValidTag Determines whether a string is a valid tag.
IsValidText Determines whether a string is valid as text within an XML element.
SearchForChildByTag Finds a child by its tag name.
SearchForTextOfTag Finds a child by its tag name and returns the contained text.
ToString Overridden:
Produces a string representation of an XML element and its constituent attributes, child elements, and text.
Protected Methods
Finalize
(inherited from System.Object)
See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)
See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:


System.Security.SecurityElement Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the SecurityElement class with the specified tag.
C# Syntax:
public SecurityElement(
   string tag
);
Parameters:

tag

The tag name of an XML element.

Exceptions
Exception Type Condition
ArgumentNullException The tag parameter is null.
ArgumentException The tag parameter is invalid in XML.
Remarks
The tag parameter must consist of a valid XML tag name. Use SecurityElement.Escape to remove invalid characters from the string.

Return to top


Overloaded ctor #2
Summary
Initializes a new instance of the SecurityElement class with the specified tag and text.
C# Syntax:
public SecurityElement(
   string tag,
   string text
);
Parameters:

tag

The tag name of the XML element.

text

The text content within the element.

Exceptions
Exception Type Condition
ArgumentNullException The tag parameter is null.
ArgumentException The tag parameter or text parameter is invalid in XML.
Remarks
If the text parameter is null this constructor produces an element identical to the default constructor.

Return to top


Property: Attributes (read-write)
Summary
Gets or sets the attributes of an XML element as name/value pairs.
C# Syntax:
public Hashtable Attributes {get; set;}
Exceptions
Exception Type Condition
ArgumentException The name or value of the Hashtable object is invalid.
Remarks
Each attribute is stored in the Hashtable as a name/value pair.

Names and values in attributes should contain only valid XML attribute characters. Use SecurityElement.Escape to remove invalid characters from the string.

There is no support for quoted strings, so strings for name/value pairs should not contain quotes or other characters requiring quoting.

Return to top


Property: Children (read-write)
Summary
Gets or sets the array of child elements of the XML element.
C# Syntax:
public ArrayList Children {get; set;}
Exceptions
Exception Type Condition
ArgumentNullException A child of the XML parent node is null.
Remarks
If a SecurityElement contains both SecurityElement.Text and SecurityElement.Children, SecurityElement.Text will appear first.

Return to top


Property: Tag (read-write)
Summary
Gets or sets the tag name of an XML element.
C# Syntax:
public string Tag {get; set;}
Exceptions
Exception Type Condition
ArgumentNullException The tag is null.
ArgumentException The tag is not valid in XML.
Remarks
In XML, the tag appears in the script as appears below:

<tag attributes>text</tag>

If this element has child elements, the children will replace text .

Assign only valid XML tag strings to this property. Use SecurityElement.Escape to remove invalid characters from the string.

Return to top


Property: Text (read-write)
Summary
Gets or sets the text within an XML element.
C# Syntax:
public string Text {get; set;}
Exceptions
Exception Type Condition
ArgumentException The text is not valid in XML.
Remarks
The text should not contain XML special characters. Use SecurityElement.Escape to remove invalid characters from the string.

If a SecurityElement contains both SecurityElement.Text and SecurityElement.Children, SecurityElement.Text will appear first.

Return to top


Method: AddAttribute(
   string name,
   string value
)
Summary
Adds a name/value attribute to an XML element.
C# Syntax:
public void AddAttribute(
   string name,
   string value
);
Parameters:

name

The name of the attribute.

value

The value of the attribute.

Exceptions
Exception Type Condition
ArgumentNullException The name parameter or value parameter is null.
ArgumentException The name parameter or value parameter is invalid in XML.

-or-

An attribute with the name specified by the name parameter already exists.

Remarks
Names and values in attributes should only contain valid XML attribute characters. XML attribute names must be unique. Use SecurityElement.Escape to remove invalid characters from the string.

There is no support for quoted strings, so strings for name/value pairs should not contain quotes or other characters requiring quoting.

Return to top


Method: AddChild(
   SecurityElement child
)
Summary
Adds a child element to the XML element.
C# Syntax:
public void AddChild(
   SecurityElement child
);
Parameters:

child

The child element to add.

Exceptions
Exception Type Condition
ArgumentNullException The child parameter is null.
Remarks
The child element is added following any previously existing child elements.

Return to top


Method: Attribute(
   string name
)
Summary
Finds an attribute by name in an XML element.
C# Syntax:
public string Attribute(
   string name
);
Parameters:

name

The name of the attribute for which to search.

Return Value:
The value associated with the named attribute, or null if no attribute with name exists.
Exceptions
Exception Type Condition
ArgumentNullException The name parameter is null.
Remarks
With XML as follows, Attribute("B") would return "456".

<thetag A="123" B="456" C="789">text</thetag>

Return to top


Method: Equal(
   SecurityElement other
)
Summary
Compares two XML element objects for equality.
C# Syntax:
public bool Equal(
   SecurityElement other
);
Parameters:

other

An XML element object to which to compare the current XML element object.

Return Value:
true if the tag, attribute names and values, child elements, and text fields in the current XML element are identical to their counterparts in the other parameter; otherwise, false.
Remarks
If there are child elements, comparison extends recursively to them.

There is no support for comparing different XML representations of the same characters.

Return to top


Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top


Method: Escape(
   string str
)
Summary
Replaces invalid XML characters in a string with their valid XML equivalent.
C# Syntax:
public static string Escape(
   string str
);
Parameters:

str

The string within which to escape invalid characters.

Return Value:
The input string with invalid characters replaced.
Remarks
Use this method to replace invalid characters in a string before using the string in a SecurityElement. If invalid characters are used in an SecurityElement without being escaped, an ArgumentException is thrown.

The following table shows the invalid XML characters and their escaped equivalents.



invalid XML Character Replaced With
"<" "&lt;"
">" "&gt;"
"\"" "&quot;"
"\'" "&apos;"
"&" "&amp;"

Return to top


Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~SecurityElement();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetHashCode()
Inherited
See base class member description: System.Object.GetHashCode
C# Syntax:
public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: IsValidAttributeName(
   string name
)
Summary
Determines whether a string is a valid attribute name.
C# Syntax:
public static bool IsValidAttributeName(
   string name
);
Parameters:

name

The attribute name to test for validity.

Return Value:
true if the name parameter is a valid XML attribute name; otherwise, false.
Remarks
This method can be used to test an attribute before adding it to a security element.

Return to top


Method: IsValidAttributeValue(
   string value
)
Summary
Determines whether a string is a valid attribute value.
C# Syntax:
public static bool IsValidAttributeValue(
   string value
);
Parameters:

value

The attribute value to test for validity.

Return Value:
true if the value parameter is a valid XML attribute value; otherwise, false.
Remarks
This method can be used to test an attribute before adding it to a security element.

Return to top


Method: IsValidTag(
   string tag
)
Summary
Determines whether a string is a valid tag.
C# Syntax:
public static bool IsValidTag(
   string tag
);
Parameters:

tag

The tag to test for validity.

Return Value:
true if the tag parameter is a valid XML tag; otherwise, false.
Remarks
This can be used to test a SecurityElement.Tag before setting it.

Return to top


Method: IsValidText(
   string text
)
Summary
Determines whether a string is valid as text within an XML element.
C# Syntax:
public static bool IsValidText(
   string text
);
Parameters:

text

The text to test for validity.

Return Value:
true if the text parameter is a valid XML text element; otherwise, false.
Remarks
This method can be used to test SecurityElement.Text before setting it.

Return to top


Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: SearchForChildByTag(
   string tag
)
Summary
Finds a child by its tag name.
C# Syntax:
public SecurityElement SearchForChildByTag(
   string tag
);
Parameters:

tag

The tag for which to search in child elements.

Return Value:
The first child XML element with the specified tag value, or null if no child element with tag exists.
Exceptions
Exception Type Condition
ArgumentNullException The tag parameter is null.
Remarks
With XML as follows, SearchForChildByTag("second") would return the child element <second> .

<thetag A="123" B="456" C="789"> <first>text1</first> <second>text2</second></thetag>

Return to top


Method: SearchForTextOfTag(
   string tag
)
Summary
Finds a child by its tag name and returns the contained text.
C# Syntax:
public string SearchForTextOfTag(
   string tag
);
Parameters:

tag

The tag for which to search in child elements.

Return Value:
The text contents of the first child element with the specified tag value.
Exceptions
Exception Type Condition
ArgumentNullException tag is null.
Remarks
This method is equivalent to the following:
              String SearchForTextOfTag(String tag) { 
                  SecurityElement element = this.SearchForChildByTag(tag);
                  return element.Text;
               }
                 
            

With XML as follows, SearchForTextOfTag("second") would return "text2".

<thetag A="123" B="456" C="789"> <first>text1</first> <second>text2</second></thetag>

Return to top


Overridden Method: ToString()
Summary
Produces a string representation of an XML element and its constituent attributes, child elements, and text.
C# Syntax:
public override string ToString();
Return Value:
The XML element and its contents.
Remarks
This method is useful in debugging to see the XML representation of the element.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.