XmlWriter 類別

定義

表示寫入器,其可提供快速、非快取的順向方法來產生含有 XML 資料之資料流或檔案。

public ref class XmlWriter abstract : IDisposable
public ref class XmlWriter abstract : IAsyncDisposable, IDisposable
public ref class XmlWriter abstract
public abstract class XmlWriter : IDisposable
public abstract class XmlWriter : IAsyncDisposable, IDisposable
public abstract class XmlWriter
type XmlWriter = class
    interface IDisposable
type XmlWriter = class
    interface IAsyncDisposable
    interface IDisposable
type XmlWriter = class
Public MustInherit Class XmlWriter
Implements IDisposable
Public MustInherit Class XmlWriter
Implements IAsyncDisposable, IDisposable
Public MustInherit Class XmlWriter
繼承
XmlWriter
衍生
實作

範例

下列範例程式碼示範如何使用非同步 API 來產生 XML。

async Task TestWriter(Stream stream)   
{  
    XmlWriterSettings settings = new XmlWriterSettings();  
    settings.Async = true;  

    using (XmlWriter writer = XmlWriter.Create(stream, settings)) {  
        await writer.WriteStartElementAsync("pf", "root", "http://ns");  
        await writer.WriteStartElementAsync(null, "sub", null);  
        await writer.WriteAttributeStringAsync(null, "att", null, "val");  
        await writer.WriteStringAsync("text");  
        await writer.WriteEndElementAsync();  
        await writer.WriteProcessingInstructionAsync("pName", "pValue");  
        await writer.WriteCommentAsync("cValue");  
        await writer.WriteCDataAsync("cdata value");  
        await writer.WriteEndElementAsync();  
        await writer.FlushAsync();  
    }  
}  

備註

類別 XmlWriter 會將 XML 資料寫入資料流程、檔案、文字讀取器或字串。 它支援 XML (XML) 1.0 (第四版的 XML ) 和 XML 1.0 (第三版) 建議中的命名空間

類別的成員 XmlWriter 可讓您:

  • 驗證字元是否為合法 XML 字元,以及項目與屬性名稱是否為有效的 XML 名稱。

  • 驗證 XML 文件的格式是否正確。

  • 將二進位位元組編碼為 Base64 或 BinHex,並寫出產生的文字。

  • 使用 Common Language Runtime 類型而非字串傳遞值,以避免必須手動執行值轉換。

  • 將多份文件寫至一個輸出資料流。

  • 寫入有效的名稱、限定名稱,以及名稱語彙基元。

本節內容:

建立 XML 寫入器
指定輸出格式
資料一致性
寫入元素
撰寫屬性
處理命名空間
寫入具類型的資料
關閉 XML 寫入器
非同步程式設計
安全性考量

建立 XML 寫入器

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

指定輸出格式

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

屬性 描述
Encoding 指定要使用的文字編碼方式。 預設為 Encoding.UTF8
Indent 表示是否縮排項目。 預設值為 false (沒有縮排) 。
IndentChars 指定縮排時要使用的字元字串。 預設值為兩個空格。
NewLineChars 指定用於分行符號的字元字串。 預設值為 \r\n (歸位字元、換行字元)。
NewLineHandling 指定如何處理分行符號。
NewLineOnAttributes 表示是否要在新行上寫入屬性。 Indent 使用這個屬性時,應該設定為 true 。 預設為 false
OmitXmlDeclaration 表示是否撰寫 XML 宣告。 預設為 false

IndentIndentChars 屬性控制如何格式化非顯著泛空白字元。 例如,若要縮排專案節點:

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 寫入器檢查字元,並在任何字元超出法律範圍時擲 XmlException 回例外狀況,如 W3C 所定義。

  • 屬性 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

若要關閉 專案,您可以呼叫 WriteEndElementWriteFullEndElement 方法。
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 不會驗證傳遞至 WriteDocTypeWriteRaw 方法的任何資料。 您不應該將任意資料傳遞至這些方法。

建構函式

XmlWriter()

初始化 XmlWriter 類別的新執行個體。

屬性

Settings

取得 XmlWriterSettings 物件,用於建立這個 XmlWriter 執行個體。

WriteState

在衍生類別中覆寫時,取得寫入器的狀態。

XmlLang

