mcs/class/System.Data/Documentation/en/ns-System.Xml.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <Namespace Name="System.Xml">
   3   <Docs>
   4     <summary>
   5       <attribution license="cc4" from="Microsoft" modified="false" />
   6       <para>The <see cref="N:System.Xml" /> namespace provides standards-based support for processing XML.</para>
   7     </summary>
   8     <remarks>
   9       <attribution license="cc4" from="Microsoft" modified="false" />
  10       <format type="text/html">
  11         <a href="#std" />
  12       </format>
  13       <format type="text/html">
  14         <h2>Supported standards </h2>
  15       </format>
  16       <para>The <see cref="N:System.Xml" /> namespace supports these standards:</para>
  17       <list type="bullet">
  18         <item>
  19           <para>XML 1.0, including DTD support: <see cref="http://www.w3.org/TR/2006/REC-xml-20060816/">http://www.w3.org/TR/2006/REC-xml-20060816/</see></para>
  20         </item>
  21         <item>
  22           <para>XML namespaces, both stream-level and DOM: <see cref="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</see></para>
  23         </item>
  24         <item>
  25           <para>XML schemas: <see cref="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</see> </para>
  26         </item>
  27         <item>
  28           <para>XPath expressions: <see cref="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</see> </para>
  29         </item>
  30         <item>
  31           <para>XSLT transformations: <see cref="http://www.w3.org/TR/xslt">http://www.w3.org/TR/xslt</see> </para>
  32         </item>
  33         <item>
  34           <para>DOM Level 1 Core: <see cref="http://www.w3.org/TR/REC-DOM-Level-1/">http://www.w3.org/TR/REC-DOM-Level-1/</see> </para>
  35         </item>
  36         <item>
  37           <para>DOM Level 2 Core: <see cref="http://www.w3.org/TR/DOM-Level-2/">http://www.w3.org/TR/DOM-Level-2/</see> </para>
  38         </item>
  39       </list>
  40       <para>See the section <format type="text/html"><a href="#diff">Differences from the W3C specs</a></format> for two cases in which the XML classes differ from the W3C recommendations.</para>
  41       <format type="text/html">
  42         <a href="#related" />
  43       </format>
  44       <format type="text/html">
  45         <h2>Related namespaces</h2>
  46       </format>
  47       <para>The .NET Framework also provides other namespaces for XML-related operations. For a list, descriptions, and links, see the <see cref="http://msdn.microsoft.com/library/gg145036.aspx">System.Xml Namespaces</see> webpage.</para>
  48       <format type="text/html">
  49         <a href="#async" />
  50       </format>
  51       <format type="text/html">
  52         <h2>Processing XML asynchronously </h2>
  53       </format>
  54       <para>The <see cref="T:System.Xml.XmlReader" /> and <see cref="T:System.Xml.XmlWriter" /> classes include a number of asynchronous methods that are based on the <format type="text/html"><a href="db854f91-ccef-4035-ae4d-0911fde808c7">Visual Studio asynchronous programming model</a></format>. These methods can be identified by the string "Async" at the end of their names. With these methods, you can write asynchronous code that's similar to your synchronous code, and you can migrate your existing synchronous code to asynchronous code easily.</para>
  55       <list type="bullet">
  56         <item>
  57           <para>Use the asynchronous methods in apps where there is significant network stream latency. Avoid using the asynchronous APIs for memory stream or local file stream read/write operations. The input stream, <see cref="T:System.Xml.XmlTextReader" />, and <see cref="T:System.Xml.XmlTextWriter" /> should support asynchronous operations as well. Otherwise, threads will still be blocked by I/O operations.</para>
  58         </item>
  59         <item>
  60           <para>We don't recommend mixing synchronous and asynchronous function calls, because you might forget to use the await keyword or use a synchronous API where an asynchronous one is necessary.</para>
  61         </item>
  62         <item>
  63           <para>Do not set the <see cref="P:System.Xml.XmlReaderSettings.Async" /> or <see cref="P:System.Xml.XmlWriterSettings.Async" /> flag to true if you don't intend to use an asynchronous method.</para>
  64         </item>
  65         <item>
  66           <para>If you forget to specify the await keyword when you call an asynchronous method, the results are non-deterministic: You might receive the result you expected or an exception.</para>
  67         </item>
  68         <item>
  69           <para>When an <see cref="T:System.Xml.XmlReader" /> object is reading a large text node, it might cache only a partial text value and return the text node, so retrieving the <see cref="P:System.Xml.XmlReader.Value" /> property might be blocked by an I/O operation. Use the <see cref="M:System.Xml.XmlReader.GetValueAsync" /> method to get the text value in asynchronous mode, or use the <see cref="M:System.Xml.XmlReader.ReadValueChunkAsync(System.Char[],System.Int32,System.Int32)" /> method to read a large text block in chunks.</para>
  70         </item>
  71         <item>
  72           <para>When you use an <see cref="T:System.Xml.XmlWriter" /> object, call the <see cref="M:System.Xml.XmlWriter.FlushAsync" /> method before calling <see cref="M:System.Xml.XmlWriter.Close" /> to avoid blocking an I/O operation.</para>
  73         </item>
  74       </list>
  75       <format type="text/html">
  76         <a href="#diff" />
  77       </format>
  78       <format type="text/html">
  79         <h2>Differences from the W3C specs</h2>
  80       </format>
  81       <para>In two cases that involve constraints on model group schema components, the <see cref="N:System.Xml" /> namespace differs from the W3C recommendations.</para>
  82       <para>Consistency in element declarations:</para>
  83       <para>In some cases, when substitution groups are used, the <see cref="N:System.Xml" /> implementation does not satisfy the "Schema Component Constraint: Element Declarations Consistent," which is described in the <see cref="http://go.microsoft.com/fwlink/?LinkId=137029">Constraints on Model Group Schema Components</see> section of the W3C spec.</para>
  84       <para>For example, the following schema includes elements that have the same name but different types in the same content model, and substitution groups are used. This should cause an error, but <see cref="N:System.Xml" /> compiles and validates the schema without errors. </para>
  85       <code>&lt;?xml version="1.0" encoding="utf-8" ?&gt;
  86 &lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"&gt;
  87
  88    &lt;xs:element name="e1" type="t1"/&gt;
  89    &lt;xs:complexType name="t1"/&gt;
  90
  91    &lt;xs:element name="e2" type="t2" substitutionGroup="e1"/&gt;
  92       &lt;xs:complexType name="t2"&gt;
  93          &lt;xs:complexContent&gt;
  94             &lt;xs:extension base="t1"&gt;
  95          &lt;/xs:extension&gt;
  96       &lt;/xs:complexContent&gt;
  97    &lt;/xs:complexType&gt;
  98
  99    &lt;xs:complexType name="t3"&gt;
 100       &lt;xs:sequence&gt;
 101          &lt;xs:element ref="e1"/&gt;
 102          &lt;xs:element name="e2" type="xs:int"/&gt;
 103       &lt;/xs:sequence&gt;
 104    &lt;/xs:complexType&gt;
 105 &lt;/xs:schema&gt;</code>
 106       <para>In this schema, type t3 contains a sequence of elements. Because of the substitution, the reference to element e1 from the sequence can result either in element e1 of type t1 or in element e2 of type t2. The latter case would result in a sequence of two e2 elements, where one is of type t2 and the other is of type xs:int. </para>
 107       <para>Unique particle attribution:</para>
 108       <para>Under the following conditions, the <see cref="N:System.Xml" /> implementation does not satisfy the "Schema Component Constraint: Unique Particle Attribution," which is described in the <see cref="http://go.microsoft.com/fwlink/?LinkId=137029">Constraints on Model Group Schema Components</see> section of the W3C spec.</para>
 109       <list type="bullet">
 110         <item>
 111           <para>One of the elements in the group references another element.</para>
 112         </item>
 113         <item>
 114           <para>The referenced element is a head element of a substitution group.</para>
 115         </item>
 116         <item>
 117           <para>The substitution group contains an element that has the same name as one of the elements in the group.</para>
 118         </item>
 119         <item>
 120           <para>The cardinality of the element that references the substitution group head element and the element with the same name as a substitution group element is not fixed (minOccurs &lt; maxOccurs).</para>
 121         </item>
 122         <item>
 123           <para>The definition of the element that references the substitution group precedes the definition of the element with the same name as a substitution group element.</para>
 124         </item>
 125       </list>
 126       <para>For example, in the schema below the content model is ambiguous and should cause a compilation error, but <see cref="N:System.Xml" /> compiles the schema without errors.</para>
 127       <code>&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"&gt;
 128
 129   &lt;xs:element name="e1" type="xs:int"/&gt;
 130   &lt;xs:element name="e2" type="xs:int" substitutionGroup="e1"/&gt;
 131
 132   &lt;xs:complexType name="t3"&gt;
 133     &lt;xs:sequence&gt;
 134       &lt;xs:element ref="e1" minOccurs="0" maxOccurs="1"/&gt;
 135       &lt;xs:element name="e2" type="xs:int" minOccurs="0" maxOccurs="1"/&gt;
 136     &lt;/xs:sequence&gt;
 137   &lt;/xs:complexType&gt;
 138
 139   &lt;xs:element name="e3" type="t3"/&gt;
 140 &lt;/xs:schema&gt;</code>
 141       <para>If you try to validate the following XML against the schema above, the validation will fail with the following message: "The element 'e3' has invalid child element 'e2'." and an <see cref="T:System.Xml.Schema.XmlSchemaValidationException" /> exception will be thrown. </para>
 142       <code>&lt;e3&gt;
 143   &lt;e2&gt;1&lt;/e2&gt;
 144   &lt;e2&gt;2&lt;/e2&gt;
 145 &lt;/e3&gt;</code>
 146       <para>To work around this problem, you can swap element declarations in the XSD document. For example:</para>
 147       <code>&lt;xs:sequence&gt;
 148   &lt;xs:element ref="e1" minOccurs="0" maxOccurs="1"/&gt;
 149   &lt;xs:element name="e2" type="xs:int" minOccurs="0" maxOccurs="1"/&gt;
 150 &lt;/xs:sequence&gt;</code>
 151       <para>becomes this:</para>
 152       <code>&lt;xs:sequence&gt;
 153   &lt;xs:element name="e2" type="xs:int" minOccurs="0" maxOccurs="1"/&gt;
 154   &lt;xs:element ref="e1" minOccurs="0" maxOccurs="1"/&gt;
 155 &lt;/xs:sequence&gt;</code>
 156       <para>Here's another example of the same issue:</para>
 157       <code>&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"&gt;
 158    &lt;xs:element name="e1" type="xs:string"/&gt;
 159    &lt;xs:element name="e2" type="xs:string" substitutionGroup="e1"/&gt;
 160
 161    &lt;xs:complexType name="t3"&gt;
 162       &lt;xs:sequence&gt;
 163          &lt;xs:element ref="e1" minOccurs="0" maxOccurs="1"/&gt;
 164          &lt;xs:element name="e2" type="xs:int" minOccurs="0" maxOccurs="1"/&gt;
 165       &lt;/xs:sequence&gt;
 166    &lt;/xs:complexType&gt;
 167    &lt;xs:element name="e3" type="t3"/&gt;
 168 &lt;/xs:schema&gt;</code>
 169       <para>If you try to validate the following XML against the schema above, the validation will fail with the following exception: "Unhandled Exception: System.Xml.Schema.XmlSchemaValidationException: The 'e2' el element is invalid - The value 'abc' is invalid according to its datatype 'http://www.w3.org/2001/XMLSchema:int' - The string 'abc' is not a valid Int32 value."\</para>
 170       <code>&lt;e3&gt;&lt;e2&gt;abc&lt;/e2&gt;&lt;/e3&gt;</code>
 171       <format type="text/html">
 172         <a href="#security" />
 173       </format>
 174       <format type="text/html">
 175         <h2>Security considerations</h2>
 176       </format>
 177       <para>The types and members in the <see cref="N:System.Xml" /> namespace rely on the <format type="text/html"><a href="9a9621d7-8883-4a4f-a874-65e8e09e20a6">.NET Framework security system</a></format>. The following sections discuss security issues that are specific to XML technologies. For details, see the specific classes and members mentioned, and visit the <see cref="http://go.microsoft.com/fwlink/?linkid=42458">XML Developer Center</see> for technical information, downloads, newsgroups, and other resources for XML developers.</para>
 178       <para>Also note that when you use the <see cref="N:System.Xml" /> types and members, if the XML contains data that has potential privacy implications, you need to implement your app in a way that respects your end users' privacy.</para>
 179       <para>External access</para>
 180       <para>Several XML technologies have the ability to retrieve other documents during processing. For example, a document type definition (DTD) can reside in the document being parsed. The DTD can also live in an external document that is referenced by the document being parsed. The XML Schema definition language (XSD) and XSLT technologies also have the ability to include information from other files. These external resources can present some security concerns. For example, you'll want to ensure that your app retrieves files only from trusted sites, and that the file it retrieves doesn't contain malicious data.</para>
 181       <para>The <see cref="T:System.Xml.XmlUrlResolver" /> class is used to load XML documents and to resolve external resources such as entities, DTDs, or schemas, and import or include directives.</para>
 182       <para>You can override this class and specify the <see cref="T:System.Xml.XmlResolver" /> object to use. Use the <see cref="T:System.Xml.XmlSecureResolver" /> class if you need to open a resource that you do not control, or that is untrusted. The <see cref="T:System.Xml.XmlSecureResolver" /> wraps an <see cref="T:System.Xml.XmlResolver" /> and allows you to restrict the resources that the underlying <see cref="T:System.Xml.XmlResolver" /> has access to.</para>
 183       <para>Denial of service</para>
 184       <para>The following scenarios are considered to be less vulnerable to denial of service attacks because the <see cref="N:System.Xml" /> classes provide a means of protection from such attacks. </para>
 185       <list type="bullet">
 186         <item>
 187           <para>Parsing text XML data.</para>
 188         </item>
 189         <item>
 190           <para>Parsing binary XML data if the binary XML data was generated by Microsoft SQL Server.</para>
 191         </item>
 192         <item>
 193           <para>Writing XML documents and fragments from data sources to the file system, streams, a <see cref="T:System.IO.TextWriter" />, or a <see cref="T:System.Text.StringBuilder" />.</para>
 194         </item>
 195         <item>
 196           <para>Loading documents into the Document Object Model (DOM) object if you are using an <see cref="T:System.Xml.XmlReader" /> object and <see cref="P:System.Xml.XmlReaderSettings.DtdProcessing" /> set to <see cref="F:System.Xml.DtdProcessing.Prohibit" />.</para>
 197         </item>
 198         <item>
 199           <para>Navigating the DOM object.</para>
 200         </item>
 201       </list>
 202       <para>The following scenarios are not recommended if you are concerned about denial of service attacks, or if you are working in an untrusted environment.</para>
 203       <list type="bullet">
 204         <item>
 205           <para>DTD processing.</para>
 206         </item>
 207         <item>
 208           <para>Schema processing. This includes adding an untrusted schema to the schema collection, compiling an untrusted schema, and validating by using an untrusted schema.</para>
 209         </item>
 210         <item>
 211           <para>XSLT processing.</para>
 212         </item>
 213         <item>
 214           <para>Parsing any arbitrary stream of user supplied binary XML data.</para>
 215         </item>
 216         <item>
 217           <para>DOM operations such as querying, editing, moving sub-trees between documents, and saving DOM objects.</para>
 218         </item>
 219       </list>
 220       <para>If you are concerned about denial of service issues or if you are dealing with untrusted sources, do not enable DTD processing. This is disabled by default on <see cref="T:System.Xml.XmlReader" /> objects that the <see cref="Overload:System.Xml.XmlReader.Create" /> method creates. </para>
 221       <block subset="none" type="note">
 222         <para>The <see cref="T:System.Xml.XmlTextReader" /> allows DTD processing by default. Use the <see cref="P:System.Xml.XmlTextReader.DtdProcessing" /> property to disable this feature.</para>
 223       </block>
 224       <para>If you have DTD processing enabled, you can use the <see cref="T:System.Xml.XmlSecureResolver" /> class to restrict the resources that the <see cref="T:System.Xml.XmlReader" /> can access. You can also design your app so that the XML processing is memory and time constrained. For example, you can configure timeout limits in your ASP.NET app.</para>
 225       <para>Processing considerations</para>
 226       <para>Because XML documents can include references to other files, it is difficult to determine how much processing power is required to parse an XML document. For example, XML documents can include a DTD. If the DTD contains nested entities or complex content models, it could take an excessive amount of time to parse the document.</para>
 227       <para>When using <see cref="T:System.Xml.XmlReader" />, you can limit the size of the document that can be parsed by setting the <see cref="P:System.Xml.XmlReaderSettings.MaxCharactersInDocument" /> property. You can limit the number of characters that result from expanding entities by setting the <see cref="P:System.Xml.XmlReaderSettings.MaxCharactersFromEntities" /> property. See the appropriate reference topics for examples of setting these properties.</para>
 228       <para>The XSD and XSLT technologies have additional capabilities that can affect processing performance. For example, it is possible to construct an XML schema that requires a substantial amount of time to process when evaluated over a relatively small document. It is also possible to embed script blocks within an XSLT style sheet. Both cases pose a potential security threat to your app.</para>
 229       <para>When creating an app that uses the <see cref="T:System.Xml.Xsl.XslCompiledTransform" /> class, you should be aware of the following items and their implications:</para>
 230       <list type="bullet">
 231         <item>
 232           <para>XSLT scripting is disabled by default. XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. </para>
 233         </item>
 234         <item>
 235           <para>The XSLT document() function is disabled by default. If you enable the document() function, restrict the resources that can be accessed by passing an <see cref="T:System.Xml.XmlSecureResolver" /> object to the <see cref="Overload:System.Xml.Xsl.XslCompiledTransform.Transform" /> method.</para>
 236         </item>
 237         <item>
 238           <para>Extension objects are enabled by default. If an <see cref="T:System.Xml.Xsl.XsltArgumentList" /> object that contains extension objects is passed to the <see cref="M:System.Xml.Xsl.XslCompiledTransform.Transform(System.String,System.String)" /> method, the extension objects are used.</para>
 239         </item>
 240         <item>
 241           <para>XSLT style sheets can include references to other files and embedded script blocks. A malicious user can exploit this by supplying you with data or style sheets that, when executed, can cause your system to process until the computer runs low on resources.</para>
 242         </item>
 243         <item>
 244           <para>XSLT apps that run in a mixed trust environment can result in style sheet spoofing. For example, a malicious user can load an object with a harmful style sheet and hand it off to another user who subsequently calls the <see cref="M:System.Xml.Xsl.XslCompiledTransform.Transform(System.String,System.String)" /> method and executes the transformation.</para>
 245         </item>
 246       </list>
 247       <para>These security issues can be mitigated by not enabling scripting or the document() function unless the style sheet comes from a trusted source, and by not accepting <see cref="T:System.Xml.Xsl.XslCompiledTransform" /> objects, XSLT style sheets, or XML source data from an untrusted source.</para>
 248       <para>Exception handling</para>
 249       <para>Exceptions thrown by lower level components can disclose path information that you do not want exposed to the app. Your apps must catch exceptions and process them appropriately.</para>
 250     </remarks>
 251   </Docs>
 252 </Namespace>