System.Xml.XmlWriter 類別

發行項
01/04/2024

類別 XmlWriter 會將 XML 數據寫入資料流、檔案、文字讀取器或字串。它支援 XML 1.0（第四版）和 XML 1.0（第三版）建議中的 W3C 可延伸標記語言（XML）和命名空間。

類別的成員 XmlWriter 可讓您：

驗證字元是否為合法 XML 字元，以及項目與屬性名稱是否為有效的 XML 名稱。
驗證 XML 文件的格式是否正確。
將二進位位元組編碼為Base64或 BinHex，並寫出產生的文字。
使用 Common Language Runtime 類型而非字串傳遞值，以避免必須手動執行值轉換。
將多份文件寫至一個輸出資料流。
寫入有效的名稱、限定名稱，以及名稱語彙基元。

建立 XML 寫入器

若要建立 XmlWriter 實例，請使用 XmlWriter.Create 方法。若要指定您想要在 XML 寫入器上啟用的功能集，請將傳遞 XmlWriterSettings 至 Create 方法。否則會使用預設設定。如需詳細資訊， Create 請參閱參考頁面。

指定輸出格式

類別 XmlWriterSettings 包含數個屬性，可控制 XmlWriter 輸出格式的方式：

屬性	說明
Encoding	指定要使用的文字編碼方式。預設值為 `Encoding.UTF8`。
Indent	表示是否縮排項目。預設值為 `false` （無縮排）。
IndentChars	指定縮排時要使用的字元字串。預設值為兩個空格。
NewLineChars	指定用於分行符號的字元字串。默認為 `\r\n` 非 Unix 平台的歸位字元、換行字元，以及 `\n` Unix 平臺的換行字元。
NewLineHandling	指定如何處理換行符。
NewLineOnAttributes	表示是否要在新行上寫入屬性。 Indent 使用這個屬性時，應該設定為 `true` 。預設值為 `false`。
OmitXmlDeclaration	表示是否撰寫 XML 宣告。預設值為 `false`。

Indent 及 IndentChars 屬性控制如何格式化非顯著泛空白字元。例如，若要縮排項目節點：

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.IndentChars = vbTab
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

使用在 NewLineOnAttributes 具有一個額外縮排層級的新行上寫入每個屬性：

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.NewLineOnAttributes = True
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

數據一致性

XML 寫入器會使用類別中的 XmlWriterSettings 兩個屬性來檢查資料一致性：

屬性 CheckCharacters 會指示 XML 寫入器檢查字元，並在任何字元超出 W3C 所定義的合法範圍內時擲回 XmlException 例外狀況。

屬性 ConformanceLevel 會設定 XML 寫入器，以檢查所寫入的數據流是否符合格式正確的 XML 1.0 檔案或檔案片段的規則，如 W3C 所定義。下表說明這三個一致性層級。預設值為 Document。如需詳細資訊，請參閱 XmlWriterSettings.ConformanceLevel 屬性和 System.Xml.ConformanceLevel 列舉。

層級	描述
Document	XML 輸出符合格式正確的 XML 1.0 檔案的規則，而且可由任何符合的處理器處理。
Fragment	XML 輸出符合格式正確的 XML 1.0 檔案片段的規則。
Auto	XML 寫入器會根據傳入數據決定要套用的符合性檢查層級（檔或片段）。

寫入專案

您可以使用下列 XmlWriter 方法來寫入項目節點。如需範例，請參閱列出的方法。

使用	目標
WriteElementString	寫入整個項目節點，包括字串值。
WriteStartElement	若要使用多個方法呼叫來寫入專案值。例如，您可以呼叫 WriteValue 寫入具型別值、呼叫 WriteCharEntity 寫入字元實體、呼叫 WriteAttributeString 寫入屬性，或者可以寫入項目子系。這是方法的更複雜版本 WriteElementString 。若要關閉專案，您可以呼叫 WriteEndElement 或 WriteFullEndElement 方法。
WriteNode	若要複製位於或 XPathNavigator 物件目前位置的項目XmlReader節點。呼叫此方法時，它會將來源物件中的所有內容複製到 XmlWriter 執行個體。

寫入屬性

您可以使用下列 XmlWriter 方法，在項目節點上寫入屬性。這些方法也可以用來在元素上建立命名空間宣告，如下一節所述。