當在衍生類別中覆寫時,取得目前xml:lang範圍。

XmlSpace

在衍生類別中覆寫時,取得表示目前 xml:space 範圍的 XmlSpace

方法

Close()

在衍生類別中覆寫時,關閉這個資料流和基礎資料流。

Create(Stream)

使用指定的資料流,建立新的 XmlWriter 執行個體。

Create(Stream, XmlWriterSettings)

使用資料流和 XmlWriter 物件,建立新 XmlWriterSettings 執行個體。

Create(String)

使用指定的檔名,建立新 XmlWriter 執行個體。

Create(String, XmlWriterSettings)

使用檔名和 XmlWriter 物件,建立新 XmlWriterSettings 執行個體。

Create(StringBuilder)

使用指定的 XmlWriter,建立新 StringBuilder 執行個體。

Create(StringBuilder, XmlWriterSettings)

使用 XmlWriterStringBuilder 物件,建立新的 XmlWriterSettings 執行個體。

Create(TextWriter)

使用指定的 XmlWriter,建立新 TextWriter 執行個體。

Create(TextWriter, XmlWriterSettings)

使用 XmlWriterTextWriter 物件,建立新的 XmlWriterSettings 執行個體。

Create(XmlWriter)

使用指定的 XmlWriter 物件,建立新 XmlWriter 執行個體。

Create(XmlWriter, XmlWriterSettings)

使用指定的 XmlWriterXmlWriter 物件,建立新的 XmlWriterSettings 執行個體。

Dispose()

釋放 XmlWriter 類別目前的執行個體所使用的全部資源。

Dispose(Boolean)

釋放 XmlWriter 所使用的 Unmanaged 資源,並選擇性地釋放 Managed 資源。

DisposeAsync()

非同步執行與釋放 (Free)、釋放 (Release) 或重設 Unmanaged 資源相關聯之由應用程式定義的工作。

DisposeAsyncCore()

以非同步方式執行與釋放 (Free)、釋放 (Release) 或重設受控資源相關聯的應用程式定義工作。

Equals(Object)

判斷指定的物件是否等於目前的物件。

(繼承來源 Object)
Flush()

在衍生類別中覆寫時,將緩衝區的所有內容清空至基礎資料流,然後清空基礎資料流。

FlushAsync()

以非同步的方式將緩衝區的所有內容清空至基礎資料流,然後清空基礎資料流。

GetHashCode()

做為預設雜湊函式。

(繼承來源 Object)
GetType()

取得目前執行個體的 Type

(繼承來源 Object)
LookupPrefix(String)

在衍生類別中覆寫時,傳回最接近命名空間 URI 在目前命名空間範圍中定義的前置詞。

MemberwiseClone()

建立目前 Object 的淺層複製。

(繼承來源 Object)
ToString()

傳回代表目前物件的字串。

(繼承來源 Object)
WriteAttributes(XmlReader, Boolean)

在衍生類別中覆寫時,寫出在 XmlReader 的目前位置找到的所有屬性。

WriteAttributesAsync(XmlReader, Boolean)

非同步寫出在 XmlReader 中的目前位置找到的所有屬性。

WriteAttributeString(String, String)

在衍生類別中覆寫時,寫出具有指定的區域名稱與數值的屬性。

WriteAttributeString(String, String, String)

在衍生類別中覆寫時,寫入具有指定區域名稱、命名空間 URI 和值的屬性。

WriteAttributeString(String, String, String, String)

在衍生類別中覆寫時,寫出具有指定的前置詞、區域名稱、命名空間 URI 及其值的屬性。

WriteAttributeStringAsync(String, String, String, String)

以非同步的方式寫出具有指定之前置詞、區域名稱、命名空間 URI 和值的屬性。

WriteBase64(Byte[], Int32, Int32)

在衍生類別中覆寫時,以 Base64 格式編碼指定的二進位位元組,並寫出產生的文字。

WriteBase64Async(Byte[], Int32, Int32)

以非同步的方式將指定的二進位位元組編碼為 base64 並寫出產生的文字。

WriteBinHex(Byte[], Int32, Int32)

在衍生類別中覆寫時,以 BinHex 格式編碼指定的二進位位元組,並寫出產生的文字。

WriteBinHexAsync(Byte[], Int32, Int32)

