XML System.Xml [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] 1.0.5000.0 2.0.0.0 4.0.0.0 All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe. System.Object The class is functionally equivalent to the class, but it supports XML standards. The type system is based on the XML Schema definition language (XSD) schema type, and the values returned are always locale-independent.

Encoding and decoding

Element and attribute names or ID values are limited to a range of XML characters according to the W3C XML 1.0 recommendation. When names contain invalid characters, you can use the and methods in this class to translate them into valid XML names. For example, if you want to use the column heading "Order Detail" in a database, the database allows the space between the two words. However, in XML, the space between "Order" and "Detail" is considered an invalid XML character. You have to convert it into an escaped hexadecimal encoding and decode it later. You can use the method with the class to ensure the names being written are valid XML names. The following C# code converts the name "Order Detail" into a valid XML name and writes the element <Order_0x0020_Detail>My order</Order_0x0020_Detail>. writer.WriteElementString(XmlConvert.EncodeName("Order Detail"),"My order"); The following methods perform encoding and decoding. Method Description Takes a name and returns the encoded name along with any invalid character that is replaced by an escape string. This method allows colons in any position, which means that the name may still be invalid according to the W3C Namespaces in XML 1.0 recommendation. Takes a name and returns the encoded name. Same as except that it also encodes the colon character, guaranteeing that the name can be used as the LocalName part of a namespace-qualified name. Reverses the transformation for all the encoding methods.

Name validation

The class contains two methods that check the characters in an element or attribute name and verify that the name conforms to the rules set by the W3C XML 1.0 recommendation: checks the characters and verifies that the name is valid. The method returns the name if it's valid, and throws an exception if it isn't. performs the same validation, but accepts non-qualified names. The contains additional methods that validate tokens, white-space characters, public IDs, and other strings.

Data type conversion

