1С XDTO: что это такое и как использовать механизм на практике

XDTO (XML Data Transfer Objects) — это встроенный в платформу 1С:Предприятие механизм для описания, передачи и чтения данных в формате XML. Он связывает типы данных 1С с XML-схемами и позволяет превращать объекты конфигурации — документы, справочники, регистры — в XML-документы и обратно без ручного разбора тегов.

Механизм чаще всего применяется в интеграциях: обмен с банками и контрагентами, взаимодействие с веб-сервисами, загрузка и выгрузка данных между базами, работа с форматами ЭДО и государственными схемами (например, требования ФНС к электронным документам описаны именно XML-схемами). Там, где есть формально описанная схема данных, XDTO обычно удобнее ручной работы с XML.

В отличие от низкоуровневых объектов ЧтениеXML и ЗаписьXML, XDTO оперирует типизированными объектами: разработчик обращается к свойствам объекта по именам, а платформа сама следит за соответствием схеме, типами значений и обязательностью полей. Это снижает количество ошибок формата, но требует понимания того, как устроены пакеты и фабрика XDTO.

Из чего состоит механизм XDTO

Основа механизма — пакет XDTO. Это объект конфигурации (ветка «Общие → XDTO-пакеты» в дереве конфигуратора), который содержит описание типов данных: простые типы (строки, числа, даты с ограничениями) и составные типы объектов со свойствами. Каждый пакет привязан к пространству имён XML — уникальному URI, который идентифицирует набор типов.

Второй ключевой элемент — фабрика XDTO (объект ФабрикаXDTO). Фабрика «знает» один или несколько пакетов и умеет создавать объекты и значения описанных в них типов, а также читать и записывать XML. Глобальная фабрика платформы включает все пакеты конфигурации и системные типы; при необходимости можно создать собственную фабрику из произвольного набора XSD-схем.

Третий элемент — объекты XDTO (ОбъектXDTO) и значения XDTO (ЗначениеXDTO). Объект соответствует составному типу и имеет свойства, значение — простому типу. Работа с ними в коде похожа на работу со структурами: свойства читаются и устанавливаются по имени, вложенные объекты образуют дерево.

Как создать и настроить пакет XDTO

Самый быстрый способ получить пакет — импортировать готовую XSD-схему. В конфигураторе создайте новый XDTO-пакет, откройте его и воспользуйтесь командой импорта схемы, указав файл .xsd. Платформа автоматически создаст типы объектов, их свойства, простые типы с фасетами (ограничениями длины, шаблонами, перечислениями) и пространство имён. Так обычно поступают со схемами ФНС, банковскими форматами и WSDL-описаниями веб-сервисов.

Если схемы нет, пакет описывается вручную. Задайте URI пространства имён, затем добавьте типы объектов и для каждого определите свойства: имя, тип (простой или ссылка на другой тип объекта), нижнюю и верхнюю границу количества (0..1 — необязательное, 1..1 — обязательное, -1 — неограниченный список). Для простых типов можно задать фасеты: минимальную и максимальную длину строки, шаблон регулярного выражения, перечисление допустимых значений.

Практическая рекомендация: не смешивайте в одном пакете типы из разных предметных областей. Если выгружаете контрагентов и счета, удобнее держать два пакета с разными пространствами имён — так проще обновлять схемы независимо и меньше риск конфликтов имён типов.

Как записать объект в XML

Типовой сценарий выгрузки выглядит так: создаётся объект XDTO нужного типа через фабрику, заполняются его свойства, затем фабрика записывает объект в XML. В коде это занимает несколько строк:

ТипДокумента = ФабрикаXDTO.Тип("http://example.org/orders", "Заказ");
ОбъектЗаказ = ФабрикаXDTO.Создать(ТипДокумента);
ОбъектЗаказ.Номер = "А-1024";
ОбъектЗаказ.Дата = ТекущаяДатаСеанса();
ОбъектЗаказ.Контрагент = "ООО Ромашка";

Запись = Новый ЗаписьXML;
Запись.УстановитьСтроку("UTF-8");
ФабрикаXDTO.ЗаписатьXML(Запись, ОбъектЗаказ);
СтрокаXML = Запись.Закрыть();

