Внешние компоненты 1С:Предприятия 8.3 — как платформа работает с DLL и SO
Содержание
Внешняя компонента в 1С — это библиотека (.dll в Windows, .so в Linux, .dylib в macOS), которую платформа 1С:Предприятие 8.3 загружает в свой процесс и дальше работает с ней как с обычным объектом встроенного языка. Через неё 1С получает то, чего нет в платформе: драйвер кассы или весов, разбор редкого формата файла, быстрый расчёт, обращение к системным функциям ОС.
Компонента пишется на C++ (реже на других языках), упаковывается в ZIP-архив с манифестом, кладётся в общий макет конфигурации и подключается двумя-тремя строками кода.
Как платформа 1С взаимодействует с внешней компонентой
Схема простая. Платформа загружает библиотеку, спрашивает у неё список классов и создаёт объект нужного класса. После этого в коде доступен объект с типом вида AddIn.Имя.ИмяКласса. Свойства и методы компоненты вызываются через точку, как у любого объекта 1С.
Что происходит при подключении:
- 📦 Платформа берёт архив компоненты (из макета, файла или справочника) и читает манифест.
- 🖥️ По манифесту выбирает файл под текущую ОС и разрядность: Windows x86, Windows x86-64, Linux, macOS, мобильные платформы.
- 🔗 Загружает библиотеку и вызывает её экспортируемые функции: получение имён классов, создание объекта, уничтожение объекта.
- 🧩 Регистрирует классы под символическим именем, которое вы передали при подключении.
- ✅ Код создаёт объект через
Новый("AddIn.Имя.ИмяКласса").
Компонента живёт в процессе того, кто её загрузил. На клиенте это 1cv8c.exe или 1cv8.exe, на сервере — рабочий процесс rphost. Отсюда два следствия: разрядность библиотеки должна совпадать с разрядностью процесса, а падение компоненты роняет весь процесс вместе с сеансами.
Обратная связь тоже есть. Компонента может отправить в 1С внешнее событие — например, «отсканирован штрихкод». В модуле формы его ловит процедура ВнешнееСобытие(Источник, Событие, Данные).
Состав архива и манифест
Архив компоненты — обычный ZIP. Внутри библиотеки под разные платформы и файл MANIFEST.XML. Пример манифеста:
<?xml version="1.0" encoding="UTF-8"?>
<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle">
<component os="Windows" path="AddInWin32.dll" type="native" arch="i386"/>
<component os="Windows" path="AddInWin64.dll" type="native" arch="x86_64"/>
<component os="Linux" path="libAddInLin64.so" type="native" arch="x86_64"/>
</bundle>
Если строки для нужной ОС или разрядности в манифесте нет, компонента на этом компьютере просто не подключится. Это первая проверка при любой ошибке загрузки.
Виды внешних компонент и где их применяют
В 8.3 живут две технологии. Третья, совсем старая, встречается только в базах, перенесённых с 7.7.
| Технология | ОС | Как устанавливается | Где работает | Когда выбирать |
|---|---|---|---|---|
| Native API | Windows, Linux, macOS, Android, iOS | из макета, без прав администратора | тонкий, толстый, веб-клиент, сервер, мобильное приложение | любая новая разработка |
| COM | только Windows | регистрация в системе через regsvr32 | толстый и тонкий клиент, сервер на Windows | готовая старая библиотека, переписывать дорого |
| Компоненты 7.7 (OLE) | только Windows | регистрация в системе | ограниченно | только поддержка наследия |
Native API — основная технология. Компонента не требует регистрации в реестре, ставится самой платформой и работает на сервере под Linux. COM-компоненту приходится регистрировать на каждом компьютере, и на Linux-сервере она не заработает.
Где внешние компоненты встречаются в типовых конфигурациях и на практике:
- 🧾 Торговое оборудование. Драйверы ККТ, сканеров, весов, терминалов эквайринга, дисплеев покупателя. В типовых решениях с подсистемой подключаемого оборудования драйвер — это и есть внешняя компонента.
- 🔐 Криптография и ЭП. Работа с криптопровайдером и сертификатами в части конфигураций идёт через компоненты.
- 🖨️ Штрихкоды. Генерация картинки штрихкода для печатных форм, распознавание с камеры на мобильных устройствах.
- 📄 Форматы файлов. Чтение и запись того, чего нет в платформе: редкие архивы, нестандартные таблицы, сканы.
- ⚡ Тяжёлые вычисления. Обработка больших массивов, криптографические хэши, сжатие картинок — на C++ это в разы быстрее, чем циклом на встроенном языке.
- 🖥️ Системные функции. Работа с окнами, буфером обмена, USB-устройствами, сетевыми протоколами.
Установка внешней компоненты: клиент, сервер, COM
Порядок зависит от того, где будет работать компонента и по какой технологии она сделана.
Native API в макете конфигурации
Это штатный путь для собственных разработок:
- Откройте Конфигуратор, ветку
Общие → Общие макеты. - Создайте макет и выберите тип «Внешняя компонента».
- Загрузите в него ZIP-архив с манифестом.
- Обновите конфигурацию базы данных.
Дальше компонента подключается по пути вида "ОбщийМакет.ИмяМакета". На сервере платформа распаковывает и загружает её сама, ничего ставить руками не нужно.
На клиенте Native-компоненту сначала надо установить на компьютер пользователя. Это делает метод УстановитьВнешнююКомпоненту или его асинхронный вариант. Пользователь видит окно подтверждения, после этого файлы копируются в профиль. Установка разовая: при следующих запусках компонента уже есть.
Клиентские компоненты кэшируются в профиле пользователя Windows, в папке %APPDATA%\1C\1cv8\ExtCompT. Если подозреваете битую установку, закройте 1С и удалите содержимое этой папки — при следующем подключении компонента поставится заново.
Веб-клиент
В браузере компонента работает только при установленном расширении работы с файлами и компонентами 1С:Предприятия. Синхронные методы подключения в веб-клиенте недоступны, поэтому код должен быть асинхронным. Плюс каждая библиотека должна быть собрана под нужный браузер и ОС — это указывается в манифесте.
Компонента по технологии COM
- Скопируйте DLL на компьютер (клиентский или сервер 1С).
- Запустите командную строку от имени администратора.
- Зарегистрируйте библиотеку:
:: 64-битная DLL для 64-битного клиента или сервера
regsvr32 "C:\AddIns\MyComponent.dll"
:: 32-битная DLL на 64-битной Windows
C:\Windows\SysWOW64\regsvr32.exe "C:\AddIns\MyComponent.dll"
- Перезапустите 1С (на сервере — после окна для пользователей, см. ниже).
Регистрация COM-компоненты на сервере 1С подхватится рабочими процессами только после их перезапуска. Перезапуск службы агента сервера обрывает все сеансы пользователей — делайте это в нерабочее время и заранее предупредите людей.
Подключение внешней компоненты из кода 1С: примеры
Ключевые методы встроенного языка:
| Метод | Что делает | Где доступен |
|---|---|---|
ПодключитьВнешнююКомпоненту(Местоположение, Имя, Тип) | загружает компоненту, возвращает Истина/Ложь | сервер, толстый и тонкий клиент |
УстановитьВнешнююКомпоненту(Местоположение) | ставит компоненту на компьютер клиента | клиент |
ПодключитьВнешнююКомпонентуАсинх(…) | асинхронное подключение, возвращает обещание | клиент, в том числе веб |
УстановитьВнешнююКомпонентуАсинх(…) | асинхронная установка | клиент, в том числе веб |
Асинхронные варианты с Асинх появились в платформе 8.3.18 вместе с конструкцией Ждать. В более старом коде встречаются НачатьПодключениеВнешнейКомпоненты и НачатьУстановкуВнешнейКомпоненты с описанием оповещения — они тоже работают.
Пример 1. Подключение на сервере
&НаСервереБезКонтекста
Функция ПосчитатьНаСервере(Строка)
Подключена = ПодключитьВнешнююКомпоненту("ОбщийМакет.МояКомпонента",
"МояКомпонента", ТипВнешнейКомпоненты.Native);
Если Не Подключена Тогда
ВызватьИсключение "Не удалось подключить внешнюю компоненту МояКомпонента";
КонецЕсли;
Компонента = Новый("AddIn.МояКомпонента.Calculator");
Возврат Компонента.Hash(Строка);
КонецФункции
Здесь Calculator — имя класса внутри библиотеки, Hash — её метод. Имена классов, свойств и методов берите из документации разработчика компоненты.
Пример 2. Установка и подключение на клиенте
&НаКлиенте
Асинх Процедура ПодключитьКомпоненту(Команда)
Местоположение = "ОбщийМакет.МояКомпонента";
Подключена = Ждать ПодключитьВнешнююКомпонентуАсинх(Местоположение,
"МояКомпонента", ТипВнешнейКомпоненты.Native);
Если Не Подключена Тогда
Ждать УстановитьВнешнююКомпонентуАсинх(Местоположение);
Подключена = Ждать ПодключитьВнешнююКомпонентуАсинх(Местоположение,
"МояКомпонента", ТипВнешнейКомпоненты.Native);
КонецЕсли;
Если Подключена Тогда
Сканер = Новый("AddIn.МояКомпонента.Scanner");
Иначе
Сообщить("Компонента не подключена. Обратитесь к администратору.");
КонецЕсли;
КонецПроцедуры
Логика «попробовать подключить → если нет, установить → подключить снова» нужна, чтобы окно установки не всплывало при каждом запуске.
Пример 3. Компонента по технологии COM
Подключена = ПодключитьВнешнююКомпоненту("C:\AddIns\MyComponent.dll");
Если Подключена Тогда
Объект = Новый("AddIn.MyProgID");
КонецЕсли;
Для COM вместо имени класса в Новый указывают ProgID, под которым компонента зарегистрирована в Windows.
Приём со ссылкой на компоненту в переменной модуля
Создавать объект компоненты при каждом вызове дорого. На клиенте объект обычно держат в переменной модуля формы или в общем клиентском модуле с повторным использованием. Так драйвер весов или сканера инициализируется один раз за сеанс.
Почему внешняя компонента не подключается: ошибки и журнал регистрации
Сообщения, с которыми приходят чаще всего:
Тип не определен (AddIn.МояКомпонента.Calculator)— объект создают до успешного подключения или в другом контексте. Подключение на клиенте не действует на сервере и наоборот.Ошибка при вызове конструктора (AddIn...)— неверное имя класса или компонента не загрузилась.Не удалось загрузить внешнюю компоненту/Ошибка загрузки внешней компоненты— проблема с самим файлом: разрядность, зависимости, манифест, антивирус.
Как писать ошибки в журнал регистрации
Сама платформа в журнал о неудачном подключении пишет не всегда. Добавьте свою запись — потом в журнале будет видно, у кого, когда и с каким текстом не подключилась компонента:
Попытка
Подключена = ПодключитьВнешнююКомпоненту("ОбщийМакет.МояКомпонента",
"МояКомпонента", ТипВнешнейКомпоненты.Native);
Исключение
Подключена = Ложь;
ЗаписьЖурналаРегистрации("ВнешниеКомпоненты.Подключение",
УровеньЖурналаРегистрации.Ошибка, , ,
ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()));
КонецПопытки;
Журнал открывается в пользовательском режиме через Администрирование → Обслуживание → Журнал регистрации (БП 3.0, ЗУП 3.1, УТ 11). Отфильтруйте по событию ВнешниеКомпоненты.Подключение и уровню «Ошибка».
Если компонента роняет рабочий процесс сервера, в журнале может не остаться ничего. Тогда смотрите технологический журнал сервера и дампы rphost: падение внутри DLL обычно видно именно там.
Безопасность и ограничения внешних компонент
Компонента — это чужой машинный код внутри процесса 1С. Она выполняется с правами пользователя Windows, под которым запущен клиент, или с правами учётной записи службы сервера. Может читать файлы, ходить в сеть, обращаться к памяти процесса.
Подключайте только компоненты из надёжного источника: от разработчика конфигурации, производителя оборудования или собственной команды.
Что ограничивает компоненты в 8.3:
- 🛡️ Подтверждение установки. На клиенте пользователь видит запрос перед установкой Native-компоненты и может отказаться.
- 🧱 Профили безопасности кластера. Администратор сервера может включить профиль безопасности для базы и в нём перечислить разрешённые внешние компоненты. Остальные на сервере не подключатся.
- 🔒 Безопасный режим. Код внешних обработок и расширений, работающих в безопасном режиме, не может свободно подключать компоненты.
- 🧪 Изолированный запуск. В актуальных версиях платформы метод подключения принимает параметр изоляции: компонента запускается в отдельном процессе. Её сбой не роняет клиент или рабочий процесс, но вызовы становятся медленнее.
Ограничения самой технологии:
- 🔁 Разрядность библиотеки должна совпадать с разрядностью процесса — 32-битная DLL в 64-битный процесс не загрузится.
- 🌐 Компонента, подключённая на клиенте, недоступна на сервере, и наоборот. Подключать нужно там, где выполняется код.
- 📱 На iOS компоненты работают только в собранном мобильном приложении, не в мобильной платформе для разработчика.
- 🧵 Долгие операции внутри компоненты блокируют поток. Длинные задачи лучше выносить на сервер в фоновое задание.
Чем заменить внешнюю компоненту
Компонента — мощный, но дорогой в сопровождении инструмент: её нужно собирать под все ОС и разрядности, обновлять, проверять после каждого обновления платформы. Часто задачу решает что-то проще.
| Подход | Когда подходит | Минусы |
|---|---|---|
Средства платформы (HTTPСоединение, ЧтениеXML, ЧтениеJSON, ЧтениеZipФайла и др.) | обмен с API, разбор форматов, архивы | не всё есть «из коробки» |
Новый COMОбъект("...") | вызов установленной в Windows программы или библиотеки | только Windows, нет на Linux-сервере |
ЗапуститьПриложение / КомандаСистемы | разовый вызов внешней утилиты с файлом на входе | медленно, сложно ловить ошибки |
| HTTP-сервис рядом (микросервис) | тяжёлая логика на Python, Go, .NET | отдельный сервер и его поддержка |
| HTTP-сервисы в самой 1С | когда внешняя система сама должна обращаться к 1С | не заменяет вызов «из 1С наружу» |
Правило выбора простое. Если нужна работа с оборудованием, скорость в цикле или функции ОС на клиенте — нужна внешняя компонента, лучше по технологии Native API. Если задача — обменяться данными с внешней системой, хватит HTTP и встроенных средств разбора форматов.
Для своих разработок 1С публикует шаблоны Native API на C++ в составе документации по технологии. Есть и открытые проекты сообщества, где собраны готовые компоненты и шаблоны сборки под Windows и Linux.