XmlTextWriter 类 (System.Xml)

表示提供快速、非缓存、只进方法的写入器，该方法生成包含 XML 数据（这些数据符合 W3C 可扩展标记语言 (XML) 1.0 和“XML 命名空间”建议）的流或文件。

从 .NET Framework 2.0 开始，建议改用 System.Xml.XmlWriter 类。

命名空间:   System.Xml
程序集:  System.Xml（位于 System.Xml.dll）

继承层次结构

System.Object
  System.Xml.XmlWriter
    System.Xml.XmlTextWriter

语法

C#

C++

F#

VB

Public Class XmlTextWriter
	Inherits XmlWriter

构造函数

	名称	说明
	XmlTextWriter(Stream, Encoding)	创建的一个实例 XmlTextWriter 类使用指定的流和编码。
	XmlTextWriter(String, Encoding)	创建的一个实例 XmlTextWriter 类使用指定的文件。
	XmlTextWriter(TextWriter)	创建的一个实例 XmlTextWriter 类使用指定 TextWriter。

属性

	名称	说明
	BaseStream	获取基础流对象。
	Formatting	指示如何对输出进行格式设置。
	Indentation	获取或设置要为层次结构中每个级别写入多少 Indentchar 时 Formatting 设置为 Formatting.Indented。
	IndentChar	获取或设置用于缩进时用于转换的字符 Formatting 设置为 Formatting.Indented。
	Namespaces	获取或设置一个值，该值指示是否进行命名空间支持。
	QuoteChar	获取或设置要用于引用属性值的字符。
	Settings	获取用于创建此 XmlWriter 实例的 XmlWriterSettings 对象。（继承自 XmlWriter。）
	WriteState	获取写入器的状态。（覆盖 XmlWriter.WriteState。）
	XmlLang	获取当前 xml:lang 范围。（覆盖 XmlWriter.XmlLang。）
	XmlSpace	获取 XmlSpace 表示当前 xml:space 作用域。（覆盖 XmlWriter.XmlSpace。）