also provides methods that enable you to convert data from a string to a strongly typed data type. For example, the method converts a string to its equivalent. This is useful because most methods in the class return data as a string. After the data is read, it can be converted to the proper data type before being used. The overloads provide the complementary operation by converting strongly typed data to strings. For example, this is useful when you want to add the data to text boxes on a webpage. Locale settings are not taken into account during data conversion. The data types are based on the XML Schema (XSD) data types.
Encodes and decodes XML names, and provides methods for converting between common language runtime types and XML Schema definition language (XSD) types. When converting data types, the values returned are locale-independent.
Constructor 1.0.5000.0 2.0.0.0 4.0.0.0 To be added. Initializes a new instance of the class. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String The following example demonstrates the valid and invalid character formats for decoding. using System; using System.Xml; public class App { public static void Main() { Console.WriteLine( "{0} : {1} : {2}", // _x0069_ decodes to i XmlConvert.DecodeName("Order #1_x0069_"), // missing beginning _ XmlConvert.DecodeName("Order #1x0069_"), // short form XmlConvert.DecodeName("Order #1_x69_") ); } } The output is Order #1i : Order #1x0069_ : Order #1_x69_ The names are decoded using the following rules: Names are decoded from left to right. Any sequence _x (where HHHH stands for a valid, four digit hexadecimal UCS-2 code) that has not been decoded is transformed into the corresponding Unicode 2.1 (Unicode 3.0 if supported by the application) character. No shortforms are recognized. They are passed on without translation. For example, _x20_ or __ are not decoded. The actual encoding of the character is application-specific. For example, Order_x0020_Details becomes Order Details. Even escaped characters that are invalid in XML names will be recognized and decoded. Decodes a name. This method does the reverse of the and methods. The decoded name. The name to be transformed. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String The following example compares the , , and methods when the name to be encoded is "7:+". using System; using System.Xml; public class App { public static void Main() { Console.WriteLine( "LocalName {0}", XmlConvert.EncodeLocalName("7:+") ); Console.WriteLine( "Name {0}", XmlConvert.EncodeName("7:+") ); Console.WriteLine( "NmToken {0}", XmlConvert.EncodeNmToken("7:+") ); } } The output is LocalName _x0037__x003A__x002B_ Name _x0037_:_x002B_ NmToken 7:_x002B_ This method is similar to the method except that it encodes the colon character, which guarantees that the name can be used as the local name part of a namespace qualified name. For example, if you passed this method the invalid name a:b, it returns a_x003a_b, which is a valid local name. If is null or String.Empty then you get the same value returned. Converts the name to a valid XML local name. The encoded name. The name to be encoded. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String See the method for an example comparing the , , and methods. This method translates invalid characters, such as spaces or half-width Katakana, that need to be mapped to XML names without the support or presence of schemas. The invalid characters are translated into escaped numeric entity encodings. The escape character is "_". Any XML name character that does not conform to the XML 1.0 spec (fourth edition) recommendation is escaped as _xHHHH_. The HHHH string stands for the four-digit hexadecimal UCS-2 code for the character in most significant bit first order. For example, the name Order Details is encoded as Order_x0020_Details. The underscore character does not need to be escaped unless it is followed by a character sequence that together with the underscore can be misinterpreted as an escape sequence when decoding the name. For example, Order_Details is not encoded, but Order_x0020_ is encoded as Order_x005f_x0020_. No shortforms are allowed. For example, the forms _x20_ and __ are not generated. This method guarantees the name is valid according to the XML specification. It allows colons in any position, which means the name may still be invalid according to the W3C Namespace Specification. To guarantee it is a valid namespace qualified name use for the prefix and local name parts and join the result with a colon. Converts the name to a valid XML name. Returns the name with any invalid characters replaced by an escape string. A name to be translated. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String See the method for an example comparing the , , and methods. This method guarantees that the name is valid according to the XML specification. For example, if you passed this method the invalid name 70+, it returns 70_x002b_ which is a valid XML name. If is null or String.Empty then you get the same value returned. Verifies the name is valid according to the XML specification. The encoded name. The name to be encoded. 0 Method 4.0.0.0 System.Boolean To be added. Checks whether the passed-in character is a valid non-colon character type. Returns true if the character is a valid non-colon character type; otherwise, false. The character to verify as a non-colon character. Method 4.0.0.0 System.Boolean To be added. Returns the passed-in character instance if the character in the argument is a valid public id character, otherwise null. Returns the passed-in character if the character is a valid public id character, otherwise null. object to validate. Method 4.0.0.0 System.Boolean For details about allowed characters, see the XML 1.0 spec (fourth edition) recommendation. Checks if the passed-in character is a valid Start Name Character type. true if the character is a valid Start Name Character type; otherwise, false. The character to validate. Method 4.0.0.0 System.Boolean For details about allowed characters, see the XML 1.0 spec (fourth edition) recommendation. Checks if the passed-in character is a valid XML whitespace character. true if the passed in character is a valid XML whitespace character; otherwise false. The character to validate. Method 4.0.0.0 System.Boolean For details about allowed characters, see the XML 1.0 spec (fourth edition) recommendation. Checks if the passed-in character is a valid XML character. true if the passed in character is a valid XML character; otherwise false. The character to validate. Method 4.0.0.0 System.Boolean To be added. Checks if the passed-in surrogate pair of characters is a valid XML character. true if the passed in surrogate pair of characters is a valid XML character; otherwise false. The surrogate character to validate. The surrogate character to validate. Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Boolean is a null reference. does not represent a value. Valid strings are "1" or "true" for true and "0" or "false" for false. Converts the to a equivalent. A Boolean value, that is, true or false. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Byte This method calls (, |, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. A Byte equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Char This method calls (). is a null reference. contains more than one character. Converts the to a equivalent. A Char representing the single character. The string containing a single character to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Obsolete System.DateTime is a null reference. is or is not in the correct format. The method is obsolete in the 2.0 version of the .NET Framework and has been replaced by the method. Converts the to a equivalent. A DateTime equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.DateTime This method calls (, , , |). Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. is a null reference. or is . -or- does not contain a date and time that corresponds to . The format structure to apply to the converted DateTime. Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. The string is validated against this format. Converts the to a equivalent. A DateTime equivalent of the string. The string to convert. The format structure to apply to the converted DateTime. Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. The string is validated against this format. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.DateTime is a null reference. or an element of is . -or- does not contain a date and time that corresponds to any of the elements of . The following example converts a to a and writes the result to the console. using System; using System.Xml; public class App { public static void Main() { String someDate = "1966-09-19T03:45:11Z"; String[] datetimeFormats = new String[] {"HH:mm:ss", "yyyy-MM-ddTHH:mm:ssZ"}; DateTime dateTime = XmlConvert.ToDateTime(someDate, datetimeFormats); Console.WriteLine( "{0}", dateTime.ToString() ); } } The output is 9/18/1966 8:45:11 PM An array containing the format structures to apply to the converted DateTime. Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. This method allows multiple formats for the string to be validated against. Converts the to a equivalent. A DateTime equivalent of the string. The string to convert. An array containing the format structures to apply to the converted DateTime. Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. 0 Method 2.0.0.0 4.0.0.0 System.DateTime To be added. Converts the to a using the specified A equivalent of the . The value to convert. One of the values that specify whether the date should be converted to local time or preserved as Coordinated Universal Time (UTC), if it is a UTC date. Method 2.0.0.0 4.0.0.0 System.DateTimeOffset When more than seven digits are specified for fractional seconds, the value is rounded. For example, 00000004 becomes 0000000 and 00000005 becomes 0000001. Converts the supplied to a equivalent. The equivalent of the supplied string. The string to convert. Method 2.0.0.0 4.0.0.0 System.DateTimeOffset If the offset specified within the input string will cause an overflow in the deserialized representation of the DateTimeOffset, a FormatException is thrown. When more than seven digits are specified for fractional seconds, the value is rounded. For example, 00000004 becomes 0000000 and 00000005 becomes 0000001. Converts the supplied to a equivalent. The equivalent of the supplied string. The string to convert. The format from which is converted. The format parameter can be any subset of the W3C Recommendation for the XML dateTime type. (For more information see http://www.w3.org/TR/xmlschema-2/#dateTime.) The string is validated against this format. Method 2.0.0.0 4.0.0.0 System.DateTimeOffset If the offset specified within the input string will cause an overflow in the deserialized representation of the DateTimeOffset, a FormatException is thrown. When more than seven digits are specified for fractional seconds, the value is rounded. For example, 00000004 becomes 0000000 and 00000005 becomes 0000001. Converts the supplied to a equivalent. The equivalent of the supplied string. The string to convert. An array of formats from which can be converted. Each format in can be any subset of the W3C Recommendation for the XML dateTime type. (For more information see http://www.w3.org/TR/xmlschema-2/#dateTime.) The string is validated against one of these formats. Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Decimal This method calls (, |||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. A Decimal equivalent of the string. The string to convert. 1 ExtendedNumerics Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Double is a null reference. is not in the correct format. represents a number less than or greater than . If is INF or -INF, this method returns Double.PositiveInfinity or Double.NegativeInfinity respectively. Converts the to a equivalent. A Double equivalent of the string. The string to convert. 1 ExtendedNumerics Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Guid To be added. Converts the to a equivalent. A Guid equivalent of the string. The string to convert. Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Int16 This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. An Int16 equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Int32 This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. An Int32 equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Int64 This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. An Int64 equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.SByte This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. An SByte equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Single is a null reference. is not in the correct format. represents a number less than or greater than . If is INF or -INF, this method returns Single.PositiveInfinity or Single.NegativeInfinity respectively. Converts the to a equivalent. A Single equivalent of the string. The string to convert. 1 ExtendedNumerics Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String To be added. Converts the to a . A string representation of the Boolean, that is, "true" or "false". The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(, ). Converts the to a . A string representation of the Byte. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(). Converts the to a . A string representation of the Char. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.Obsolete System.String The method is obsolete in the 2.0 version of the .NET Framework and has been replaced with the method. Converts the to a . A string representation of the DateTime in the format yyyy-MM-ddTHH:mm:ss where 'T' is a constant literal. The value to convert. 0 Method 2.0.0.0 4.0.0.0 System.String To be added. Converts the supplied to a . A representation of the supplied . The to be converted. Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(, ). Converts the to a . A string representation of the Decimal. The value to convert. 1 ExtendedNumerics Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String If is Double.PositiveInfinity or Double.NegativeInfinity, this method returns the string INF or -INF respectively. Converts the to a . A string representation of the Double. The value to convert. 1 ExtendedNumerics Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String To be added. Converts the to a . A string representation of the Guid. The value to convert. Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(, ). Converts the to a . A string representation of the Int16. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(, ). Converts the to a . A string representation of the Int32. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(, ). Converts the to a . A string representation of the Int64. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.String This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls .ToString(, ). Converts the to a . A string representation of the SByte. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String If is Single.PositiveInfinity or Single.NegativeInfinity, this method returns the string INF or -INF respectively. Converts the to a . A string representation of the Single. The value to convert. 1 ExtendedNumerics Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String To be added. The following example converts a to a and writes the result to the console. using System; using System.Xml; public class App { public static void Main() { TimeSpan timeSpan = new TimeSpan(3, 11, 59, 6, 128); Console.WriteLine( "{0}", XmlConvert.ToString(timeSpan) ); } } The output is P3DT11H59M6.128S Converts the to a . A string representation of the TimeSpan. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.String This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls .ToString(, ). Converts the to a . A string representation of the UInt16. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.String This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls .ToString(, ). Converts the to a . A string representation of the UInt32. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.String This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls .ToString(, ). Converts the to a . A string representation of the UInt64. The value to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String This method calls .ToString(, ). The format structure that defines how to display the converted string. Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. Converts the to a . A string representation of the DateTime in the specified format. The value to convert. The format structure that defines how to display the converted string. Valid formats include "yyyy-MM-ddTHH:mm:sszzzzzz" and its subsets. 0 Method 2.0.0.0 4.0.0.0 System.String To be added. Converts the to a using the specified. A equivalent of the . The value to convert. One of the values that specify how to treat the value. Method 2.0.0.0 4.0.0.0 System.String To be added. Converts the supplied to a in the specified format. A representation in the specified format of the supplied . The to be converted. The format to which is converted. The format parameter can be any subset of the W3C Recommendation for the XML dateTime type. (For more information see http://www.w3.org/TR/xmlschema-2/#dateTime.) Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.TimeSpan To be added. is not in the correct format to represent a value. Converts the to a equivalent. A TimeSpan equivalent of the string. The string to convert. The string format must conform to the W3C XML Schema Part 2: Datatypes recommendation for duration. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.UInt16 This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. A UInt16 equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.UInt32 This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. A UInt32 equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.CLSCompliant(false) System.UInt64 This member is not CLS-compliant. For a CLS-compliant alternative, use (). This method calls (, ||, ). is a null reference. is not in the correct format. represents a number less than or greater than . Converts the to a equivalent. A UInt64 equivalent of the string. The string to convert. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String is or . is not a valid XML name. This method can be used with the class in the following manner. try{ writer.WriteStartElement(XmlConvert.VerifyName("item"),"bar"); } catch(Exception e) { Console.WriteLine("error"); } Verifies that the name is a valid name according to the W3C Extended Markup Language recommendation. The name, if it is a valid XML name. The name to verify. 0 Method 1.0.5000.0 2.0.0.0 4.0.0.0 System.String If contains a colon, is thrown. is or . is not a valid XML qualified name. Verifies that the name is a valid NCName according to the W3C Extended Markup Language recommendation. An NCName is a name that cannot contain a colon. The name, if it is a valid NCName. The name to verify. 0 Method 2.0.0.0 4.0.0.0 System.String This method ensures that the name token follows the proper syntax for a valid NMTOKEN. It can be used in the following manner: try { writer.WriteStartElement(XmlConvert.VerifyNMTOKEN("abc"),"book"); } catch(Exception e) { Console.WriteLine("error"); } For more information on the NMTOKEN data type, see http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#NMTOKEN. Verifies that the string is a valid NMTOKEN according to the W3C XML Schema Part2: Datatypes recommendation The name token, if it is a valid NMTOKEN. The string you wish to verify. Method 4.0.0.0 System.String No other values than the passed in argument should be returned. The characters valid for public id do not vary between XML editions, so no XmlVersion overload is required. See XML 1.0 spec (fourth edition) production [13] PublidChar for details on the allowed characters If the parameter is null, an ArgumentNullException will be thrown. If any of the characters are not valid public id characters, an XmlException is thrown with information about the first invalid character encountered. Returns the passed in string instance if all the characters in the string argument are valid public id characters. Returns the passed-in string if all the characters in the argument are valid public id characters. that contains the id to validate. Method 2.0.0.0 4.0.0.0 System.String This method ensures that the name token follows the proper syntax for a valid token. It can be used in the following manner: try { writer.WriteStartElement(XmlConvert.VerifyTOKEN("abc"),"book"); } catch(Exception e) { Console.WriteLine("error"); } For more information on tokens, see http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#token. Verifies that the string is a valid token according to the W3C XML Schema Part2: Datatypes recommendation. The token, if it is a valid token. The string value you wish to verify. Method 4.0.0.0 System.String No other values than the passed in argument should be returned. The characters that are valid for whitespace do not vary between XML editions, so no xml version overload is required. See XML 1.0 spec (fourth edition) production [3] S for details on the allowed characters. If the parameter is null, an ArgumentNullException will be thrown. If any of the characters are not valid whitespace characters, an XmlException is thrown with information about the first invalid character encountered. Returns the passed-in string instance if all the characters in the string argument are valid whitespace characters. Returns the passed-in string instance if all the characters in the string argument are valid whitespace characters, otherwise null. to verify. Method 4.0.0.0 System.String No other values than the passed in argument should be returned. See XML 1.0 spec (fourth edition) production [2] Char for details on the allowed characters. If the parameter is null, an ArgumentNullException will be thrown. If any of the characters are not valid xml characters, an XmlException is thrown with information on the first invalid character encountered. Returns the passed-in string if all the characters and surrogate pair characters in the string argument are valid XML characters, otherwise null. Returns the passed-in string if all the characters and surrogate-pair characters in the string argument are valid XML characters, otherwise null. that contains characters to verify. 0