Внешние компоненты для 1С

Что такое внешняя компонента

Внешняя компонента (ВК) — это скомпилированная библиотека (.dll для Windows, .so для Linux, .dylib для macOS), написанная на компилируемом языке (как правило, C++), которая добавляет коду 1С новые методы и свойства. Фактически это подключаемый модуль расширения платформы.

Взаимодействие платформы с компонентой построено на фиксированном программном контракте. Актуальный контракт — Native API: компонента реализует набор интерфейсов из SDK 1С (комплект «Технология создания внешних компонент» с ИТС), а платформа вызывает её методы. Ранее применялся также COM-вариант (подключение через ПодключитьВнешнююКомпоненту с типом COM), но он привязан к Windows и постепенно выходит из употребления. Для нового кода следует использовать Native API: он кроссплатформенный (Windows/Linux/macOS) и работает как на клиенте, так и на сервере.

Важно понимать границу применимости. Компонента не имеет доступа к объектам конфигурации — справочникам, документам, регистрам. Она принимает на вход примитивные типы (числа, строки, двоичные данные) и возвращает примитивные типы. Бизнес-логика остаётся в 1С; компонента выполняет единственную операцию, недоступную средствами платформы.

Назначение

Применение внешней компоненты оправдано, когда задача выходит за пределы возможностей BSL. Типичные сценарии:

• Работа с оборудованием. Фискальные регистраторы, сканеры штрихкодов, весы, эквайринговые терминалы — драйверы оборудования 1С почти всегда реализованы как внешние компоненты.
• Ресурсоёмкие вычисления. Обработка изображений, сжатие, хеширование больших объёмов данных, разбор бинарных форматов. Операции, которые в BSL выполнялись бы минутами или были бы невозможны, в нативном коде занимают миллисекунды. Пример: сжатие изображений для прайс-листа с тысячами позиций на чистом BSL либо неприемлемо медленно, либо требует запуска внешнего исполняемого файла; компонента на базе библиотеки stb_image решает задачу непосредственно в процессе.
• Криптография и интеграции. Обращение к системным криптографическим библиотекам, специализированным API и протоколам, для которых нет готового HTTP- или COM-интерфейса.
• Доступ к операционной системе. Низкоуровневые операции с файловой системой, реестром, устройствами, недоступные в безопасной модели 1С.

Обратная сторона — случаи, когда компонента не требуется. Если задача решается HTTP-сервисом, COM-объектом операционной системы, фоновым заданием или штатным механизмом БСП, следует использовать их. Компонента — это код на C++, который необходимо собирать под каждую платформу, подписывать, версионировать и сопровождать. Это существенная стоимость владения, которую не стоит принимать при наличии более простого решения.

Правильное подключение

Основная сложность при работе с внешними компонентами — не разработка, а корректное подключение. Дальнейшие действия зависят от того, есть ли у вас готовый архив с компонентой. Рассмотрим оба случая на примере конфигурации на БСП (УТ/КА/ERP/Розница).

Если у вас есть архив с компонентой

Это основной сценарий: архив получен от поставщика или разработчика, а код подключения уже реализован в поставляемой обработке. От вас требуется одно действие — загрузить архив в справочник.

Загрузка в справочник «Внешние компоненты»

В конфигурациях на БСП предусмотрен справочник «Внешние компоненты». Архив загружается через НСИ и администрирование → Печатные формы, отчёты и обработки → Внешние компоненты → Добавить → Из файла. Идентификатор, версия и наименование заполняются автоматически из INFO.XML внутри архива:

<?xml version="1.0" encoding="UTF-8"?>
<drivers>
  <component progid="AddIn.ImageResizer"
             name="Сжатие картинок"
             version="1.0.0.0"
             type=""/>
</drivers>

Идентификатор компоненты — значение progid без префикса AddIn. (то есть ImageResizer). Именно по нему обработка обращается к компоненте.

О цифровой подписи

Распространено мнение, что сбой подключения вызван отсутствием цифровой подписи. При подключении через справочник БСП подпись не проверяется — неподписанная Native-компонента подключается штатно (проверено на УТ 11.5, платформа 8.3.27/8.5). Блокировка в базах с защитой ВК относится к способу подключения (прямой вызов из кода в обход справочника), а не к проверке подписи: подписанная и неподписанная компоненты одинаково не подключаются прямым вызовом. Подпись в данном случае значения не имеет и является ложным направлением при диагностике.

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

Если у вас нет архива с компонентами

Это сценарий разработчика: компоненту нужно упаковать в архив, загрузить в справочник и обратиться к ней из кода. Архив представляет собой zip с фиксированной структурой:

ImageResizer.zip
├── MANIFEST.XML
├── INFO.XML
├── ImageResizer_win32.dll
├── ImageResizer_win64.dll
└── libImageResizer_lin64.so

