Пакет XDTO внутри расширения 1С: создание, загрузка схемы, проверка

Пакет XDTO в расширение добавляется так: откройте расширение в конфигураторе, в дереве найдите ветку «Общие» → «Пакеты XDTO», вызовите контекстное меню и выберите «Добавить». Задайте имя и уникальное пространство имён, затем опишите типы вручную или загрузите готовую XSD-схему. После сохранения расширения пакет доступен в коде через ФабрикаXDTO.

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

Ниже — порядок действий, настройки пакета, работа с типами в коде и разбор ошибок, на которых чаще всего спотыкаются.

Что проверить до добавления пакета

Пять минут проверки сэкономят час разбирательств. Начните с четырёх вещей.

• ✅ Расширение уже создано и открыто в конфигураторе. Если нет — создайте через «Конфигурация» → «Расширения конфигурации » → «Добавить».
• ✅ Назначение расширения понятно: оно будет работать в той базе, где схема нужна. Схема, собранная под одну базу, в другой может конфликтовать по пространству имён.
• ✅ Пространство имён свободно. В основной конфигурации и в других расширениях не должно быть пакета с тем же URI.
• ✅ Есть схема-источник: XSD-файл от партнёра, описание формата или хотя бы образец XML.

Как найти конфликт пространства имён заранее

Откройте основную конфигурацию и посмотрите ветку «Общие» → «Пакеты XDTO». У каждого пакета есть свойство «Пространство имён». Сравните со своим. Расширения проверьте так же: у каждого своё дерево.

Проще всего выполнить проверку из кода в консоли, на тестовой копии базы:

Для Каждого Пакет Из ФабрикаXDTO.Пакеты Цикл
    Сообщить(Пакет.URIПространстваИмен);
КонецЦикла;

В списке окажутся и пакеты расширений, если они подключены. Ищите свой URI, прежде чем придумывать новый.

Создание пакета XDTO в расширении через конфигуратор

Сам механизм почти не отличается от добавления пакета в обычную конфигурацию. Разница в том, что объект попадает в расширение, а не в основную конфигурацию.

1. Откройте конфигуратор в той базе, где подключено расширение.
2. Выберите «Конфигурация» → «Расширения конфигурации» и откройте нужное расширение. В дереве слева появится структура расширения.
3. Раскройте ветку «Общие», найдите «Пакеты XDTO».
4. Нажмите правой кнопкой по ветке и выберите «Добавить».
5. В палитре свойств задайте «Имя» (латиницей или кириллицей без пробелов) и «Синоним» — по нему пакет видят в интерфейсе.
6. Заполните «Пространство имён» — URI, например http://example.org/exchange/orders.
7. Откройте окно пакета двойным щелчком и опишите типы или загрузите схему (следующий раздел).
8. Сохраните расширение: «Конфигурация» → «Сохранить конфигурацию расширения» либо кнопка с дискетой.

💡 Если нужного пункта «Добавить» нет, проверьте, что вы работаете именно в окне расширения, а не в основной конфигурации. Окна похожи, и путаница случается чаще, чем кажется.

Заимствование чужого пакета

Бывает, что нужен не новый пакет, а доработка существующего из типовой конфигурации. Тогда в контекстном меню ищите «Заимствовать из основной конфигурации». Заимствованный пакет остаётся связанным с оригиналом, и вносить в него произвольные правки можно не везде. Для нового формата лучше создать собственный пакет с отдельным пространством имён: это надёжнее и не ломается при обновлении поставщика.

Загрузка схемы и настройка пространства имён

Описывать сложную схему руками в редакторе неудобно. Если у вас есть XSD, загружайте файлом.

В окне пакета используйте команду загрузки схемы из файла (она находится в командной панели окна и в меню «Действия»). Выберите XSD. Конфигуратор разберёт типы, элементы и импортируемые пространства имён.

После загрузки проверьте три вещи:

• что в поле «Пространство имён» стоит именно тот URI, который указан в атрибуте targetNamespace схемы;
• что все типы появились в дереве окна пакета, в том числе вложенные;
• что нет «висячих» ссылок на пакеты, которых нет в расширении (подробнее — в разделе про зависимости).

Пространство имён: правила, которые сэкономят нервы

Пространство имён — это идентификатор пакета. По нему код находит тип: ФабрикаXDTO.Тип("http://example.org/exchange/orders", "Заказ").

