Класс System.XmlWriter

Класс XmlWriter записывает XML-данные в поток, файл, средство чтения текста или строку. Он поддерживает расширяемый язык разметки W3C (XML) 1.0 (четвертый выпуск) и пространства имен в рекомендациях XML 1.0 (третий выпуск ).

Члены XmlWriter класса позволяют:

• Убедитесь, что символы являются юридическими XML-символами, а имена элементов и атрибутов являются допустимыми XML-именами.
• Убедитесь, что XML-документ хорошо сформирован.
• Закодируйте двоичные байты как Base64 или BinHex и выпишите полученный текст.
• Передайте значения с помощью типов среды CLR вместо строк, чтобы избежать необходимости вручную выполнять преобразования значений.
• Запись нескольких документов в один выходной поток.
• Укажите допустимые имена, квалифицированные имена и токены имен.

Создайте 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 проверять символы и вызывать 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 методы. Примеры см. в перечисленных методах.

Записать атрибуты

Для записи атрибутов на узлах элементов можно использовать следующие XmlWriter методы. Эти методы также можно использовать для создания объявлений пространства имен в элементе, как описано в следующем разделе.

Управление пространствами имен

Пространства имен используются для квалификации имен элементов и атрибутов в XML-документе. Префиксы пространства имен связывают элементы и атрибуты с пространствами имен, которые, в свою очередь, связаны со ссылками на URI. Пространства имен создают уникальность имени элемента и атрибута в XML-документе.

Он XmlWriter поддерживает стек пространства имен, соответствующий всем пространствам имен, определенным в текущей области пространства имен. При написании элементов и атрибутов можно использовать пространства имен следующим образом:

• Объявите пространства имен вручную с помощью WriteAttributeString метода. Это может быть полезно, если вы знаете, как наилучшим образом оптимизировать количество объявлений пространства имен. Пример см. в методе WriteAttributeString(String, String, String, String) .

• Переопределите текущее объявление пространства имен новым пространством имен. В следующем коде метод WriteAttributeString изменяет URI пространства имен для префикса "x" с "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 правил для этого типа схемы.

Сведения о типах данных XSD по умолчанию, соответствующих типам CLR, см. метод 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 метод. Не следует передавать произвольные данные этим методам.