Если свойство объявлено как список (верхняя граница -1 или больше 1), оно представлено объектом СписокXDTO, и элементы добавляются методом Добавить(). Необязательные свойства можно не заполнять — они просто не попадут в XML. А вот обязательное незаполненное свойство вызовет ошибку при записи, потому что результат не пройдёт валидацию по схеме.

Проверять результат удобно валидацией: метод ФабрикаXDTO.Проверить() до записи покажет, нарушает ли заполненный объект ограничения схемы. Это дешевле, чем получить отказ от внешней системы, которая отвергнет некорректный файл.

1. 1
   Импортируйте XSD-схему или опишите пакет XDTO вручную в конфигураторе
2. 2
   В коде получите тип через ФабрикаXDTO.Тип() и создайте объект методом Создать()
3. 3
   Заполните обязательные свойства, списки заполните через Добавить()
4. 4
   Проверьте объект методом ФабрикаXDTO.Проверить()
5. 5
   Запишите объект через ЗаписьXML и ФабрикаXDTO.ЗаписатьXML()
6. 6
   Сохраните строку в файл или передайте в HTTP-запрос

Как прочитать XML и разобрать данные

Чтение выполняется зеркально: создаётся объект ЧтениеXML, открывается файл или строка, и фабрика читает корневой элемент в объект XDTO. Дальше данные доступны как обычные свойства:

Чтение = Новый ЧтениеXML;
Чтение.УстановитьСтроку(СтрокаXML);
ОбъектЗаказ = ФабрикаXDTO.ПрочитатьXML(Чтение);
НомерЗаказа = ОбъектЗаказ.Номер;
Для Каждого СтрокаТовара Из ОбъектЗаказ.Товары.Товар Цикл
// обработка позиции
КонецЦикла;

Важный нюанс — работа с необязательными свойствами. Если свойство отсутствует в XML, обращение к нему вернёт Неопределено, и попытка сразу использовать значение (например, в арифметике или сравнении строк) может привести к ошибке. Безопасный приём — проверять наличие через метод Установлено() объекта XDTO или явное сравнение с Неопределено.

Если входящий XML не соответствует схеме — неизвестный элемент, нарушен порядок следования, неверный тип значения — метод ПрочитатьXML выбросит исключение с описанием ошибки валидации. Оборачивайте чтение в попытку/исключение и логируйте текст ошибки: сообщения платформы обычно содержат имя проблемного элемента и ожидаемый тип, что сильно ускоряет диагностику.

Контрольные точки

Как проверить результат обмена

Чтение XML без исключений

Норма

ПрочитатьXML вернул объект ожидаемого типа

Тревожный признак

Исключение с текстом ошибки валидации схемы

Обязательные свойства

Норма

Все обязательные поля заполнены значениями

Тревожный признак

Свойство равно Неопределено, запись падает

Списки

Норма

Количество элементов совпадает с источником

Тревожный признак

Одиночный элемент прочитан не как список

Кодировка и пространство имён

Норма

UTF-8, URI пространства совпадает со схемой

Тревожный признак

Кракозябры в строках, тип не найден фабрикой

Сериализация объектов конфигурации

Отдельный сценарий — сериализация объектов 1С (элементов справочников, документов) в XDTO без ручного маппинга. Класс СериализаторXDTO умеет превращать объекты базы в объекты XDTO системных пакетов и обратно: СериализаторXDTO.ЗаписатьXDTO(Объект) и СериализаторXDTO.ПрочитатьXDTO(ОбъектXDTO). Именно на этом построены типовые механизмы обмена и выгрузки конфигураций.

Такой подход удобен для переноса данных между идентичными или близкими конфигурациями, потому что сериализатор сохраняет ссылки, типы и состав реквизитов автоматически. Но для обмена с внешними системами он почти не подходит: внешняя сторона ожидает свою схему, а не внутреннее представление 1С. В интеграциях объекты заполняют вручную по схеме контрагента.

XDTO или ручная работа с XML: что выбрать

