Как загрузить внешнюю компоненту в 1С

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

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

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

Что такое внешняя компонента и когда она нужна

Внешняя компонента (ВК) реализуется по технологии Native API или как COM-объект. Native API — современный стандарт фирмы «1С»: компонента поставляется в виде ZIP-архива с файлом manifest.xml и бинарными файлами для разных платформ (Windows x86, x64, Linux, иногда Android/iOS для мобильной платформы). COM-компоненты — устаревший подход, работающий только под Windows и требующий регистрации в системе.

Типичные сценарии использования: драйверы торгового оборудования, компоненты сканирования и распознавания, работа с электронной подписью, интеграция с нестандартными API, которых нет во встроенном языке. Если задачу можно решить штатными средствами платформы (HTTP-запросы, XML, JSON), внешняя компонента обычно не нужна — это лишняя зависимость и точка отказа.

Подготовка: откуда брать компоненту и что проверить

Перед загрузкой убедитесь, что у вас корректный дистрибутив. Для Native API это ZIP-архив, внутри которого лежит manifest.xml и файлы вида ИмяКомпоненты.dll (Windows) или libИмяКомпоненты.so (Linux) с суффиксами разрядности. Откройте manifest.xml текстовым редактором и проверьте, для каких платформ есть сборки: если нужен тонкий клиент на Windows x64, а в архиве только x86-файл, подключение не выполнится.

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

Способ 1. Загрузка из макета конфигурации

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

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

Если Не Результат Тогда
ВызватьИсключение "Не удалось подключить внешнюю компоненту";
КонецЕсли;

// Создание объекта компоненты
Компонента = Новый("AddIn.СканерШК.Scanner");

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

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

Способ 2. Загрузка из файла на диске

Если компонента не встроена в конфигурацию, её можно подключить напрямую из файла. Для Native API указывается путь к ZIP-архиву или к DLL/SO, для COM — путь к зарегистрированной библиотеке. Способ удобен для отладки и для компонент, поставляемых отдельным установщиком.

// Файл должен быть доступен на том компьютере, где выполняется код
Результат = ПодключитьВнешнююКомпоненту(
"C:\Components\MyComponent.zip",
"МояКомпонента",
ТипВнешнейКомпоненты.Native);

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

Особенности клиентов: тонкий, толстый, веб и сервер

Разрядность компоненты должна совпадать с разрядностью процесса, который её загружает. 64-разрядный тонкий клиент не загрузит 32-разрядную DLL, и наоборот. Поэтому в ZIP-архиве Native API держат несколько сборок, а платформа при подключении выбирает подходящую по записи в manifest.xml. Если подходящей сборки нет, метод вернёт Ложь без подробного объяснения.

В веб-клиенте внешние компоненты работают через механизм расширения для браузера: пользователю потребуется установить расширение платформы и разрешить подключение компоненты. Часть компонент в веб-клиенте не работает в принципе — это нужно уточнять в документации поставщика. На сервере под Linux подключаются только .so-сборки, COM-технология там недоступна.

Сравнение вариантов

Из макета конфигурации

Подходит для тиражируемых решений: компонента обновляется вместе с конфигурацией. Ограничение — увеличивает размер конфигурации и требует обновления макета при новой версии компоненты.

Из файла на диске

Удобно для отладки и драйверов с собственным установщиком. Ограничение — файл нужно разложить на все рабочие места и следить за версиями вручную.

COM-компонента

Только Windows, требует регистрации через regsvr32 с правами администратора. Оправдано лишь для старых компонент, не имеющих Native API-версии.

Типичные ошибки подключения и их диагностика

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

Частые причины отказа: несовпадение разрядности клиента и сборки, повреждённый или перепакованный ZIP (архив должен сохранять структуру с manifest.xml в корне), блокировка DLL антивирусом или политикой безопасности Windows (файл, скачанный из интернета, может быть помечен как заблокированный — проверьте свойства файла), отсутствие прав на каталог, отсутствие в системе зависимых библиотек, которые использует сама компонента.

Проверка результата и отладка

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

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

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

Возврат ПодключитьВнешнююКомпоненту

Норма

Истина

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

Ложь — проверяйте манифест, разрядность и доступность файла

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

Норма

Объект создан, методы доступны

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

Исключение «Тип не определён» — неверный идентификатор или имя объекта

Тестовый вызов метода

Норма

Метод возвращает ожидаемое значение

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

Ошибка вызова — смотрите журнал регистрации и документацию компоненты

Если компонента подключается нестабильно, включите технологический журнал с событием EXCP и поищите ошибки загрузки библиотеки на уровне ОС. Для COM-компонент проверьте регистрацию через regsvr32 вручную — ошибка регистрации сразу покажет системную причину.

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

Как выбрать сценарий под свою задачу

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

Как выбрать действие

Компонента — часть вашей конфигурации и должна работать у всех пользователейПоместите ZIP в общий макет и подключайте по имени макета

Компонента — драйвер оборудования с собственным установщикомПодключайте из каталога установки на клиенте и проверяйте наличие файла перед подключением

Код выполняется на сервере, а компонента работает с клиентским оборудованиемПеренесите вызов в клиентский общий модуль — на сервере такая компонента бесполезна

Нужен веб-клиентПроверьте поддержку веб-клиента у поставщика и наличие расширения платформы у пользователей

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

Можно ли подключить внешнюю компоненту без изменения конфигурации?

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

Почему ПодключитьВнешнююКомпоненту возвращает Ложь без текста ошибки?

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

Как подключить компоненту в тонком клиенте без модальных окон?

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

Нужно ли подключать компоненту заново в каждом сеансе?

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

Чем Native API лучше COM-компоненты?

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