使用	目標
WriteAttributeString	若要寫入整個屬性節點，包括字串值。
WriteStartAttribute	若要使用多個方法呼叫來寫入屬性值。例如，您可以呼叫 WriteValue 來寫入具類型的值。這是方法的更複雜版本 WriteElementString 。若要關閉專案，您可以呼叫 WriteEndAttribute 方法。
WriteAttributes	複製物件目前位置 XmlReader 上找到的所有屬性。寫入的屬性取決於讀取器目前所在的節點類型： - 如果是屬性節點，它會寫入目前的屬性，然後寫入其餘的屬性，直到項目結尾標記為止。 - 對於項目節點，它會寫入專案所包含的所有屬性。 - 對於 XML 宣告節點，它會寫入宣告中的所有屬性。 - 對於所有其他節點類型，方法會擲回例外狀況。

處理命名空間

命名空間用於對 XML 文件中的項目與屬性名稱進行限定。命名空間前置詞會將元素和屬性與命名空間產生關聯，而命名空間又與 URI 參考相關聯。命名空間會在 XML 文件中建立項目和屬性名稱唯一性。

會 XmlWriter 維護對應至目前命名空間範圍中定義之所有命名空間的命名空間堆疊。當寫入項目及屬性時，可透過下列方式利用命名空間：

使用 WriteAttributeString 方法手動宣告命名空間。當知道如何最佳化命名空間宣告數目時，這便會很有用。如需範例，請參閱 WriteAttributeString(String, String, String, String) 方法。

使用新的命名空間覆寫目前的命名空間宣告。在下列程式代碼中，方法會將 WriteAttributeString 前置詞的 "x" 命名空間 URI 從 "123" 變更為 "abc"。

writer.WriteStartElement("x", "root", "123");
writer.WriteStartElement("item");
writer.WriteAttributeString("xmlns", "x", null, "abc");
writer.WriteEndElement();
writer.WriteEndElement();

writer.WriteStartElement("x", "root", "123")
writer.WriteStartElement("item")
writer.WriteAttributeString("xmlns", "x", Nothing, "abc")
writer.WriteEndElement()
writer.WriteEndElement()

程式碼會產生下列 XML 字串：

<x:root xmlns:x="123">
  <item xmlns:x="abc" />
</x:root>

寫入屬性或項目時，指定命名空間前置詞。許多用來寫入元素和屬性的方法可讓您執行這項操作。例如， WriteStartElement(String, String, String) 方法會寫入開始標記，並將它與指定的命名空間和前置詞產生關聯。

寫入具類型的數據

WriteValue方法接受 Common Language Runtime （CLR）物件、根據 XML 架構定義語言（XSD）資料類型轉換規則，將輸入值轉換成其字串表示法，並使用方法將其寫出WriteString。這比使用類別中的 XmlConvert 方法將具型別數據轉換成字串值更容易，再將其寫出。

寫入文字時，使用該架構類型的規則，將具類型的值串行化為文字 XmlConvert 。

如需對應至 CLR 類型的預設 XSD 數據類型，請參閱 WriteValue 方法。

XmlWriter也可以用來寫入 XML 資料存放區。例如，XPathNavigator 類別可以建立 XmlWriter 物件，以建立 XmlDocument 物件的節點。如果數據存放區有可用的架構資訊，如果您嘗試轉換成不允許的類型，此方法 WriteValue 會擲回例外狀況。如果資料存放區沒有可用的架構資訊，方法 WriteValue 會將所有值 xsd:anySimpleType 視為類型。

關閉 XML 寫入器

當您使用 XmlWriter 方法來輸出 XML 時，除非呼叫 Close 方法，否則不會寫入元素和屬性。例如，如果您使用 XmlWriter 來填入 XmlDocument 物件，在關閉 XmlWriter 實例之前，您將無法在目標檔中看到寫入的元素和屬性。

非同步程式設計

XmlWriter大部分的方法都有異步對應專案，其方法名稱結尾有「Async」。例如，的異步對等專案 WriteAttributeString 是 WriteAttributeStringAsync。

WriteValue對於沒有異步對應專案的方法，請將傳回值轉換為字串，並改用 WriteStringAsync 方法。

安全性考量

使用類別時， XmlWriter 請考慮下列事項：

所 XmlWriter 擲回的例外狀況可以揭露您不想泡到應用程式的路徑資訊。您的應用程式必須攔截例外狀況，並適當地加以處理。
XmlWriter 不會驗證傳遞至 WriteDocType 或 WriteRaw 方法的任何數據。您不應該將任意數據傳遞至這些方法。