方法

	名称	说明
	Close()	关闭此流和基础流。（覆盖 XmlWriter.Close()。）
	Dispose()	释放 XmlWriter 类的当前实例所使用的所有资源。（继承自 XmlWriter。）
	Dispose(Boolean)	释放由 XmlWriter 占用的非托管资源，还可以另外再释放托管资源。（继承自 XmlWriter。）
	Equals(Object)	确定指定的对象是否等于当前对象。（继承自 Object。）
	Finalize()	在垃圾回收将某一对象回收前允许该对象尝试释放资源并执行其他清理操作。（继承自 Object。）
	Flush()	将缓冲区中的所有内容刷新到基础流，并同时刷新基础流。（覆盖 XmlWriter.Flush()。）
	FlushAsync()	将缓冲区中的所有内容异步刷新到基础流，并同时刷新基础流。（继承自 XmlWriter。）
	GetHashCode()	作为默认哈希函数。（继承自 Object。）
	GetType()	获取当前实例的 Type。（继承自 Object。）
	LookupPrefix(String)	返回在当前命名空间范围中为该命名空间 URI 定义的最近的前缀。（覆盖 XmlWriter.LookupPrefix(String)。）
	MemberwiseClone()	创建当前 Object 的浅表副本。（继承自 Object。）
	ToString()	返回表示当前对象的字符串。（继承自 Object。）
	WriteAttributes(XmlReader, Boolean)	当在派生类中重写出在当前位置中找到的所有属性 XmlReader。（继承自 XmlWriter。）
	WriteAttributesAsync(XmlReader, Boolean)	异步写出在当前位置中找到的所有属性 XmlReader。（继承自 XmlWriter。）
	WriteAttributeString(String, String)	当在派生类中被重写时，写出具有指定的本地名称和值的属性。（继承自 XmlWriter。）
	WriteAttributeString(String, String, String)	当在派生类中被重写时，写入具有指定的本地名称、命名空间 URI 和值的属性。（继承自 XmlWriter。）
	WriteAttributeString(String, String, String, String)	当在派生类中被重写时，写出具有指定的前缀、本地名称、命名空间 URI 和值的属性。（继承自 XmlWriter。）
	WriteAttributeStringAsync(String, String, String, String)	异步写出具有指定前缀、本地名称、命名空间 URI 和值的属性。（继承自 XmlWriter。）
	WriteBase64(Byte(), Int32, Int32)	将指定的二进制字节编码为 Base64 并写出结果文本。（覆盖 XmlWriter.WriteBase64(Byte(), Int32, Int32)。）
	WriteBase64Async(Byte(), Int32, Int32)	将指定的二进制字节异步编码为 Base64 并写出结果文本。（继承自 XmlWriter。）
	WriteBinHex(Byte(), Int32, Int32)	将指定的二进制字节编码为 BinHex 并写出结果文本。（覆盖 XmlWriter.WriteBinHex(Byte(), Int32, Int32)。）
	WriteBinHexAsync(Byte(), Int32, Int32)	以异步方式将为指定的二进制字节编码 BinHex 并写出结果文本。（继承自 XmlWriter。）
	WriteCData(String)	写出包含指定文本的 <![CDATA[...]]> 块。（覆盖 XmlWriter.WriteCData(String)。）
	WriteCDataAsync(String)	异步写出一个包含指定文本的 <![CDATA[...]]> 块。（继承自 XmlWriter。）
	WriteCharEntity(Char)	为指定的 Unicode 字符值强制生成字符实体。（覆盖 XmlWriter.WriteCharEntity(Char)。）
	WriteCharEntityAsync(Char)	为指定的 Unicode 字符值异步强制生成字符实体。（继承自 XmlWriter。）
	WriteChars(Char(), Int32, Int32)	以每次一个缓冲区的方式写入文本。（覆盖 XmlWriter.WriteChars(Char(), Int32, Int32)。）
	WriteCharsAsync(Char(), Int32, Int32)	以每次一个缓冲区的方式异步写入文本。（继承自 XmlWriter。）
	WriteComment(String)	写出包含指定文本的注释 <!--...-->。（覆盖 XmlWriter.WriteComment(String)。）
	WriteCommentAsync(String)	异步写出一个包含指定文本的注释 <!--...-->。（继承自 XmlWriter。）
	WriteDocType(String, String, String, String)	写出具有指定名称和可选属性的 DOCTYPE 声明。（覆盖 XmlWriter.WriteDocType(String, String, String, String)。）
	WriteDocTypeAsync(String, String, String, String)	异步写入具有指定名称和可选属性的 DOCTYPE 声明。（继承自 XmlWriter。）
	WriteElementString(String, String)	写入具有指定的本地名称和值的元素。（继承自 XmlWriter。）
	WriteElementString(String, String, String)	写入具有指定的本地名称、命名空间 URI 和值的元素。（继承自 XmlWriter。）
	WriteElementString(String, String, String, String)	写入具有指定的前缀、本地名称、命名空间 URI 和值的元素。（继承自 XmlWriter。）
	WriteElementStringAsync(String, String, String, String)	异步写入具有指定的前缀、本地名称、命名空间 URI 和值的元素。（继承自 XmlWriter。）
	WriteEndAttribute()	关闭前一个 WriteStartAttribute 调用。（覆盖 XmlWriter.WriteEndAttribute()。）
	WriteEndAttributeAsync()	异步关闭前一个 WriteStartAttribute 调用。（继承自 XmlWriter。）
	WriteEndDocument()	关闭任何打开的元素或特性并将写入器重新设置为起始状态。（覆盖 XmlWriter.WriteEndDocument()。）
	WriteEndDocumentAsync()	异步关闭任何打开的元素或属性并将写入器重新设置为起始状态。（继承自 XmlWriter。）
	WriteEndElement()	关闭一个元素并弹出相应的命名空间范围。（覆盖 XmlWriter.WriteEndElement()。）
	WriteEndElementAsync()	异步关闭一个元素并弹出相应的命名空间范围。（继承自 XmlWriter。）
	WriteEntityRef(String)	写出实体引用作为 &name;。（覆盖 XmlWriter.WriteEntityRef(String)。）
	WriteEntityRefAsync(String)	异步写出实体引用作为 &name;。（继承自 XmlWriter。）
	WriteFullEndElement()	关闭一个元素并弹出相应的命名空间范围。（覆盖 XmlWriter.WriteFullEndElement()。）
	WriteFullEndElementAsync()	异步关闭一个元素并弹出相应的命名空间范围。（继承自 XmlWriter。）
	WriteName(String)	写出指定的名称，确保它是符合 W3C XML 1.0 建议 (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) 的有效名称。（覆盖 XmlWriter.WriteName(String)。）
	WriteNameAsync(String)	异步写出指定的名称，确保它是符合 W3C XML 1.0 建议 (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) 的有效名称。（继承自 XmlWriter。）
	WriteNmToken(String)	写出指定的名称，确保它一个有效 NmToken 根据 W3C XML 1.0 建议 (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name)。（覆盖 XmlWriter.WriteNmToken(String)。）
	WriteNmTokenAsync(String)	异步写出指定的名称，确保它是符合 W3C XML 1.0 建议 (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name) 的有效 NmToken。（继承自 XmlWriter。）
	WriteNode(XmlReader, Boolean)	当在派生类中被重写时，将全部内容从读取器复制到写入器并将读取器移动到下一个同级的开始位置。（继承自 XmlWriter。）
	WriteNode(XPathNavigator, Boolean)	将所有内容从复制 XPathNavigator 到编写器的对象。 位置 XPathNavigator 保持不变。（继承自 XmlWriter。）
	WriteNodeAsync(XmlReader, Boolean)	将所有内容从读取器异步复制到写入器并将读取器移动到下一个同级的开头。（继承自 XmlWriter。）
	WriteNodeAsync(XPathNavigator, Boolean)	以异步方式将所有内容从复制 XPathNavigator 到编写器的对象。 位置 XPathNavigator 保持不变。（继承自 XmlWriter。）
	WriteProcessingInstruction(String, String)	写出在名称和文本之间带有空格的处理指令，如下︰ <？ 命名 text？ >。（覆盖 XmlWriter.WriteProcessingInstruction(String, String)。）
	WriteProcessingInstructionAsync(String, String)	异步写出在名称和文本之间带有空格的处理指令如下︰ <？ 命名 text？ >。（继承自 XmlWriter。）
	WriteQualifiedName(String, String)	写出命名空间限定的名称。 此方法查找位于给定命名空间范围内的前缀。（覆盖 XmlWriter.WriteQualifiedName(String, String)。）
	WriteQualifiedNameAsync(String, String)	异步写出命名空间限定的名称。 此方法查找位于给定命名空间范围内的前缀。（继承自 XmlWriter。）
	WriteRaw(Char(), Int32, Int32)	从字符缓冲区手动写入原始标记。（覆盖 XmlWriter.WriteRaw(Char(), Int32, Int32)。）
	WriteRaw(String)	从字符串手动写入原始标记。（覆盖 XmlWriter.WriteRaw(String)。）
	WriteRawAsync(Char(), Int32, Int32)	从字符缓冲区手动异步写入原始标记。（继承自 XmlWriter。）
	WriteRawAsync(String)	从字符串手动异步写入原始标记。（继承自 XmlWriter。）
	WriteStartAttribute(String)	写入具有指定本地名称的属性的开头。（继承自 XmlWriter。）
	WriteStartAttribute(String, String)	写入具有指定本地名称和命名空间 URI 的属性的开头。（继承自 XmlWriter。）
	WriteStartAttribute(String, String, String)	写入属性的开头。（覆盖 XmlWriter.WriteStartAttribute(String, String, String)。）
	WriteStartAttributeAsync(String, String, String)	异步写入具有指定前缀、本地名称和命名空间 URI 的属性的开头。（继承自 XmlWriter。）
	WriteStartDocument()	写入版本为“1.0”的 XML 声明。（覆盖 XmlWriter.WriteStartDocument()。）
	WriteStartDocument(Boolean)	写入版本为“1.0”的 XML 声明和独立的属性。（覆盖 XmlWriter.WriteStartDocument(Boolean)。）
	WriteStartDocumentAsync()	异步写入版本为“1.0”的 XML 声明。（继承自 XmlWriter。）
	WriteStartDocumentAsync(Boolean)	异步写入版本为“1.0”的 XML 声明和独立的属性。（继承自 XmlWriter。）
	WriteStartElement(String)	当在派生类中被重写时，写出具有指定的本地名称的开始标记。（继承自 XmlWriter。）
	WriteStartElement(String, String)	当在派生类中被重写时，写入指定的开始标记并将其与给定的命名空间关联起来。（继承自 XmlWriter。）
	WriteStartElement(String, String, String)	写入指定的开始标记并将其与给定的命名空间和前缀关联起来。（覆盖 XmlWriter.WriteStartElement(String, String, String)。）
	WriteStartElementAsync(String, String, String)	异步写入指定的开始标记并将其与给定的命名空间和前缀关联起来。（继承自 XmlWriter。）
	WriteString(String)	写入给定的文本内容。（覆盖 XmlWriter.WriteString(String)。）
	WriteStringAsync(String)	异步写入给定的文本内容。（继承自 XmlWriter。）
	WriteSurrogateCharEntity(Char, Char)	为代理项字符对生成并写入代理项字符实体。（覆盖 XmlWriter.WriteSurrogateCharEntity(Char, Char)。）
	WriteSurrogateCharEntityAsync(Char, Char)	为代理项字符对异步生成并写入代理项字符实体。（继承自 XmlWriter。）
	WriteValue(Boolean)	写入 Boolean 值。（继承自 XmlWriter。）
	WriteValue(DateTime)	写入 DateTime 值。（继承自 XmlWriter。）
	WriteValue(DateTimeOffset)	写入 DateTimeOffset 值。（继承自 XmlWriter。）
	WriteValue(Decimal)	写入 Decimal 值。（继承自 XmlWriter。）
	WriteValue(Double)	写入 Double 值。（继承自 XmlWriter。）
	WriteValue(Int32)	写入 Int32 值。（继承自 XmlWriter。）
	WriteValue(Int64)	写入 Int64 值。（继承自 XmlWriter。）
	WriteValue(Object)	写入对象值。（继承自 XmlWriter。）
	WriteValue(Single)	写入一个单精度浮点数。（继承自 XmlWriter。）
	WriteValue(String)	写入 String 值。（继承自 XmlWriter。）
	WriteWhitespace(String)	写出给定的空白区域。（覆盖 XmlWriter.WriteWhitespace(String)。）
	WriteWhitespaceAsync(String)	异步写出给定的空白区域。（继承自 XmlWriter。）