Выбор между XDTO и прямыми ЧтениеXML/ЗаписьXML зависит от наличия схемы и сложности формата. Если формат описан XSD или задан жёстко (ЭДО, веб-сервисы, банковские выписки), XDTO даёт валидацию, типизацию и защиту от опечаток в именах тегов — это почти всегда правильный выбор.

Если схемы нет, формат простой и нестабильный, либо нужно прочитать «чужой» XML с вольной структурой, потоковое чтение через ЧтениеXML может оказаться проще: не придётся вручную описывать пакет под каждый вариант входящего файла. Для JSON-обмена XDTO вообще не используется — там работают ЧтениеJSON/ЗаписьJSON и структуры.

Сравнение подходов к обмену

Пакеты XDTO + фабрика

Подходит при наличии XSD-схемы и строгого формата. Даёт валидацию и типизацию, но требует описания пакета и обновления при смене схемы.

ЧтениеXML / ЗаписьXML

Подходит для простых или нестабильных форматов без схемы. Полный контроль, но вся проверка структуры ложится на код разработчика.

СериализаторXDTO

Подходит для переноса объектов между базами 1С. Не подходит для интеграции с внешними системами.

ЧтениеJSON / ЗаписьJSON

Подходит для REST API и обмена JSON. К XML и XSD-схемам отношения не имеет.

Типичные ошибки и ограничения

Чаще всего проблемы возникают не в коде, а в несоответствии схемы и реальных данных. Пространство имён в XML не совпадает с URI пакета — фабрика не находит тип. В схеме элемент объявлен обязательным, а выгрузка его не заполняет — запись падает. Порядок элементов в схеме с последовательностью (sequence) нарушен — чтение завершается ошибкой, хотя все данные на месте.

Вторая группа ошибок — типы данных. Даты в XML передаются в формате ISO 8601, числа — с точкой в качестве разделителя; если внешняя система присылает локализованные форматы, валидация не пройдёт. Также стоит помнить о производительности: фабрика с большим количеством тяжёлых пакетов (например, полный комплект схем ЭДО) создаётся не мгновенно, поэтому в массовых операциях фабрику лучше создавать один раз и переиспользовать.

FAQ

Чем XDTO отличается от обычного ЧтениеXML?

ЧтениеXML — потоковый низкоуровневый разбор: разработчик сам обходит узлы и проверяет структуру. XDTO работает поверх схемы: данные представлены типизированными объектами, а платформа автоматически проверяет соответствие XML описанным типам, обязательность полей и порядок элементов.

Можно ли использовать XDTO без добавления пакета в конфигурацию?

Да. Можно программно создать собственную фабрику из XSD-файлов, загруженных во время выполнения, и работать через неё, не храня пакет в конфигураторе. Это удобно, когда схема часто меняется и поставляется внешней системой.

Почему ПрочитатьXML выдаёт ошибку «тип не найден»?

Чаще всего пространство имён корневого элемента во входящем XML не совпадает с URI пространства имён пакета, либо нужный пакет не входит в используемую фабрику. Сравните значение xmlns в файле с URI пакета в конфигураторе — они должны совпадать посимвольно.

Как выгрузить в XML список строк документа?

Опишите в пакете свойство со списочным типом (верхняя граница -1), а в коде добавляйте элементы через метод Добавить() списка XDTO, создавая каждый элемент фабрикой по его типу. При чтении такое свойство всегда возвращает СписокXDTO, который обходится циклом.

Подходит ли XDTO для обмена через REST API?

Как правило, нет: REST-сервисы обычно обмениваются JSON, и для них используются ЧтениеJSON и ЗаписьJSON. XDTO уместен там, где форматом является XML — SOAP-сервисы, ЭДО, банковские и государственные форматы.

Что делать, если схема внешней системы обновилась?

Импортируйте новую версию XSD в пакет, проверьте изменившиеся типы и свойства, найдите по конфигурации все обращения к затронутым типам и скорректируйте код. Затем протестируйте выгрузку и загрузку на копии базы, включая проверку валидатором внешней системы, если она его предоставляет.