Внешние компоненты 1С: что это и как с ними работать

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

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

Физически внешняя компонента — это файл DLL (Windows), SO (Linux) или готовая сборка под нужную платформу, упакованная по правилам технологии создания внешних компонент. Платформа загружает библиотеку в процесс клиента или сервера, находит в ней точку входа и создаёт объект, доступный из кода 1С.

Зачем нужны внешние компоненты и какие задачи они решают

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

Типовые области применения:

• Торговое оборудование — сканеры штрихкодов, фискальные регистраторы, весы, терминалы сбора данных, дисплеи покупателя. Драйверы оборудования в типовых конфигурациях реализованы именно как внешние компоненты.
• Криптография и ЭЦП — подписание документов, работа с аппаратными токенами, интеграция с криптопровайдерами.
• Интеграция на уровне ОС — чтение специфических портов, работа с системным реестром, вызовы WinAPI, взаимодействие с другими приложениями.
• Высокопроизводительные вычисления — обработка изображений, распознавание, сложная математика, где интерпретатор 1С слишком медленный.

Важно понимать границу: если задачу можно решить средствами встроенного языка, HTTP-сервисами или COM-соединением, внешняя компонента обычно не нужна. Она оправдана там, где требуется нативный код и прямой доступ к ресурсам системы.

Три технологии создания внешних компонент

Платформа 1С поддерживает несколько технологий, и от выбора зависит, как компонента упаковывается, регистрируется и на каких клиентах работает.

Native API

Современная и рекомендуемая технология. Компонента пишется на C++ по спецификации Native API, компилируется под нужные платформы (Windows, Linux, разные разрядности) и упаковывается в ZIP-архив вместе с файлом манифеста MANIFEST.XML, где перечислены сборки под каждую платформу. Ключевое преимущество — работа без регистрации в системе, в том числе в веб-клиенте (через механизм расширения работы с файлами и подключения ВК) и на сервере.

COM (AddIn по технологии COM)

Исторически первая технология: компонента — это COM-объект, который регистрируется в Windows через regsvr32 и реализует интерфейс IInitDone. Работает только на Windows и только там, где выполнена регистрация с правами, достаточными для записи в реестр. Для новых разработок COM-вариант применяют редко, но он встречается в старых драйверах оборудования.

Внешние компоненты мобильной платформы

Отдельный случай — компоненты для мобильной платформы 1С, которые собираются под Android и iOS и поставляются вместе с мобильным приложением. Принцип тот же: нативный код, вызываемый из встроенного языка.

Сравнение технологий

Native API

Кроссплатформенность, работа в веб-клиенте и на сервере, поставка в ZIP без регистрации. Требует разработки на C++ и сборки под каждую платформу.

COM (AddIn)

Проще в разработке на старте, но только Windows, нужна регистрация regsvr32, не работает в веб-клиенте и на Linux-сервере.

Мобильная ВК

Единственный вариант для мобильного приложения 1С; собирается под конкретную ОС и поставляется с приложением.

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

Подключение выполняется методом глобального контекста ПодключитьВнешнююКомпоненту() (в асинхронном режиме — НачатьПодключениеВнешнейКомпоненты()). Метод принимает местонахождение компоненты, её имя и, при необходимости, тип.

Типовой фрагмент кода:

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

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

Здесь первый параметр — путь к компоненте. Это может быть общий макет конфигурации с ZIP-архивом, файл на диске или место в справочнике дополнительных отчетов и обработок. Второй параметр — программное имя, под которым компонента регистрируется в сеансе. Третий — тип технологии.

После успешного подключения объект создаётся конструктором Новый("AddIn.ИмяКомпоненты.ИмяОбъекта"). Дальше работа с ним не отличается от работы с обычным объектом 1С: вызовы методов, чтение и запись свойств, подписка на внешние события.

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

Где выполняется компонента: клиент, сервер, веб-клиент

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

Из этого следуют практические выводы. Сканер штрихкодов подключён к рабочему месту кассира, поэтому драйвер сканера подключают на клиенте. А компоненту генерации отчёта в фоновом задании подключают на сервере — и она обязана иметь сборку под ОС и разрядность сервера 1С, иначе подключение завершится ошибкой.

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

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

Большинство проблем с внешними компонентами сводится к нескольким повторяющимся сценариям.

«Не удалось подключить внешнюю компоненту» без деталей. Чаще всего причина — отсутствие сборки под текущую платформу. Например, в ZIP есть DLL только для Windows x86, а подключение выполняется на 64-разрядном сервере Linux. Проверьте MANIFEST.XML внутри архива: там должны быть перечислены все нужные комбинации ОС и разрядности.

Компонента подключается, но объект не создаётся. Ошибка в имени: строка в Новый("AddIn.Имя.Объект") должна точно совпадать с именем, заданным в коде самой компоненты, включая регистр. Также проверьте, что второй параметр подключения совпадает с префиксом в конструкторе.

COM-компонента не регистрируется. Регистрация через regsvr32 требует прав администратора и соответствия разрядности: 32-разрядную DLL на 64-разрядной Windows регистрируют через C:\Windows\SysWOW64\regsvr32.exe.

Работает на клиенте, не работает на сервере. На сервере свои требования: сборка под серверную ОС, отсутствие обращений к GUI (серверный процесс не имеет рабочего стола), достаточные права учётной записи агента сервера 1С.

Как проверить, что компонента работает правильно

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

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

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

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

Возвращаемое значение подключения

Норма

Метод вернул Истина, объект создан

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

Ложь или исключение при Новый("AddIn...") — нет сборки под платформу или неверное имя

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

Норма

Метод возвращает ожидаемое значение (версия, статус устройства)

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

Ошибка вызова — компонента загружена, но не может обратиться к устройству или ресурсу

Поведение на целевом окружении

Норма

Работает на том же типе клиента и ОС, что и у пользователей

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

Работает только у разработчика — проблема разрядности, прав или регистрации

Альтернативы внешним компонентам

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

• HTTP- и веб-сервисы — интеграция с внешними системами через REST/SOAP вместо компоненты-обёртки.
• COM-соединение и OLE — простой вызов COM-объектов Windows без создания полноценной ВК.
• Запуск внешних приложений — обмен через файлы или командную строку, если интерактивность не нужна.
• Драйверы оборудования из состава БПО — библиотека подключаемого оборудования уже содержит готовые компоненты для большинства классов устройств.

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

Частые вопросы о внешних компонентах 1С

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

Внешняя обработка — это файл .epf с кодом на встроенном языке 1С, она работает только средствами платформы. Внешняя компонента — нативная библиотека на C++ или другом языке, которая даёт доступ к оборудованию и системным функциям, недоступным из встроенного языка.

Можно ли использовать внешнюю компоненту в веб-клиенте?

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

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

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

Где взять внешнюю компоненту для сканера штрихкодов или кассы?

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

Безопасно ли подключать сторонние внешние компоненты?

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

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

Проверьте по порядку: есть ли в архиве сборка под текущую ОС и разрядность (MANIFEST.XML), корректен ли путь к компоненте, достаточно ли прав у пользователя или учётной записи сервера. Для COM-компонент дополнительно убедитесь, что выполнена регистрация через regsvr32 нужной разрядности.