备注

此类实现 XmlWriter 类。

说明

从.NET Framework 2.0 开始，我们建议您创建 XmlWriter 实例通过使用 XmlWriter.Create 方法和 XmlWriterSettings 类，以充分利用新功能。

XmlTextWriter 维护与当前元素堆栈中定义的所有命名空间对应的命名空间堆栈。 使用 XmlTextWriter 可以手动声明命名空间。

w.WriteStartElement("root");
w.WriteAttributeString("xmlns", "x", null, "urn:1");
 w.WriteStartElement("item","urn:1");
 w.WriteEndElement();
 w.WriteStartElement("item","urn:1");
 w.WriteEndElement();
w.WriteEndElement();

上面的 C# 代码产生以下输出。 XmlTextWriter 将升级到根元素，以避免让它能在两个子元素上重复的命名空间声明。 子元素中选取前缀的命名空间声明中。

<root xmlns:x="urn:1">
 <x:item/>
 <x:item/>
</x:root>

XmlTextWriter 此外允许您重写当前命名空间声明。 在以下示例中，命名空间 URI"123"由"abc"要生成的 XML 元素重写 <x:node xmlns:x="abc"/>。

w.WriteStartElement("x","node","123");
w.WriteAttributeString("xmlns","x",null,"abc");

通过使用接受作为参数的前缀的 write 方法还可以指定要使用该前缀。 在下面的示例中，两个不同的前缀映射到相同的命名空间 URI 以产生 XML 文本 <x:root xmlns:x="urn:1"><y:item xmlns:y="urn:1"/></x:root>。

