Как добавить внешнюю компоненту в 1С

Внешняя компонента (ВК) — это библиотека, написанная не на встроенном языке 1С, а на C++, C# или другом языке, которая расширяет возможности платформы: работа со сканерами штрих-кодов, криптография, обмен с оборудованием, интеграция с нестандартными API. Подключить её можно двумя принципиально разными способами: классическая регистрация COM-библиотеки в операционной системе или современный механизм Native API, при котором компонента хранится прямо в информационной базе и подключается программно.

Выбор способа зависит от того, в каком виде вы получили компоненту. Если поставщик дал файл .dll и инструкцию «зарегистрируйте через regsvr32» — это COM-сценарий. Если компонента распространяется как zip-архив с манифестом manifest.xml и файлами для разных платформ — это Native API, и её правильное место хранения — макет конфигурации или общий макет.

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

Определите тип компоненты: Native API или COM

Прежде чем что-либо добавлять, посмотрите на состав поставки. Native API компонента обычно поставляется в виде zip-архива, внутри которого лежат несколько файлов .dll или .so для разных платформ (Windows 32/64, Linux, иногда Android и iOS) и файл manifest.xml, где перечислены эти файлы и их целевые платформы. Такая компонента не требует регистрации в системе и работает в том числе на тонком клиенте и в веб-клиенте (при наличии соответствующей сборки).

COM-компонента — это, как правило, один файл .dll (или .ocx), который регистрируется в реестре Windows и становится доступен по программному идентификатору ProgID. Этот вариант работает только на Windows и только там, где библиотека зарегистрирована: на сервере 1С, если код выполняется на сервере, или на каждом клиентском компьютере, если код клиентский.

Если сомневаетесь, откройте файл поставки: наличие manifest.xml однозначно указывает на Native API. Документация поставщика обычно прямо указывает технологию и пример кода подключения — ориентируйтесь на него.

Добавьте компоненту в макет конфигурации

Для Native API стандартный способ хранения — макет с типом «Двоичные данные». Откройте конфигуратор, перейдите в ветку «Общие» → «Макеты» (или создайте макет внутри конкретного объекта), добавьте новый макет, задайте ему имя без пробелов и кириллицы, например КомпонентаСканер, выберите тип «Двоичные данные» и загрузите в него zip-архив компонента целиком, не распаковывая.

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

1. 1
   Откройте конфигуратор и ветку «Общие» → «Макеты»
2. 2
   Создайте макет с типом «Двоичные данные» и латинским именем
3. 3
   Загрузите в макет zip-архив компонента целиком
4. 4
   Сохраните и обновите конфигурацию базы данных
5. 5
   Проверьте, что макет доступен: ПолучитьОбщийМакет("ИмяМакета") возвращает двоичные данные

Альтернатива макету — поместить компоненту в справочник «Внешние компоненты» подсистемы БСП, если конфигурация построена на библиотеке стандартных подсистем. Тогда подключение выполняется штатными функциями БСП, а администратор может обновлять компоненту без конфигуратора, прямо в пользовательском режиме.

Подключите компоненту программно

Основной метод — ПодключитьВнешнююКомпоненту. Для компоненты из макета место хранения указывается в виде пути к макету. Типовой код выглядит так:

Подключено = ПодключитьВнешнююКомпоненту(
"ОбщийМакет.КомпонентаСканер",
"Scanner",
ТипВнешнейКомпоненты.Native);

Если Подключено Тогда
Сканер = Новый("AddIn.Scanner.Scanner");
Иначе
Сообщить("Не удалось подключить компоненту");
КонецЕсли;

Второй параметр — имя подключения, которое затем фигурирует в строке создания объекта AddIn.Scanner. Третий сегмент в имени объекта (здесь Scanner после точки) — это имя класса внутри компоненты, его нужно взять из документации поставщика: ошибка в этом имени даёт сбой именно на строке Новый, а не на подключении.

ПодключитьВнешнююКомпоненту("ОбщийМакет.КомпонентаСканер", "Scanner", ТипВнешнейКомпоненты.Native);
Сканер = Новый("AddIn.Scanner.Scanner");

Для COM-компоненты сначала выполняется регистрация в ОС: regsvr32 "C:\Components\MyComp.dll" с правами администратора. Затем компонента подключается по ProgID: ПодключитьВнешнююКомпоненту("AddIn.MyComp") — либо объект создаётся напрямую через COM-объект, в зависимости от реализации. Учтите разрядность: 32-разрядная dll не зарегистрируется для 64-разрядного процесса сервера 1С.

Учтите место выполнения кода: клиент или сервер

Компонента подключается в том процессе, где выполняется код. Если метод вызывается в серверной процедуре, библиотека загружается в рабочий процесс сервера 1С — значит, в архиве должна быть сборка под ОС и разрядность сервера (например, Linux x64), а для COM — регистрация выполняется на сервере. Если код клиентский, компонента загружается на компьютер пользователя.

Для Native API платформа умеет автоматически устанавливать компоненту на клиенте из макета при первом обращении — для этого предусмотрен метод УстановитьВнешнююКомпоненту и механизм автозагрузки из архива с манифестом. В веб-клиенте компонента работает только при наличии сборки для браузера и установленного расширения для работы с файлами/компонентами.

Проверьте, что компонента подключилась корректно

Минимальная проверка — два контрольных значения: метод ПодключитьВнешнююКомпоненту вернул Истина, и конструктор Новый("AddIn...") создал объект без исключения. Дополнительно вызовите любой безопасный метод компоненты, например получение версии, если такой есть в документации — это подтверждает, что библиотека не только загрузилась, но и работоспособна.

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

Типичные ошибки и их причины

Самая частая проблема — «Компонента не обнаружена» при корректном, казалось бы, пути к макету. Причины: макет создан с типом, отличным от «Двоичные данные»; zip-архив был перепакован и manifest.xml оказался во вложенной папке; в архиве нет сборки под платформу, где выполняется код. Распакуйте архив и проверьте, что манифест лежит в корне.

Вторая группа ошибок — разрядность и права. 64-разрядный сервер 1С не загрузит 32-разрядную COM-dll; для regsvr32 нужны права администратора; антивирус может блокировать загрузку неподписанных библиотек. Третья группа — несовпадение имён: имя подключения во втором параметре метода и имя в строке AddIn.Имя.Класс должны совпадать символ в символ.

Безопасность и обновление компоненты

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

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

FAQ