System.Xml.XmlWriter 类

项目
01/11/2024

XmlWriter 类将 XML 数据写入流、文件、文本读取器或字符串。它支持 W3C 可扩展标记语言 (XML) 1.0（第四版）和 XML 中命名空间 1.0（第三版）的建议。

XmlWriter 类的成员使你能够：

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

创建 XML 编写器

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

指定输出格式

XmlWriterSettings 类包括多个可以控制如何格式化 XmlWriter 输出的属性：

properties	说明
Encoding	指定要使用的文本编码。默认为 `Encoding.UTF8`。
Indent	指示是否使元素缩进。默认值为 `false`（无缩进）。
IndentChars	指定在缩进时要使用的字符串。默认值为两个空格。
NewLineChars	指定分行符要使用的字符串。对于非 Unix 平台，默认值为 `\r\n`（回车符、换行符），对于 Unix 平台，默认值为 `\n` （换行符）。
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 编写器，以检查所编写的流是否符合 W3C 规定的格式正确的 XML 1.0 文档或文档片段的规则。下表描述了三个一致性级别。默认为 Document。有关详细信息，请参阅 XmlWriterSettings.ConformanceLevel 属性和 System.Xml.ConformanceLevel 枚举。

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

写入元素

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

使用	功能
WriteElementString	写入整个元素节点，包括字符串值。
WriteStartElement	要通过使用多个方法调用来写入元素值。例如，可以调用 WriteValue 来编写类型化的值，调用 WriteCharEntity 来编写字符实体，调用 WriteAttributeString 来编写属性，也可以编写子元素。这是 WriteElementString 方法的一个更复杂版本。若要关闭元素，请调用 WriteEndElement 或 WriteFullEndElement 方法。
WriteNode	要复制在 XmlReader 或 XPathNavigator 对象的当前位置找到的元素节点。在调用时，会将源对象中的所有内容复制到 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 方法接受公共语言运行时 (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 方法的任何数据。不应将任意数据传递给这些方法。