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

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

Путь зависит от технологии. Native API ставится средствами самой платформы, без прав администратора. COM-компонента регистрируется в Windows и требует прав. Дальше — как отличить одно от другого и что сделать, чтобы всё заработало с первого раза.

Из чего состоит внешняя компонента

ВК распространяется в одном из двух видов:

• 📦 ZIP-архив с файлом MANIFEST.XML и одной или несколькими библиотеками под разные системы. Это формат Native API.
• 🔧 Отдельная DLL или EXE, которую нужно регистрировать в системе. Так устроены COM-компоненты.

В архиве Native API манифест описывает, какая библиотека для какой ОС и какой разрядности. Платформа сама выбирает подходящую. Пример манифеста:

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

Один архив обслуживает и 32-, и 64-разрядный клиент, и Windows с Linux. COM-компонента так не умеет: под каждую разрядность нужна своя регистрация.

Какие бывают внешние компоненты

Для чего их используют на практике:

• 🖨 фискальные регистраторы, сканеры штрихкодов, весы, эквайринг;
• 🔐 криптография и электронная подпись;
• 📄 разбор PDF, сжатие, нестандартные форматы обмена;
• 🌐 сетевые протоколы, которых нет в платформе;
• ⚡ тяжёлые вычисления, где встроенный язык слишком медленный.

Чем внешняя компонента отличается от внешней обработки

Путают их постоянно, хотя это разные вещи.

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

От расширений конфигурации (.cfe) ВК тоже отличается: расширение меняет логику конфигурации, а компонента добавляет новые возможности платформе.

Где хранить компоненту

Есть три распространённых варианта.

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

Не кладите ВК в общую папку «для всех» без контроля версий. Через месяц у половины пользователей окажется старая библиотека, а у половины новая, и баг будет «плавающим».

Подключение внешней компоненты из кода

Базовый вариант для компоненты, лежащей в общем макете:

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

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

Три параметра: место хранения, любое уникальное имя (символьный идентификатор) и тип технологии. Имя классу AddIn.<идентификатор>.<имя класса> задаёт сам разработчик компоненты, оно указано в её документации.

Если компонента ещё не установлена на компьютере, сначала вызывают установку. В актуальных платформах вместо синхронных вызовов принято использовать асинхронные: НачатьУстановкуВнешнейКомпоненты и ПодключитьВнешнююКомпонентуАсинх. Они не «замораживают» окно и корректно работают в веб-клиенте.

Установка внешней компоненты по шагам

Native API (ZIP-архив)

1. Получите архив у разработчика оборудования или программы. Проверьте, что в нём есть MANIFEST.XML.
2. Загрузите архив в базу: в общий макет конфигуратором или в справочник компонент через интерфейс.
3. Запустите функцию, которая вызывает ПодключитьВнешнююКомпоненту. Платформа спросит подтверждение при первой установке.
4. Нажмите «Установить». Платформа распакует библиотеку в профиль пользователя, обычно это каталог внутри %APPDATA%\1C\1cv8\ExtCompT.
5. Повторите проверку: теперь подключение проходит без вопросов.

Устанавливается компонента на каждом рабочем месте отдельно. Если в базе работают 30 человек с кассами, диалог увидят все 30, один раз каждый.

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

1. Скопируйте DLL в постоянную папку, например C:\Program Files\Vendor\Scanner\. Не оставляйте её в «Загрузках».
2. Откройте командную строку от имени администратора.
3. Зарегистрируйте библиотеку:

regsvr32 "C:\Program Files\Vendor\Scanner\Scanner.dll"

4. Дождитесь сообщения об успешной регистрации.
5. Для 32-разрядной DLL на 64-разрядной Windows используйте regsvr32 из каталога C:\Windows\SysWOW64. Обычный regsvr32 из System32 ставит только 64-разрядные библиотеки.

Подключение из кода — через Новый COMОбъект("Scanner.Application"). Либо, если компонента подключается как внешняя, через ПодключитьВнешнююКомпоненту с типом COM.

Безопасность: чему верить, а чему нет

Компонента исполняет произвольный машинный код. Один недобросовестный файл способен прочитать документы пользователя, поэтому подход такой:

• ✅ берите ВК только у производителя оборудования или проверенного разработчика;
• ✅ сверяйте контрольную сумму файла, если поставщик её публикует;
• ✅ проверяйте цифровую подпись DLL в свойствах файла (вкладка «Цифровые подписи»);
• ❌ не ставьте компоненты из чатов, с файлообменников и «подправленные» версии.

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

Компонента не хранится «в базе безопасно». Она запускается в процессе клиента (или сервера, если её вызывают серверным кодом) и работает с правами этого процесса. Потому серверное подключение допустимо лишь для проверенных библиотек.

Типичные ошибки при подключении

Сообщения платформы бывают разными, но причин немного.

Кроме перечисленного, полезно проверить три вещи:

1. 📁 Права на каталог. Если профиль пользователя перенаправлен или закрыт групповой политикой, платформа не распакует файл.
2. 🛡 Антивирус. Он часто срабатывает на неизвестные DLL. Добавьте каталог компонент в исключения.
3. 🔄 Кеш. Если вы заменили ВК на новую версию, а платформа берёт старую, закройте все клиенты и удалите содержимое каталога ExtCompT для этой компоненты. Остальные кеши платформы чистить не нужно.

Обновление и версии

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

• меняйте идентификатор подключения при несовместимых изменениях, например Scanner2;
• храните номер версии компоненты рядом с файлом (в названии макета или реквизите справочника);
• после обновления проверяйте работу на одном рабочем месте, а потом раскатывайте на остальные.

Как добавить компоненту в общий макет

Если вы администратор или разработчик конфигурации, порядок такой:

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

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

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

Если вы сами заказываете или пишете компоненту, ориентируйтесь на задачу:

• 🌐 нужен веб-клиент или Linux — только Native API;
• 🖥 всё работает на одном Windows-сервере терминалов, а оборудование поставляет COM-драйвер — оставьте COM, не переписывайте без нужды;
• 🔁 нужна работа без блокировки интерфейса — выбирайте асинхронные методы подключения;
• 🧪 нужна быстрая проверка идеи — сначала сделайте прототип на языке 1С и только потом уходите в нативный код.

Как узнать, что компонента подключена

Простая проверка в консоли кода или в отладчике: после вызова ПодключитьВнешнююКомпоненту возвращается Истина, а Новый("AddIn.…") не падает с исключением. Если возвращается Ложь, причину платформа сама не пишет, поэтому обрабатывайте это в коде и сообщайте пользователю понятный текст.

Полезный приём при отладке: оберните вызов в Попытка … Исключение, а в тексте исключения выводите ОписаниеОшибки(). Там обычно видно, что не так: «файл не найден», «неверный формат», «компонента несовместима с платформой».

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