XmlTextWriter w = new XmlTextWriter(Console.Out);
w.WriteStartElement("x","root","urn:1");
 w.WriteStartElement("y","item","urn:1");
 w.WriteEndElement();
w.WriteEndElement();
w.Close();

如果有多个命名空间声明将不同的前缀映射到同一个命名空间 URI， XmlTextWriter 向后遍历命名空间声明堆栈和选取最近的一个。

XmlTextWriter w = new XmlTextWriter(Console.Out);
w.Formatting = Formatting.Indented;
w.WriteStartElement("x","root","urn:1");
w.WriteStartElement("y","item","urn:1");
w.WriteAttributeString("attr","urn:1","123");
w.WriteEndElement();
w.WriteEndElement();
w.Close();

在上面的 C# 示例，因为 WriteAttributeString 调用未指定前缀，编写器使用推送到命名空间堆栈的最后一个前缀，并将生成以下 XML:

<x:root xmlns:x="urn:1">
 <y:item y:attr="123" xmlns:y="urn:1" />
</x:root>

如果出现命名空间冲突， XmlTextWriter 通过生成替换前缀来解决它们。 例如，如果某属性和元素具有相同前缀但使用不同的命名空间、 XmlWriter 生成替换前缀的属性。 生成的前缀命名 n{i} 其中 i 是从 1 开始的数字。 编号为 1。 对于每个元素重置。

