Класс System.XmlWriter

Статья
01/04/2024

Класс 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 форматированием выходных данных:

Свойство	Description
Encoding	Указывает кодировку текста, которую следует использовать. Значение по умолчанию — `Encoding.UTF8`.
Indent	Показывает, нужны ли отступы элементов. Значение по умолчанию — `false` без отступа.
IndentChars	Указывает символьную строку для использования при отступе. По умолчанию - два пробела.
NewLineChars	Указывает символьную строку, используемую для разрывов строки. Значение по умолчанию — `\r\n` (возврат каретки, канал строк) для платформ, отличных от Unix, и `\n` (канал строк) для платформ Unix.
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 проверка символов и вызывать XmlException исключение, если какие-либо символы находятся за пределами юридического диапазона, как определено W3C.

Свойство ConformanceLevel настраивает модуль записи XML на проверка, что поток, написанный, соответствует правилам для хорошо сформированного XML-документа или фрагмента документа, определенного W3C. Три уровня соответствия описаны в следующей таблице. Значение по умолчанию — Document. Дополнительные сведения см. в свойстве XmlWriterSettings.ConformanceLevel System.Xml.ConformanceLevel и перечислении.

Level	Description
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 метод изменяет 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, преобразует входное значение в строковое представление в соответствии с правилами преобразования типов данных 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 метод. Не следует передавать произвольные данные этим методам.