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