Если схема партнёра уже содержит свой targetNamespace, не переписывайте его. Нужно, чтобы XML, который вы получаете и отправляете, совпадал по пространствам имён с ожиданием другой стороны.

Зависимости между пакетами

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

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

Типы данных и коллекции XDTO в коде расширения

Пакет создан. Теперь им надо пользоваться. Основа — три объекта: ФабрикаXDTO, ОбъектXDTO, СписокXDTO.

Создание объекта по типу

URI = "http://example.org/exchange/orders";

ТипЗаказ = ФабрикаXDTO.Тип(URI, "Заказ");
Заказ = ФабрикаXDTO.Создать(ТипЗаказ);

Заказ.Номер = "ЗК-00125";
Заказ.Дата = ТекущаяДата();
Заказ.Сумма = 15400.50;

Свойство с неверным именем вызовет исключение: объект XDTO — строго типизирован, и придумать новое поле на лету нельзя. Это защита от опечаток.

Вложенные объекты и списки

Если свойство в схеме имеет maxOccurs больше единицы, оно превращается в список — СписокXDTO. Добавляйте элементы методом Добавить.

ТипСтрока = ФабрикаXDTO.Тип(URI, "СтрокаЗаказа");

Для Каждого Позиция Из ТаблицаТоваров Цикл
    Строка = ФабрикаXDTO.Создать(ТипСтрока);
    Строка.Артикул = Позиция.Артикул;
    Строка.Количество = Позиция.Количество;
    Заказ.Строки.Добавить(Строка);
КонецЦикла;

Типичная ловушка: обращение к необязательному свойству, которое не задано. Проверяйте методом Установлено:

Если Заказ.Установлено("Комментарий") Тогда
    Текст = Заказ.Комментарий;
КонецЕсли;

Запись и чтение XML

Сериализацию делает фабрика через ЗаписьXML и ЧтениеXML:

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

Обратная операция — ФабрикаXDTO.ПрочитатьXML(Чтение). Если XML не соответствует схеме, платформа выбросит исключение с описанием: какой элемент ожидался и какой встретился.

Простые типы, перечисления и даты

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

• 📏 Длина строки. Значение длиннее maxLength вызовет исключение при присвоении. Обрезайте строку заранее.
• 📋 Перечисление. Допустимы только значения из списка в схеме. Регистр имеет значение: «Новый» и «новый» для схемы разные.
• 📅 Даты. Тип dateTime записывается в формате ISO с разделителем T. Если партнёр ждёт только дату, в схеме будет тип date, и время отбросится.
• 🔢 Числа. Количество знаков после запятой задаёт схема. Округляйте до записи, а не надейтесь на платформу.

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

Работа в клиент-серверной базе: где выполняется код

В файловом варианте всё просто: клиент и «сервер» — один процесс. В клиент-серверном (и в веб-клиенте) разница есть.

• 🖥 Фабрика XDTO доступна и на клиенте, и на сервере. Но для обмена с внешними системами правильнее работать на сервере: там доступны регламентные задания, веб-сервисы, длительные операции.
• 🔗 Пакеты расширения видны в сессиях, где расширение подключено. Если расширение подключили, а сеанс уже был открыт, перезапустите клиент: старый сеанс его не подхватит.
• 🌐 Для веб-сервисов с XDTO используйте серверные процедуры с директивой &НаСервере и передавайте клиенту уже готовый результат, а не сам объект XDTO.
• ⚙️ В регламентных заданиях расширение должно быть активным в базе и для этого режима: проверьте у расширения свойства подключения.

Передача между клиентом и сервером

Объект XDTO нельзя уверенно передавать как параметр процедуры между контекстами. Передавайте строку XML и разбирайте её на нужной стороне. Это скучно, но предсказуемо и одинаково работает в тонком клиенте, веб-клиенте и толстом клиенте.

Как проверить, что пакет работает

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

1. Откройте консоль кода в режиме 1С:Предприятие (внешняя обработка или обработка расширения).
2. Выполните ФабрикаXDTO.Пакеты.Получить("http://example.org/exchange/orders").
3. Если вернулся объект пакета — он подгружен. Если Неопределено — расширение не подключено или URI написан иначе.
4. Создайте объект нужного типа, запишите в XML и прочитайте обратно.

Типичные ошибки и способы их устранения

Здесь собраны сбои именно при работе с XDTO в расширениях. Выберите свой симптом.

Что делать, если расширение не применяется после правки пакета

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

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