与命名空间 URI 关联的属性必须具有前缀 （命名空间不适用于属性的默认值）。 这符合 W3C XML 建议中的命名空间的 5.2 节。 如果属性引用的命名空间 URI，但未指定前缀，则编写器将生成该属性的前缀。

当编写一个空元素，一个额外的空格之间添加标记名称和结束标记，例如 <item />。 这提供了与旧的浏览器兼容性。

当 String 作为方法参数用于 null 和 String.Empty 是等效的。 String.Empty 遵循 W3C 规则。

若要编写强类型化的数据，使用 XmlConvert 类将数据类型转换为字符串。 例如，下面的 C# 代码将转换将数据从 Double 到 String 并写入元素 <price>19.95</price>。

Double price = 19.95;
writer.WriteElementString("price", XmlConvert.ToString(price));

XmlTextWriter 不会检查以下︰

• 属性和元素名称中的无效字符。

• 不符合指定的编码的 Unicode 字符。 如果指定的编码，不能容纳的 Unicode 字符 XmlTextWriter 未转义的字符实体到 Unicode 字符。

• 重复的属性。

• DOCTYPE 公共标识符或系统标识符中的字符。

安全注意事项

以下各项是在使用时应考虑事项 XmlTextWriter 类。

• 引发的异常 XmlTextWriter 可能会泄露冒泡到应用程序不希望的路径信息。 应用程序必须捕获异常并进行相应的处理。

• 在将 XmlTextWriter 传递给另一个应用程序时，基础流会公开给该应用程序。 如果需要将 XmlTextWriter 传递给不完全可信的应用程序，应使用通过 XmlWriter 方法创建的 Create 对象。

• XmlTextWriter 没有验证传递到任何数据 WriteDocType 或 WriteRaw 方法。 不应将任意数据传递给这些方法。

• 如果更改默认设置，则不能保证生成的输出是格式良好的 XML 数据。

• 不接受支持组件，如 Encoding 来自受信任的源对象。

版本信息

.NET Framework
自 1.1 起可用

线程安全

此类型的所有公共静态（Visual Basic 中的 已共享 在 Visual Basic 中）成员都是线程安全的。不保证所有实例成员都是线程安全的。

另请参阅

System.Xml 命名空间
XML 文档和数据