以非同步的方式將指定的二進位位元組編碼為 BinHex 並寫出產生的文字。

WriteCData(String)

在衍生類別中覆寫時,寫出包含指定文字的 <![CDATA[...]]> 區塊。

WriteCDataAsync(String)

以非同步的方式寫出包含指定文字的 <![CDATA[...]]> 區塊。

WriteCharEntity(Char)

在衍生類別中覆寫時,強制產生指定之 Unicode 字元值的字元實體。

WriteCharEntityAsync(Char)

以非同步的方式強制產生指定的 Unicode 字元值的字元實體。

WriteChars(Char[], Int32, Int32)

在衍生類別中覆寫時,一次將文字寫入一個緩衝區。

WriteCharsAsync(Char[], Int32, Int32)

以非同步的方式一次將文字寫入一個緩衝區。

WriteComment(String)

在衍生類別中覆寫時,寫出包含指定文字的註解 <!--...-->。

WriteCommentAsync(String)

以非同步的方式寫出包含指定文字的註解 <!--...-->。

WriteDocType(String, String, String, String)

在衍生類別中覆寫時,寫入具有指定名稱與選擇性屬性的 DOCTYPE 宣告。

WriteDocTypeAsync(String, String, String, String)

以非同步的方式寫入具有指定名稱與選擇性屬性的 DOCTYPE 宣告。

WriteElementString(String, String)

寫入具有指定之區域名稱和值的項目。

WriteElementString(String, String, String)

寫入具有指定之區域名稱、命名空間 URI 和值的項目。

WriteElementString(String, String, String, String)

寫入具有指定的前置詞、區域名稱、命名空間 URI 和值的項目。

WriteElementStringAsync(String, String, String, String)

以非同步的方式寫入具有指定之前置詞、區域名稱、命名空間 URI 和值的項目。

WriteEndAttribute()

在衍生類別中覆寫時,會關閉先前的 WriteStartAttribute(String, String) 呼叫。

WriteEndAttributeAsync()

非同步關閉上一個 WriteStartAttribute(String, String) 呼叫。

WriteEndDocument()

在衍生類別中覆寫時,關閉任何開啟的項目或屬性,並將寫入器回復開始狀態。

WriteEndDocumentAsync()

以非同步的方式關閉任何開啟的項目或屬性,並將寫入器回復開始狀態。

WriteEndElement()

在衍生類別中覆寫時,關閉一個項目並取出對應的命名空間範圍。

WriteEndElementAsync()

以非同步的方式關閉一個項目並取出對應的命名空間範圍。

WriteEntityRef(String)

在衍生類別中覆寫時,寫出如 &name; 的實體參考。

WriteEntityRefAsync(String)

以非同步的方式將實體參考寫出為 &name;

WriteFullEndElement()

在衍生類別中覆寫時,關閉一個項目並取出對應的命名空間範圍。

WriteFullEndElementAsync()

以非同步的方式關閉一個項目並取出對應的命名空間範圍。

WriteName(String)

