XDocument 類別概觀 (C#)XDocument Class Overview (C#)

本主題說明 XDocument 類別。This topic introduces the XDocument class.

XDocument 類別的概觀Overview of the XDocument class

XDocument 類別包含有效 XML 文件所需的資訊。The XDocument class contains the information necessary for a valid XML document. 這包括 XML 宣告、處理指示與註解。This includes an XML declaration, processing instructions, and comments.

請注意,如果您需要 XDocument 類別所提供的特定功能,您僅需要建立 XDocument 物件。Note that you only have to create XDocument objects if you require the specific functionality provided by the XDocument class. 在許多情況下,您可以直接使用 XElementIn many circumstances, you can work directly with XElement. 直接使用 XElement 是較簡單的程式設計模型。Working directly with XElement is a simpler programming model.

XDocument 是衍生自 XContainerXDocument derives from XContainer. 因此,它可以包含子節點。Therefore, it can contain child nodes. 不過,XDocument 物件可以有只有一個 XElement 子節點。However, XDocument objects can have only one child XElement node. 這會反映 XML 標準,也就是說 XML 文件中只能有一個根項目 (Root Element)。This reflects the XML standard that there can be only one root element in an XML document.

XDocument 的元件Components of XDocument

XDocument 可以包含下列項目:An XDocument can contain the following elements:

  • 一個 XDeclaration 物件。One XDeclaration object. XDeclaration 可讓您指定 XML 宣告的關聯部分:XML 版本、文件的編碼,以及 XML 文件是否是獨立的。XDeclaration enables you to specify the pertinent parts of an XML declaration: the XML version, the encoding of the document, and whether the XML document is stand-alone.

  • 一個 XElement 物件。One XElement object. 這是 XML 文件的根節點。This is the root node of the XML document.

  • 任何數目的 XProcessingInstruction 物件。Any number of XProcessingInstruction objects. 處理指示會將資訊傳達到處理 XML 的應用程式。A processing instruction communicates information to an application that processes the XML.

  • 任何數目的 XComment 物件。Any number of XComment objects. 這些註解將是根項目的同層級。The comments will be siblings to the root element. XComment 物件不得為清單中的第一個引數,因為對於 XML 文件而言,它不適用於開始註解。The XComment object cannot be the first argument in the list, because it is not valid for an XML document to start with a comment.

  • 一個適用於 DTD 的 XDocumentTypeOne XDocumentType for the DTD.

當您序列化 XDocument 時,即使 XDocument.Declarationnull,如果寫入器已將 Writer.Settings.OmitXmlDeclaration 設定為 false (預設值),則輸出將會有 XML 宣告。When you serialize an XDocument, even if XDocument.Declaration is null, the output will have an XML declaration if the writer has Writer.Settings.OmitXmlDeclaration set to false (the default).

根據預設,LINQ to XMLLINQ to XML 會將版本設定為 "1.0",並將編碼設定為 "utf-8"。By default, LINQ to XMLLINQ to XML sets the version to "1.0", and sets the encoding to "utf-8".

在沒有 XDocument 的情況下使用 XElementUsing XElement without XDocument

如先前所述,XElement 類別是 LINQ to XMLLINQ to XML 程式發展介面中的主要類別。As previously mentioned, the XElement class is the main class in the LINQ to XMLLINQ to XML programming interface. 在許多情況下,您的應用程式將不需要您建立文件。In many cases, your application will not require that you create a document. 您可以使用 XElement 類別來建立 XML 樹狀結構、在其中加入其他 XML 樹狀結構、修改 XML 樹狀結構,然後加以儲存。By using the XElement class, you can create an XML tree, add other XML trees to it, modify the XML tree, and save it.

使用 XDocumentUsing XDocument

若要建構 XDocument,請使用功能結構,如同您建構 XElement 物件時所執行的操作。To construct an XDocument, use functional construction, just like you do to construct XElement objects.

下列程式碼會建立 XDocument 物件及其所包含的相關聯物件。The following code creates an XDocument object and its associated contained objects.

XDocument d = new XDocument(  
    new XComment("This is a comment."),  
    new XProcessingInstruction("xml-stylesheet",  
        "href='mystyle.css' title='Compact' type='text/css'"),  
    new XElement("Pubs",  
        new XElement("Book",  
            new XElement("Title", "Artifacts of Roman Civilization"),  
            new XElement("Author", "Moreno, Jordao")  
        ),  
        new XElement("Book",  
            new XElement("Title", "Midieval Tools and Implements"),  
            new XElement("Author", "Gazit, Inbar")  
        )  
    ),  
    new XComment("This is another comment.")  
);  
d.Declaration = new XDeclaration("1.0", "utf-8", "true");  
Console.WriteLine(d);  
  
d.Save("test.xml");  

當您檢查 test.xml 檔案時,您會得到下列輸出:When you examine the file test.xml, you get the following output:

<?xml version="1.0" encoding="utf-8"?>  
<!--This is a comment.-->  
<?xml-stylesheet href='mystyle.css' title='Compact' type='text/css'?>  
<Pubs>  
  <Book>  
    <Title>Artifacts of Roman Civilization</Title>  
    <Author>Moreno, Jordao</Author>  
  </Book>  
  <Book>  
    <Title>Midieval Tools and Implements</Title>  
    <Author>Gazit, Inbar</Author>  
  </Book>  
</Pubs>  
<!--This is another comment.-->  

另請參閱See also