XmlWriter 类
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
表示一个写入器，该写入器提供一种快速、非缓存和只进方式以生成包含 XML 数据的流或文件。
public ref class XmlWriter abstract : IDisposablepublic ref class XmlWriter abstract : IAsyncDisposable, IDisposablepublic ref class XmlWriter abstractpublic abstract class XmlWriter : IDisposablepublic abstract class XmlWriter : IAsyncDisposable, IDisposablepublic abstract class XmlWritertype XmlWriter = class
interface IDisposabletype XmlWriter = class
interface IAsyncDisposable
interface IDisposabletype XmlWriter = classPublic MustInherit Class XmlWriter
Implements IDisposablePublic MustInherit Class XmlWriter
Implements IAsyncDisposable, IDisposablePublic 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 数据写入流、文件、文本读取器或字符串。 它支持 W3C 可扩展标记语言 (XML) 1.0 (第四版) 和 XML 1.0 (第三版中的命名空间) 建议。
类的成员 XmlWriter 使你能够：
检查字符是不是合法的 XML 字符，元素和属性的名称是不是有效的 XML 名称。
检查 XML 文档的格式是否正确。
将二进制字节编码为 Base64 或 BinHex，并写出生成的文本。
使用公共语言运行时类型（而不是字符串）传递值，以避免手动执行值转换。
将多个文档写入一个输出流。
写出有效的名称、限定名和名称标记。
本部分内容：
创建 XML 编写器
指定输出格式
数据一致性
写入元素
写入属性
处理命名空间
写入类型化数据
关闭 XML 编写器
异步编程
安全注意事项
创建 XML 编写器
若要创建 XmlWriter 实例，请使用 XmlWriter.Create 方法。 若要指定要在 XML 编写器上启用的功能集，请将 传递给 XmlWriterSettingsCreate 方法。 否则，使用默认设置。 有关详细信息， Create 请参阅参考页。
指定输出格式
类 XmlWriterSettings 包括几个控制 XmlWriter 输出格式的属性：
| Property | 说明 |
|---|---|
| Encoding | 指定要使用的文本编码。 默认值为 Encoding.UTF8。 |
| Indent | 指示是否使元素缩进。 默认值为 false (无缩进) 。 |
| IndentChars | 指定在缩进时要使用的字符串。 默认值为两个空格。 |
| NewLineChars | 指定分行符要使用的字符串。 默认值为 \r\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 编写器配置为检查正在写入的流是否符合格式正确的 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 接受 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 方法的任何数据。 不应将任意数据传递给这些方法。
构造函数
| XmlWriter() |
初始化 XmlWriter 类的新实例。 |
属性
| Settings |
获取用于创建此 XmlWriter 实例的 XmlWriterSettings 对象。 |
| WriteState |
当在派生类中被重写时，获取写入器的状态。 |
| XmlLang |
当在派生类中被重写时，获取当前的 |
| XmlSpace |
当在派生类中被重写时，获取表示当前 |
方法
显式接口实现
| IDisposable.Dispose() |
有关此成员的说明，请参见 Dispose()。 |
扩展方法
| ConfigureAwait(IAsyncDisposable, Boolean) |
配置如何执行从异步可处置项返回的任务的等待。 |