Как подключить DLL-библиотеку в 1С

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

Выбор способа зависит от того, как разработана сама библиотека. Если поставщик оборудования или ПО предоставляет COM-компонент, подключение выполняется через создание COM-объекта или регистрацию в системе. Если компонента написана по Native API, её подключают методом ПодключитьВнешнююКомпоненту. Обычная «неуправляемая» DLL с экспортируемыми функциями без COM-интерфейса напрямую из кода 1С не вызывается — для неё понадобится обёртка.

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

Какие виды DLL поддерживает платформа 1С

Платформа 1С:Предприятие работает с внешними библиотеками через два механизма. Первый — технология COM (Component Object Model): библиотека регистрируется в реестре Windows, после чего её классы доступны по программному идентификатору (ProgID). Второй — внешние компоненты по технологии Native API, разработанной специально для 1С: такие компоненты могут поставляться в составе макета конфигурации, подключаться из файла или из ZIP-архива и работать также в веб-клиенте и на Linux-сервере.

Важно понимать ограничение: обычная DLL, экспортирующая функции в стиле WinAPI (без COM-интерфейсов и без поддержки Native API), из встроенного языка 1С недоступна. Попытка «подключить» такой файл методом ПодключитьВнешнююКомпоненту завершится ошибкой, потому что платформа ищет в библиотеке точки входа, определённые стандартом компонент.

Подключение COM-библиотеки через COMОбъект

Если библиотека реализована как COM-сервер, сначала её нужно зарегистрировать в операционной системе. Регистрация выполняется утилитой regsvr32, запущенной с правами администратора. Для 32-разрядной DLL на 64-разрядной Windows используется утилита из каталога SysWOW64, для 64-разрядной — из System32.

regsvr32 "C:\Components\MyLibrary.dll"

После успешной регистрации объект создаётся в коде 1С по его ProgID — строковому идентификатору, который поставщик библиотеки указывает в документации:

Компонент = Новый COMОбъект("MyLibrary.MyClass");
Результат = Компонент.ВыполнитьДействие(Параметр);

Если ProgID неизвестен, его можно найти в реестре Windows: зарегистрированные классы перечислены в ветке HKEY_CLASSES_ROOT. Также документацию к COM-объекту обычно можно получить у поставщика библиотеки — без неё имена методов и их параметры придётся угадывать, что непродуктивно.

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

Компоненты Native API подключаются методом глобального контекста ПодключитьВнешнююКомпоненту. В качестве параметра указывается либо путь к файлу DLL, либо навигационная ссылка на макет в конфигурации, если компонента встроена в неё. Второй параметр — имя, под которым компонента будет доступна, третий (необязательный) — тип компоненты.

Если ПодключитьВнешнююКомпоненту("C:\Components\AddIn.dll", "МояКомпонента", ТипВнешнейКомпоненты.Native) Тогда
Компонент = Новый ("AddIn.МояКомпонента.MyComponent");
Иначе
Сообщить("Не удалось подключить компоненту");
КонецЕсли;

Метод возвращает булево значение, поэтому подключение всегда следует оборачивать в проверку результата. После успешного подключения объект компоненты создаётся конструктором Новый со строковым именем вида «AddIn.ИмяПодключения.ИмяОбъекта». Точное имя объекта указывается в документации к компоненте.

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

1. 1
   Убедитесь, что DLL реализует Native API (уточните у поставщика или в документации)
2. 2
   Проверьте совпадение разрядности DLL и клиента 1С
3. 3
   Поместите DLL в доступный каталог или в макет конфигурации
4. 4
   Вызовите ПодключитьВнешнююКомпоненту с проверкой возвращаемого значения
5. 5
   Создайте объект через Новый ("AddIn...") и вызовите тестовый метод
6. 6
   Зафиксируйте обработку ошибки на случай отсутствия файла

Разрядность и место выполнения кода

Самая частая причина неудачного подключения — несовпадение разрядности. 32-разрядная DLL загружается только в 32-разрядный процесс, 64-разрядная — только в 64-разрядный. Если код выполняется на тонком клиенте, разрядность определяется установленным клиентским приложением; если на сервере 1С — разрядностью сервера. Поэтому одна и та же компонента может работать при отладке в файловой базе и не подключаться в клиент-серверном варианте.

Второй аспект — место исполнения. Конструкция Новый COMОбъект и подключение компоненты из файловой системы выполняются на той стороне, где работает код. Если код серверный, DLL должна лежать на сервере и быть доступна учётной записи, под которой работает агент сервера 1С. В веб-клиенте COM-объекты недоступны вовсе, а внешние компоненты требуют специальной сборки и установки расширения для браузера.

Что делать с обычной DLL без COM-интерфейса

Если в распоряжении только «классическая» DLL с экспортируемыми функциями, прямого пути из 1С нет. Практические варианты такие: создать COM-обёртку на C#, C++ или Delphi, которая внутри себя вызывает нужные функции DLL; переписать компоненту по Native API, если есть доступ к исходному коду; либо вынести логику во внешнюю программу или HTTP-сервис и обмениваться данными с ней из 1С.

Обёртка на .NET — наиболее быстрый путь: класс помечается атрибутами COM-видимости, сборка регистрируется утилитой regasm, после чего доступна из 1С как обычный COMОбъект. Этот способ требует навыков разработки вне 1С, но даёт полный контроль над передачей параметров и обработкой ошибок.

Типичные ошибки и их устранение

Ошибка «Недопустимая строка с указанием класса» при создании COMОбъекта означает, что класс не зарегистрирован: либо не выполнен regsvr32, либо регистрация прошла в «не той» разрядности реестра. Проверьте, какой версией regsvr32 пользовались, и повторите регистрацию нужной.

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

Безопасность и сопровождение

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

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

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