Назначение файлов архива: MANIFEST.XML — манифест с перечнем библиотек по ОС и разрядности; INFO.XML — данные для автозаполнения справочника; далее — бинарные файлы компоненты, обязательно в корне архива, без вложенных папок.

Манифест задаёт соответствие файлов операционным системам и разрядности:

<?xml version="1.0" encoding="UTF-8"?>
<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle"
        name="ImageResizer">
  <component os="Windows" arch="i386"
             type="native"
             path="ImageResizer_win32.dll"/>
  <component os="Windows" arch="x86_64"
             type="native"
             path="ImageResizer_win64.dll"/>
  <component os="Linux" arch="x86_64"
             type="native"
             path="libImageResizer_lin64.so"/>
</bundle>

Два требования, нарушение которых приводит к трудно диагностируемым сбоям:

1. Файл манифеста должен называться строго MANIFEST.XML — заглавными буквами. Платформа ищет файл именно с таким именем. Файл MANIFEST.xml (строчными) не находится, и платформа выдаёт обобщённое сообщение «Не найден файл внешней компоненты», хотя фактическая причина — регистр имени манифеста. Это наименее очевидная из возможных причин: сообщение указывает на файл компоненты, а проблема в имени манифеста.
2. В архиве должны присутствовать обе разрядности Windows — i386 и x86_64. Тонкий клиент 1С бывает как 32-, так и 64-разрядным. При отсутствии требуемой разрядности возникает то же сообщение «Не найден файл внешней компоненты». Несоответствие разрядности — частая причина сбоя подключения, не связанная с кодом.

Собранный архив загружается в справочник «Внешние компоненты» так же, как описано в предыдущем пункте. После этого компоненту подключают из кода.

Подключение из кода

Не следует подключать компоненту прямым вызовом ПодключитьВнешнююКомпоненту. В типовых конфигурациях на БСП включена защита внешних компонент, и прямой вызов — из файла, из двоичных данных, из макета, из временного хранилища — возвращает Ложь с тем же обобщённым сообщением в журнале регистрации. Так блокируется любая компонента, включая подписанную самой 1С и эталонный шаблон из SDK. Изменение способа передачи местоположения компоненты результата не даёт — не работает ни один.

Корректный способ — штатный механизм БСП, метод ПодключитьКомпоненту (его не следует путать с ПодключитьВнешнююКомпоненту):

МД = Метаданные.ОбщиеМодули;
Если МД.Найти("ВнешниеКомпонентыСервер") <> Неопределено Тогда

    Модуль = ОбщегоНазначения.ОбщийМодуль(
        "ВнешниеКомпонентыСервер");
    Рез = Модуль.ПодключитьКомпоненту("ImageResizer");

    Если Рез.Подключено Тогда
        Компонента = Рез.ПодключаемыйМодуль;
        Сжатое = Компонента.СжатьИзображение(
            ДвоичныеДанные, 100, 100, 60);
    Иначе
        ЗаписьЖурналаРегистрации(
            "МояПодсистема.ВК",
            УровеньЖурналаРегистрации.Предупреждение,
            , , Рез.ОписаниеОшибки);
    КонецЕсли;

КонецЕсли;

Метод ВнешниеКомпонентыСервер.ПодключитьКомпоненту(Идентификатор) возвращает структуру {Подключено, ПодключаемыйМодуль, ОписаниеОшибки}. Объект компоненты находится в поле ПодключаемыйМодуль, а ОписаниеОшибки содержит конкретную причину сбоя — в отличие от обобщённого сообщения при прямом вызове.

Детали, важные для промышленного применения:

• Обращение через ОбщегоНазначения.ОбщийМодуль(...) с предварительной проверкой Метаданные.ОбщиеМодули.Найти(...) обеспечивает компиляцию кода и в конфигурациях без подсистемы внешних компонент, с предусмотренным запасным вариантом.
• Для клиента предусмотрен асинхронный аналог — ВнешниеКомпонентыКлиент.ПодключитьВнешнююКомпоненту(...) с описанием оповещения.
• Целесообразно предусматривать запасной вариант: если компонента не подключилась, должен существовать альтернативный путь выполнения операции (например, через внешний исполняемый файл или без оптимизации). Отказ функциональности из-за незагруженной компоненты недопустим.

Диагностика: компонента не подключается

При появлении сообщения «Не найден файл внешней компоненты» следует проверить по порядку:

1. Файл манифеста в архиве называется MANIFEST.XML заглавными буквами?
2. В манифесте указаны обе разрядности Windows (i386 и x86_64)?
3. Файлы расположены в корне архива, а значения path в манифесте совпадают с именами записей в zip с точностью до регистра?
4. Подключение выполняется через ВнешниеКомпонентыСервер.ПодключитьКомпоненту (БСП), а не прямым вызовом ПодключитьВнешнююКомпоненту?
5. Компонента загружена в справочник «Внешние компоненты»?

В большинстве случаев причина находится в первых двух пунктах.

Заключение

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