Как добавить XDTO-пакет в расширение 1С

XDTO-пакеты в 1С описывают структуры данных для обмена через веб-сервисы, XML-файлы и механизмы сериализации. Когда типовой конфигурации не хватает нужного пакета — например, для интеграции с внешним API или обработки файла нестандартного формата — разработчик сталкивается с вопросом: можно ли добавить XDTO-пакет через расширение, не меняя основную конфигурацию.

Ответ зависит от версии платформы 1С:Предприятие и от того, что именно требуется сделать. Заимствование существующего пакета из основной конфигурации в расширение поддерживается давно, а вот создание полностью нового пакета внутри расширения имеет ограничения, которые важно понимать до начала работы. Ниже разобраны оба сценария с конкретными шагами в конфигураторе.

Что такое XDTO-пакет и когда он нужен в расширении

XDTO-пакет (XML Data Transfer Objects) — это объект метаданных, описывающий типы данных, которые платформа может сериализовать в XML и обратно. Каждый пакет привязан к пространству имён (namespace) и содержит набор типов значений и типов объектов.

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

Добавлять пакет в расширение имеет смысл, когда нельзя или нежелательно изменять основную конфигурацию: она на поддержке у поставщика, обновляется автоматически, а доработка должна переживать обновления без ручного сравнения и объединения.

Как заимствовать существующий XDTO-пакет из конфигурации

Самый частый сценарий — нужно изменить или дополнить пакет, который уже есть в основной конфигурации, например пакет, созданный при подключении типового веб-сервиса. Порядок действий следующий.

1. 1
   Откройте конфигуратор и подключите расширение (Конфигурация → Расширения конфигурации → создать или открыть существующее)
2. 2
   В дереве конфигурации найдите ветку «XDTO-пакеты» и нужный пакет
3. 3
   Щёлкните по пакету правой кнопкой мыши и выберите «Добавить в расширение»
4. 4
   Убедитесь, что пакет появился в дереве расширения с пометкой заимствования
5. 5
   Откройте свойства заимствованного пакета и проверьте пространство имён — оно должно совпадать с исходным
6. 6
   Сохраните расширение и обновите конфигурацию базы данных

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

Изменять структуру заимствованного пакета в расширении, как правило, нельзя — расширение работает с пакетом «как есть». Если нужна другая структура типов, потребуется отдельный новый пакет.

Как создать новый XDTO-пакет непосредственно в расширении

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

Чтобы создать новый пакет, откройте дерево метаданных расширения, найдите ветку «XDTO-пакеты», вызовите контекстное меню и выберите «Добавить». В свойствах пакета задайте имя и пространство имён — именно по пространству имён платформа будет идентифицировать пакет при сериализации.

Далее добавьте в пакет типы: типы значений (простые типы с ограничениями — длина строки, диапазон числа, шаблон) и типы объектов (структуры со свойствами). Свойства типа объекта ссылаются на типы значений из этого же пакета, из стандартного пространства имён http://www.w3.org/2001/XMLSchema или из других пакетов.

Импорт пакета из XSD-схемы или WSDL

Вручную описывать сложную структуру типов долго и чревато ошибками. Если у вас есть XSD-схема от контрагента или WSDL-описание веб-сервиса, пакет создаётся автоматически.

Для XSD-схемы используйте конструктор: при создании пакета выберите вариант импорта из XML-схемы и укажите файл .xsd. Платформа построит типы по схеме, включая вложенные объекты и ограничения. Для веб-сервиса пакет создаётся при добавлении WS-ссылки: укажите URL WSDL, и платформа сформирует пакет с типами операций и сообщений сервиса.

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

Если WSDL веб-сервиса периодически меняется, удобнее держать пакет в основной конфигурации через WS-ссылку с возможностью обновления, а в расширении размещать только код обработки данных. Иначе каждое изменение схемы потребует ручной правки пакета в расширении.

Как обратиться к пакету из кода расширения

После добавления пакета работа с ним в модуле расширения выглядит стандартно. Типы доступны через глобальную фабрику XDTO, обращение идёт по пространству имён:

Фабрика = ФабрикаXDTO;
ТипОбъекта = Фабрика.Тип("http://example.org/scheme", "ЗаказПокупателя");
НовыйОбъект = Фабрика.Создать(ТипОбъекта);
НовыйОбъект.Номер = "ЗП-001";
НовыйОбъект.Дата = ТекущаяДатаСеанса();

Для записи объекта в XML используется ЗаписьXML совместно с методом ФабрикаXDTO.ЗаписатьXML(), для чтения — ЧтениеXML и ФабрикаXDTO.ПрочитатьXML(). Если тип элемента в файле не найден в фабрике, чтение вернёт объект неопределённого типа или вызовет исключение — это первый признак того, что пакет не подключился.

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

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

Пакет виден в дереве расширения

Норма

Пакет отображается в ветке «XDTO-пакеты» без значков ошибки

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

Пакет помечен как отсутствующий в основной конфигурации

Проверка применимости расширения

Норма

Расширение подключается без ошибок после обновления конфигурации БД

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

Ошибка применимости со ссылкой на пакет

Доступ к типу из кода

Норма

ФабрикаXDTO.Тип() возвращает тип по пространству имён

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

Возвращается Неопределено или исключение «Тип не найден»

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

Главное ограничение — версия платформы. На платформах младше 8.3.11 собственные XDTO-пакеты в расширении создать нельзя, доступно только заимствование. Второе ограничение касается режима совместимости: если конфигурация работает в режиме совместимости со старой версией, часть возможностей расширений отключается даже на новой платформе.

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

Альтернатива: работа без XDTO-пакета

Не всегда пакет обязателен. Если структура XML простая или нестабильная, можно читать и писать XML напрямую через ЧтениеXML/ЗаписьXML построчно, без типизации. Это быстрее в реализации, но лишает контроля типов и проверки обязательных полей на уровне платформы.

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

Маршрут решения

Как выбрать подход

Нужно изменить поведение типового пакета без правки конфигурацииЗаимствуйте пакет в расширение и работайте с ним из кода расширения

Нужен полностью новый формат обмена и платформа 8.3.11 или новееСоздайте собственный XDTO-пакет в расширении с уникальным пространством имён

Платформа старше 8.3.11 или режим совместимости блокирует новые объектыДобавьте пакет в основную конфигурацию, а логику обработки разместите в расширении

Структура XML простая и часто меняетсяРассмотрите работу через ЧтениеXML/ЗаписьXML без XDTO-пакета

Частые вопросы

Можно ли в расширении изменить типы заимствованного XDTO-пакета?

Нет. Заимствованный пакет доступен в расширении только для использования, его структуру типов изменить нельзя. Если нужна другая структура, создайте в расширении собственный пакет с отдельным пространством имён и работайте с ним.

Почему кнопка «Добавить» в ветке XDTO-пакетов расширения неактивна?

Чаще всего причина в версии платформы ниже 8.3.11 либо в режиме совместимости конфигурации, установленном на старую версию. Проверьте оба параметра: версию сервера и свойство «Режим совместимости» в свойствах конфигурации.

Что произойдёт с расширением, если в основной конфигурации удалят заимствованный пакет?

Расширение перестанет проходить проверку применимости и отключится с ошибкой. Поэтому при обновлениях конфигурации, где меняются XDTO-пакеты, проверяйте расширения заранее на копии базы.

Как импортировать XSD-схему в пакет расширения?

При создании нового пакета используйте вариант импорта из XML-схемы и укажите файл .xsd. Платформа построит типы автоматически. После импорта проверьте имена типов и корректность вложенных структур.

Код не видит типы пакета, хотя пакет добавлен. Что проверить?

Сначала обновите конфигурацию базы данных — без этого новые метаданные недоступны в сеансе. Затем проверьте пространство имён в вызове ФабрикаXDTO.Тип(): оно должно точно совпадать со свойством пакета, включая регистр и слэши.

Можно ли использовать пакет расширения в веб-сервисе, опубликованном отдельно?

Да, если сам веб-сервис или его обработчики доступны в расширении. Но учитывайте, что WSDL публикуемого сервиса формируется из пакетов конфигурации; если типы defined только в расширении, убедитесь, что расширение активно в сеансе, обслуживающем веб-сервис.