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

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

Способ подключения зависит от типа компоненты. Современные компоненты для управляемого приложения и веб-клиента собираются по технологии Native API и поставляются в виде ZIP-архива, который добавляется в макет конфигурации. Старые COM-компоненты требуют регистрации в операционной системе через regsvr32. Смешение этих подходов — самая частая причина ошибок.

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

Какие бывают типы внешних компонент и какой выбрать

Платформа 1С поддерживает два принципиально разных типа внешних компонент. Первый — Native API: библиотека, собранная по стандарту 1С, поставляется в ZIP-архиве, где лежат версии под разные платформы (Windows x86, x64, иногда Linux и Android). Такие компоненты работают в тонком и веб-клиенте, не требуют прав администратора для установки и являются рекомендуемым форматом для новых разработок.

Второй тип — COM-компоненты: обычные DLL, зарегистрированные в реестре Windows. Они работают только в толстом и тонком клиенте под Windows, требуют регистрации на каждом рабочем месте и не поддерживаются веб-клиентом. К этому типу относится большинство старых драйверов торгового оборудования и компонент, написанных до появления Native API.

Перед подключением определите тип компоненты по упаковке: если у вас ZIP-архив с манифестом manifest.xml внутри — это Native API. Если отдельный файл DLL с инструкцией «зарегистрируйте через regsvr32» — это COM. От этого зависит весь дальнейший порядок действий.

Добавление Native API компоненты в макет конфигурации

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

Важно загружать именно исходный ZIP-архив целиком, а не распакованные DLL. Платформа сама извлекает из архива нужную версию библиотеки под текущую разрядность клиента и операционную систему. Если загрузить в макет отдельную DLL, подключение завершится ошибкой «Некорректный формат архива» или подобной.

Обратитесь к документации компоненты за точным именем и идентификатором: они понадобятся при вызове методов подключения. Обычно идентификатор указан в манифесте архива или в примерах поставщика и выглядит как «AddIn.ИмяКомпоненты».

Программное подключение: установка и вызов методов

Подключение Native API компоненты в клиентском коде выполняется в два этапа: сначала установка на рабочее место, затем подключение. Установка выполняется один раз (платформа кэширует компоненту), но на практике её часто вызывают при каждом подключении — это безопасно.

НачатьУстановкуВнешнейКомпоненты(, "ОбщийМакет.КомпонентаСканера");

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

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

Метод ПодключитьВнешнююКомпоненту принимает три ключевых параметра: место хранения (для макета — строка вида «ОбщийМакет.ИмяМакета»), имя подключения (любое короткое имя латиницей, используется в конструкторе объекта) и тип компоненты — Native или COM. После успешного подключения объект создаётся через конструктор Новый с именем вида «AddIn.ИмяПодключения.ИмяОбъекта».

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

1. 1
   Добавьте ZIP-архив компоненты в общий макет с типом «Двоичные данные»
2. 2
   В клиентском коде вызовите установку компоненты из макета
3. 3
   Вызовите ПодключитьВнешнююКомпоненту с типом Native и проверьте возвращаемое значение
4. 4
   Создайте объект через Новый("AddIn.ИмяПодключения.ИмяОбъекта")
5. 5
   Вызовите тестовый метод компоненты и убедитесь в корректном ответе

Подключение COM-компоненты через регистрацию в Windows

COM-компонента перед использованием регистрируется в операционной системе. Скопируйте DLL на рабочее место (лучше в отдельный каталог, а не в системные папки) и выполните регистрацию из командной строки, запущенной от имени администратора.

regsvr32 "C:\Components\MyComponent.dll"

Критичный момент — разрядность. 32-битная DLL регистрируется 32-битной версией regsvr32 (из каталога SysWOW64 на 64-битной Windows), 64-битная — соответственно своей. Разрядность компоненты должна совпадать с разрядностью клиентского приложения 1С: если у пользователя 32-битный тонкий клиент, а компонента 64-битная, подключение завершится ошибкой.

После регистрации компонента подключается по её программному идентификатору ProgID, который указан в документации поставщика:

Подключено = ПодключитьВнешнююКомпоненту("AddIn.MyComponent", , ТипВнешнейКомпоненты.COM);

// Либо напрямую через COM-объект
Попытка
    Компонента = Новый COMОбъект("MyCompany.MyComponent");
Исключение
    Сообщить("Компонента не зарегистрирована: " + ОписаниеОшибки());
КонецПопытки;

Учтите, что регистрацию нужно выполнять на каждом рабочем месте, где используется компонента. В терминальных средах достаточно регистрации на сервере терминалов, но при обновлении DLL старую версию следует сначала отменить (regsvr32 /u), затем зарегистрировать новую.

Подключение на сервере 1С и в файловой базе

Если компонента вызывается в серверном коде (фоновые задания, серверные процедуры), она должна быть установлена на сервере 1С:Предприятия, а не на клиентских машинах. Для Native API компоненты сервер выполняет установку из макета самостоятельно при первом вызове НачатьУстановкуВнешнейКомпоненты в серверном контексте.

Для COM-компонент на сервере действует то же правило разрядности: DLL регистрируется через regsvr32 на самом сервере 1С, и её разрядность должна совпадать с разрядностью рабочего процесса сервера. Частая ситуация: на клиенте компонента работает, а в серверной процедуре падает с ошибкой — причина именно в том, что на сервере она не зарегистрирована.

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

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

Ошибка «Не удалось подключить внешнюю компоненту» без деталей чаще всего означает несовпадение разрядности, отсутствие регистрации (для COM) или повреждённый архив (для Native). Начинайте диагностику с проверки возвращаемого значения ПодключитьВнешнююКомпоненту и журнала регистрации — туда платформа пишет расширенную информацию об ошибке.

Если компонента подключается, но объект не создаётся (ошибка в конструкторе Новый), проверьте правильность имени: оно строится как «AddIn.ИмяПодключения.ИмяОбъекта», где ИмяПодключения — второй параметр подключения, а ИмяОбъекта берётся из документации компоненты. Опечатка в любом из сегментов даёт ошибку «Недопустимое значение» или «Объект не найден».

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