XmlWriter 类

定义

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

继承

Object

XmlWriter

派生

System.Xml.XmlDictionaryWriter

System.Xml.XmlTextWriter

System.Xml.Xsl.Runtime.XmlQueryOutput

实现

IDisposable IAsyncDisposable

示例

以下示例代码演示如何使用异步 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 1.0（第四版） 和 XML 1.0（第三版）建议中的 W3C 可扩展标记语言（XML）和命名空间。

XmlWriter 类的成员使你能够：

• 验证这些字符是否为合法的 XML 字符，以及元素和属性名称是否为有效的 XML 名称。
• 验证 XML 文档的格式正确。
• 将二进制字节编码为 Base64 或 BinHex，并写出生成的文本。
• 使用公共语言运行时类型而不是字符串传递值，以避免必须手动执行值转换。
• 将多个文档写入一个输出流。
• 编写有效名称、限定名称和名称标记。

创建 XML 编写器

若要创建 XmlWriter 实例，请使用该方法 XmlWriter.Create 。 若要指定要在 XML 编写器上启用的功能集，请向XmlWriterSettings该方法传递一个Create。 否则，将使用默认设置。 请参阅 Create 参考页以了解详细信息。

指定输出格式

该 XmlWriterSettings 类包括多个属性，用于控制 XmlWriter 输出的格式：

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 编写器配置为检查所编写的流是否符合由 W3C 定义的格式正确的 XML 1.0 文档或文档片段的规则。 下表描述了这三个一致性级别。 默认值为 Document。 有关详细信息，请参阅 XmlWriterSettings.ConformanceLevel 属性和 System.Xml.ConformanceLevel 枚举。

  Level	Description
  Document	XML 输出符合格式正确的 XML 1.0 文档的规则，并且可由任何符合要求的处理器进行处理。
  Fragment	XML 输出符合格式正确的 XML 1.0 文档片段的规则。
  Auto	XML 编写器根据传入数据确定要应用（文档或片段）的符合性检查级别。

写入元素

可以使用以下 XmlWriter 方法编写元素节点。 有关示例，请参阅列出的方法。

写入属性

可以使用以下 XmlWriter 方法在元素节点上编写属性。 这些方法还可用于在元素上创建命名空间声明，如下一部分所述。

处理命名空间

命名空间用于限定 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 接受公共语言运行时 （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 方法的任何数据。 不应将任意数据传递给这些方法。

另请参阅

• XML 文档和数据