當覆寫衍生類別時,請寫出指定的名稱,以確保它是符合 W3C XML 1.0 建議 (https://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) (英文) 的有效名稱。

WriteNameAsync(String)

非同步地寫出指定的名稱,以確保它是符合 W3C XML 1.0 建議 (https://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) (英文) 的有效名稱。

WriteNmToken(String)

當覆寫衍生類別時,請寫出指定的名稱,以確保它是符合 W3C XML 1.0 建議 (https://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) (英文) 的有效 NmToken。

WriteNmTokenAsync(String)

非同步地寫出指定的名稱,以確保它是符合 W3C XML 1.0 建議 (https://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) (英文) 的有效 NmToken。

WriteNode(XmlReader, Boolean)

在衍生類別中覆寫時,從讀取器複製所有內容至寫入器,並將讀取器移至下一個同層級 (Sibling) 的開頭。

WriteNode(XPathNavigator, Boolean)

XPathNavigator 物件中的所有項目複製到寫入器。 XPathNavigator 的位置保持不變。

WriteNodeAsync(XmlReader, Boolean)

以非同步的方式從讀取器複製所有內容至寫入器,並將讀取器移至下一個同層級 (Sibling) 的開頭。

WriteNodeAsync(XPathNavigator, Boolean)

以非同步方式將所有項目從 XPathNavigator 物件複製到寫入器。 XPathNavigator 的位置保持不變。

WriteProcessingInstruction(String, String)

在衍生類別中覆寫時,寫出名稱與文字之間有空白的處理指示,如下所示:<?name text?>。

WriteProcessingInstructionAsync(String, String)

以非同步方式寫出名稱與文字之間有空白的處理指示,如下所示:<?name text?>。

WriteQualifiedName(String, String)

在衍生類別中覆寫時,寫出命名空間限定名稱。 這個方法會查詢在指定之命名空間範圍中的前置詞。

WriteQualifiedNameAsync(String, String)

以非同步的方式寫出命名空間限定名稱。 這個方法會查詢在指定之命名空間範圍中的前置詞。

WriteRaw(Char[], Int32, Int32)

在衍生類別中覆寫時,從字元緩衝區手動寫入未經處理的標記。

WriteRaw(String)

在衍生類別中覆寫時,從字串手動寫入未經處理的標記 (Raw Markup)。

WriteRawAsync(Char[], Int32, Int32)

以非同步的方式從字元緩衝區手動寫入未經處理的標記。

WriteRawAsync(String)

以非同步的方式從字串手動寫入未經處理的標記 (Raw Markup)。

WriteStartAttribute(String)

寫入具有指定之區域名稱的屬性開頭。

WriteStartAttribute(String, String)

寫入具有指定之區域名稱和命名空間 URI 之屬性的開頭。

WriteStartAttribute(String, String, String)

在衍生類別中覆寫時,寫入具有指定的前置詞、區域名稱和命名空間 URI 之屬性的開頭。

WriteStartAttributeAsync(String, String, String)

以非同步的方式寫入具有指定之前置詞、本機名稱和命名空間 URI 之屬性的開頭。

WriteStartDocument()

在衍生類別中覆寫時,使用「1.0」版寫入 XML 宣告。

WriteStartDocument(Boolean)

在衍生類別中覆寫時,使用「1.0」版寫入 XML 宣告與獨立屬性。

WriteStartDocumentAsync()

以非同步的方式使用「1.0」版寫入 XML 宣告。

WriteStartDocumentAsync(Boolean)

以非同步的方式使用「1.0」版寫入 XML 宣告與獨立屬性。

WriteStartElement(String)

在衍生類別中覆寫時,寫出具有指定之區域名稱的開頭標記。

WriteStartElement(String, String)

在衍生類別中覆寫時,寫入指定的開頭標記並與指定的命名空間產生關聯。

WriteStartElement(String, String, String)

在衍生類別中覆寫時,寫入指定的開頭標記,並與指定的命名空間與前置詞產生關聯。

WriteStartElementAsync(String, String, String)

以非同步的方式寫入指定的開頭標記,並將它與指定的命名空間與前置詞產生關聯。

WriteString(String)

在衍生類別中覆寫時,寫入指定的文字內容。

WriteStringAsync(String)

以非同步的方式寫入指定的文字內容。

WriteSurrogateCharEntity(Char, Char)

在衍生類別中覆寫時,產生和寫入 Surrogate 字元字組的 Surrogate 字元實體。

WriteSurrogateCharEntityAsync(Char, Char)

以非同步的方式產生和寫入 Surrogate 字元字組的 Surrogate 字元實體。

WriteValue(Boolean)

寫入 Boolean 值。

WriteValue(DateTime)

寫入 DateTime 值。

WriteValue(DateTimeOffset)

寫入 DateTimeOffset 值。

WriteValue(Decimal)

寫入 Decimal 值。

WriteValue(Double)

寫入 Double 值。

WriteValue(Int32)

寫入 Int32 值。

WriteValue(Int64)

寫入 Int64 值。

WriteValue(Object)

寫入物件值。

WriteValue(Single)

寫入單精確度浮點數。

WriteValue(String)

寫入 String 值。

WriteWhitespace(String)

在衍生類別中覆寫時,寫出指定的空白字元。

WriteWhitespaceAsync(String)

以非同步的方式寫出指定的空白字元。

明確介面實作

IDisposable.Dispose()

如需這個成員的說明,請參閱 Dispose()

擴充方法

ConfigureAwait(IAsyncDisposable, Boolean)

設定如何執行從非同步可處置項目傳回的工作 await。

適用於

另請參閱