Разработка и Конфигурация · 12 мин
Внешняя компонента в 1С: что это и как её подключить
Внешняя компонента в 1С: назначение, технология Native API и COM, порядок подключения в конфигураторе, типичные ошибки и способы проверки работоспособности.
Внешняя компонента в 1С — это отдельный программный модуль (обычно библиотека DLL), который расширяет возможности платформы функциями, недоступными во встроенном языке. Через внешние компоненты 1С подключается к торговому оборудованию, сканерам штрихкодов, криптографическим средствам, аппаратным ключам и другим системам, где требуется низкоуровневый доступ к железу или операционной системе.
Классический пример — драйвер ККТ или сканера штрихкодов: платформа сама по себе не умеет обращаться к COM-порту устройства, поэтому производитель оборудования поставляет компоненту, а разработчик 1С вызывает её методы из встроенного языка. Без компоненты интеграция с таким оборудованием невозможна в принципе.
Компонента поставляется в виде файла (или архива с файлами под разные платформы), подключается в конфигураторе или программно, после чего её объекты становятся доступны в коде как обычные объекты 1С с методами и свойствами. Дальше разберём, какие технологии применяются, как подключить компоненту и что проверить, если она не загружается.
Зачем нужны внешние компоненты и где они применяются
Встроенный язык 1С намеренно изолирован от операционной системы: из него нельзя напрямую обратиться к драйверу устройства, вызвать произвольную функцию Windows API или выполнить низкоуровневую операцию. Это сделано ради безопасности и кроссплатформенности, но создаёт разрыв там, где нужен доступ к железу или системным библиотекам. Внешние компоненты закрывают именно этот разрыв.
Типовые сценарии использования:
- подключение торгового оборудования — сканеров штрихкодов, фискальных регистраторов, терминалов сбора данных, весов;
- криптография и электронная подпись — работа с сертификатами, подписание документов через средства СКЗИ;
- обмен со специализированным ПО — платёжные терминалы, банковские клиенты, системы маркировки;
- ускорение вычислений — вынос тяжёлых алгоритмов в компилируемый код;
- доступ к функциям ОС, недоступным из встроенного языка.
В типовых конфигурациях компоненты уже встроены: например, в «1С:Рознице» и «Управлении торговлей» драйверы оборудования поставляются в составе конфигурации в виде макетов и подключаются автоматически при настройке рабочего места. Самостоятельная разработка компоненты требуется редко — чаще задача сводится к правильному подключению готовой.
Технологии создания: COM и Native API
Исторически первой технологией был COM: компонента регистрировалась в системе как COM-объект, а 1С обращалась к ней через механизм OLE/COM. Такой подход до сих пор встречается в старых драйверах и решениях, но у него есть ограничения — привязка к Windows, необходимость регистрации в реестре и проблемы с разрядностью.
Современный стандарт — Native API. Это технология фирмы «1С», при которой компонента не требует регистрации в системе, загружается напрямую из файла и может поставляться в виде ZIP-архива с вариантами под разные платформы: Windows 32/64, Linux 32/64, а также для веб-клиента. Платформа сама выбирает нужный файл из архива в зависимости от того, где выполняется код — на клиенте или на сервере.
На практике выбор технологии обычно уже сделан поставщиком: вы получаете готовую компоненту и подключаете её. Если же разрабатываете собственную, для новых решений следует использовать Native API — это единственный вариант, работающий на Linux-серверах и в веб-клиенте.
Сравнение технологий
Современный стандарт: не требует регистрации, работает на Windows и Linux, поддерживает веб-клиент, поставляется ZIP-архивом. Рекомендуется для всех новых решений.
Устаревший подход: только Windows, требуется регистрация в реестре, чувствителен к разрядности клиента. Оправдан только для поддержки старых драйверов.
Как устроена компонента Native API
Компонента Native API распространяется в виде ZIP-архива со строго определённой структурой. Внутри находится файл манифеста (manifest.xml), в котором перечислены файлы библиотек и указано, для какой платформы каждый предназначен. Платформа читает манифест и загружает подходящий вариант.
Ключевой элемент компоненты — программный идентификатор вида AddIn.ИмяКомпоненты.ИмяОбъекта (например, AddIn.Scanner.BarcodeScanner). Именно по этому идентификатору объект создаётся в коде после подключения. Идентификатор задаётся разработчиком компоненты и указывается в её документации.
Компонента может предоставлять один или несколько объектов, у каждого — свой набор методов, свойств и событий. События позволяют компоненте уведомлять 1С, например, о считывании штрихкода: платформа получает внешнее событие, которое обрабатывается в модуле формы.
Как подключить внешнюю компоненту в конфигураторе
Стандартный способ встраивания компоненты в конфигурацию — поместить её ZIP-архив в макет. Для этого в конфигураторе создаётся общий макет типа «Двоичные данные», в который загружается ZIP-файл компоненты. Дальше подключение выполняется программно.
Типовая последовательность вызовов выглядит так:
// Подключение компоненты из макета
Результат = ПодключитьВнешнююКомпоненту(
"ОбщийМакет.ДрайверСканера",
"Сканер",
ТипВнешнейКомпоненты.Native);
Если Результат Тогда
// Создание объекта компоненты
Сканер = Новый("AddIn.Сканер.BarcodeScanner");
// Вызов методов
Сканер.ОткрытьПорт(3);
Иначе
Сообщить("Не удалось подключить компоненту");
КонецЕсли;
Первый параметр — путь к макету или к файлу на диске, второй — произвольное имя подключения, которое затем используется в идентификаторе объекта. Метод возвращает Истина при успехе; при неудаче текст ошибки можно получить через ИнформацияОбОшибке() или журнал регистрации.
- 1Получите ZIP-архив компоненты от поставщика и проверьте наличие manifest.xml внутри
- 2Создайте в конфигураторе общий макет с типом «Двоичные данные» и загрузите в него архив
- 3Вызовите ПодключитьВнешнююКомпоненту с указанием макета и типа Native
- 4Создайте объект через Новый с программным идентификатором из документации компоненты
- 5Вызовите тестовый метод (например, получение версии драйвера) и убедитесь, что возвращается осмысленное значение
Подключение из файла и на сервере
Компоненту можно подключить не только из макета, но и напрямую из файла на диске — это удобно на этапе отладки. В первом параметре указывается полный путь к ZIP-архиву или DLL. Важно помнить: если код выполняется на сервере, путь должен быть доступен именно с сервера, а не с клиентской машины разработчика.
Отдельный нюанс — место выполнения. Если компонента работает с оборудованием, подключённым к компьютеру пользователя (сканер, ККТ), подключать её нужно на клиенте. Если компонента выполняет серверные вычисления или обращается к ресурсам сервера — на сервере. В тонком и веб-клиенте действуют дополнительные ограничения: в веб-клиенте компонента требует установки расширения работы с файлами и отдельной установки в браузер.
Типичные ошибки при подключении и их диагностика
Самая частая проблема — метод ПодключитьВнешнююКомпоненту возвращает Ложь без внятного сообщения. Причины обычно такие: повреждённый или неправильно собранный ZIP-архив, отсутствие в архиве варианта под нужную платформу (например, есть только 32-битная DLL, а сервер 64-битный), либо нарушенная структура манифеста.
Вторая группа ошибок связана с созданием объекта: компонента подключилась, но конструкция Новый("AddIn...") вызывает исключение. Это почти всегда означает неверный программный идентификатор — сверьте его с документацией посимвольно, включая имя подключения, указанное во втором параметре.
Третья группа — ошибки уже при вызове методов: оборудование не отвечает, порт занят другой программой, драйвер ОС не установлен. Здесь компонента работает корректно, а проблема находится на уровне железа или операционной системы. Проверяйте устройство штатными утилитами производителя до обращения к коду 1С.
Как проверить, что компонента работает
После подключения полезно выполнить минимальную проверку до начала реальной работы. У большинства компонентов есть метод получения версии или теста устройства — вызовите его и убедитесь, что возвращается осмысленное значение, а не исключение. Для оборудования дополнительно выполните тестовую операцию: считайте штрихкод, напечатайте пробный чек на тестовом устройстве.
При нестабильной работе смотрите журнал регистрации: туда попадают ошибки загрузки компоненты. На сервере дополнительно проверьте, что учётная запись, под которой работает агент сервера 1С, имеет доступ к файлам компоненты и к устройствам, если они серверные.
Как проверить результат
Метод возвращает Истина
Возвращает Ложь — проверяйте архив, манифест и разрядность
Новый("AddIn...") выполняется без исключения
Исключение — неверный идентификатор или имя подключения
Возвращается строка версии драйвера
Исключение или пустое значение — компонента загружена с ошибкой
Оборудование отвечает на тестовую команду
Таймаут или ошибка порта — проблема в железе или драйвере ОС
Ограничения и альтернативы
Внешние компоненты — не единственный способ интеграции. Если система или устройство имеет HTTP- или веб-сервисный интерфейс, предпочтительнее использовать HTTPСоединение или WS-ссылки: такое решение не требует установки файлов на каждое рабочее место и проще в сопровождении. Компонента оправдана там, где нужен прямой доступ к железу или высокая скорость обмена.
Учитывайте и ограничения: компоненту нужно обновлять при смене версии платформы, если поставщик выпускает новые сборки; в веб-клиенте пользователю придётся установить компоненту в браузер; в файловых базах с множеством рабочих мест развёртывание усложняется. Перед выбором архитектуры оцените эти издержки.
Как выбрать подход
Что важно запомнить
Внешняя компонента — это подключаемая библиотека, расширяющая 1С доступом к оборудованию и системным функциям. Современный стандарт — Native API с поставкой в ZIP-архиве. Подключение выполняется через макет с двоичными данными и метод ПодключитьВнешнююКомпоненту, объект создаётся по программному идентификатору. Главные причины сбоев — несовпадение разрядности, ошибки в идентификаторе и неверное место выполнения кода.
Частые вопросы о внешних компонентах 1С
Чем внешняя компонента отличается от внешней обработки?
Внешняя обработка — это файл .epf с кодом на встроенном языке 1С, который платформа выполняет как часть конфигурации. Внешняя компонента — это скомпилированная библиотека (DLL), написанная обычно на C++, которая добавляет в язык новые объекты. Обработка ограничена возможностями встроенного языка, компонента — нет.
Можно ли написать внешнюю компоненту самостоятельно?
Да. Фирма «1С» публикует документацию по технологии Native API и примеры шаблонов проектов на C++. Потребуются навыки разработки на C++ и сборки библиотек под нужные платформы. Для разовой задачи чаще выгоднее найти готовую компоненту или пересмотреть архитектуру в пользу HTTP-интеграции.
Почему компонента работает на клиенте, но не работает на сервере?
Чаще всего дело в разрядности (сервер 64-битный, а в архиве только 32-битная сборка), в отсутствии Linux-варианта для сервера на Linux или в правах учётной записи агента сервера. Также проверьте, что устройство, к которому обращается компонента, физически доступно с сервера.
Нужно ли регистрировать компоненту Native API в системе?
Нет. В этом главное отличие от COM: компонента Native API загружается платформой напрямую из ZIP-архива или файла, регистрация в реестре не требуется. Это упрощает развёртывание и позволяет хранить компоненту прямо в конфигурации.
Безопасно ли подключать сторонние компоненты?
Компонента выполняется с правами процесса 1С и теоретически имеет доступ к данным и файлам. Подключайте только компоненты от производителя оборудования или проверенных разработчиков, при возможности проверяйте цифровую подпись файлов и не используйте компоненты из неофициальных источников.
Как обновить компоненту, встроенную в конфигурацию?
Замените содержимое общего макета с двоичными данными на новый ZIP-архив от поставщика и обновите конфигурацию базы данных. Код подключения менять не нужно, если программный идентификатор и состав методов не изменились — это стоит проверить в описании новой версии драйвера.