Внешние компоненты, COM-библиотеки и БСП: подключение к 1С 8.3

Чтобы подключить библиотеку в 1С 8.3, положите её в общий макет конфигурации и вызовите ПодключитьВнешнююКомпоненту("ОбщийМакет.ИмяМакета", "Имя", ТипВнешнейКомпоненты.Native). Если это COM-библиотека (DLL), её сначала регистрируют в Windows через regsvr32, а в коде создают объект Новый COMОбъект("ProgID"). Библиотеку программных модулей вроде БСП подключают иначе: объединением конфигураций в Конфигураторе.

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

Что называют библиотекой в 1С и какой способ вам нужен

Слово «библиотека» в мире 1С означает три разные вещи. От того, какая у вас, зависит весь порядок действий.

• 🔌 Внешняя компонента — код на C++, который расширяет язык 1С: работа с оборудованием, криптография, нестандартные форматы, системные вызовы.
• 🪟 COM — старый, но живой способ. Через него 1С управляет Excel, Word, сторонними программами и .NET-сборками, опубликованными как COM.
• 📚 Библиотека конфигураций — набор общих модулей, подсистем и объектов метаданных. Самая известная — «Библиотека стандартных подсистем» (БСП), на ней построены почти все типовые решения.

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

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

Шаг 1. Соберите архив с манифестом

Если поставщик дал одну DLL, лучше упаковать её в 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>

Файлы библиотек и манифест лежат в корне архива, без вложенных папок. Если какой-то сборки у вас нет — просто не указывайте её строку. Но тогда на этой платформе компонента не загрузится.

Шаг 2. Добавьте макет в конфигурацию

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

Шаг 3. Подключите компоненту в коде на клиенте

На клиенте компоненту нужно сначала установить в профиль пользователя, а потом подключить. Удобно сделать это асинхронно (асинхронные методы с Ждать доступны в платформе с номером не ниже 8.3.18):

&НаКлиенте
Асинх Процедура ПодключитьСканер(Команда)

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

    Если Не Подключено Тогда
        Ждать УстановитьВнешнююКомпонентуАсинх(Местоположение);
        Подключено = Ждать ПодключитьВнешнююКомпонентуАсинх(Местоположение, "Сканер", ТипВнешнейКомпоненты.Native);
    КонецЕсли;

    Если Не Подключено Тогда
        Сообщить("Не удалось подключить компоненту сканера");
        Возврат;
    КонецЕсли;

    Сканер = Новый("AddIn.Сканер.ScannerClass");

КонецПроцедуры

Строка AddIn.Сканер.ScannerClass собирается из трёх частей: постоянного префикса AddIn, символического имени, которое вы сами передали вторым параметром, и имени класса внутри компоненты. Имя класса берите из документации поставщика: угадать его нельзя.

Шаг 4. Подключение на сервере

На сервере установка не нужна, достаточно подключения. Метод возвращает Истина или Ложь, исключение он не выбрасывает — результат обязательно проверяйте:

&НаСервере
Функция ПодписатьНаСервере(Данные)

    Если Не ПодключитьВнешнююКомпоненту("ОбщийМакет.КомпонентаКрипто", "Крипто", ТипВнешнейКомпоненты.Native) Тогда
        ВызватьИсключение "Компонента криптографии не подключена на сервере";
    КонецЕсли;

    Крипто = Новый("AddIn.Крипто.CryptoClass");
    // дальше вызовы методов компоненты по её документации

КонецФункции

Для серверного подключения в архиве должна быть сборка под ОС и разрядность сервера 1С, а не вашего рабочего компьютера. Сервер на Linux x86_64 потребует .so под x86_64, даже если все пользователи сидят на Windows.

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

COM подходит, когда библиотека уже существует как COM-сервер и переписывать её под Native API никто не будет. Ограничение одно и жёсткое: только Windows.

Регистрация DLL

1. Скопируйте DLL в постоянную папку, например C:\Program Files\Vendor\Lib\. Из «Загрузок» не регистрируйте: файл потом удалят.
2. Запустите командную строку от имени администратора.
3. Выполните регистрацию утилитой нужной разрядности:

:: 64-битная DLL
C:\Windows\System32\regsvr32.exe "C:\Program Files\Vendor\Lib\MyLib.dll"

:: 32-битная DLL на 64-битной Windows
C:\Windows\SysWOW64\regsvr32.exe "C:\Program Files\Vendor\Lib\MyLib.dll"

Названия папок сбивают с толку, но так устроена Windows: System32 — для 64-битных файлов, SysWOW64 — для 32-битных.

Для .NET-сборок вместо regsvr32 используется regasm из папки нужной версии .NET Framework с ключом /codebase. Сборка должна быть собрана с атрибутом видимости для COM.

Вызов из 1С

Попытка
    Библиотека = Новый COMОбъект("Vendor.MyLib");
Исключение
    Сообщить("Ошибка создания COM-объекта: " + ОписаниеОшибки());
    Возврат;
КонецПопытки;

ProgID (Vendor.MyLib) указан в документации библиотеки. Его же можно найти в реестре, в ветке HKEY_CLASSES_ROOT, — поиском по имени DLL.

Разрядность COM-библиотеки должна совпадать с разрядностью процесса 1С, который её вызывает. 64-битный клиент 1С не создаст объект из 32-битной in-process DLL. Если пересобрать библиотеку нельзя, ставят клиент той же разрядности.

Подключение библиотечной конфигурации: БСП и другие

Здесь библиотека — не файл в макете, а куски кода и метаданных, которые встраиваются в вашу конфигурацию. Так подключают БСП, «Библиотеку электронных документов», «Библиотеку интернет-поддержки» и подобные решения.

Порядок для своей конфигурации:

1. Сделайте выгрузку базы: Администрирование → Выгрузить информационную базу в Конфигураторе. Без копии не начинайте — объединение затрагивает много объектов сразу.
2. Если конфигурация ещё не на поддержке, включите её: Конфигурация → Поддержка → Настройка поддержки.
3. Выберите Конфигурация → Сравнить, объединить с конфигурацией из файла и укажите .cf библиотеки.
4. На вопрос о постановке на поддержку ответьте «Да»: тогда библиотеку потом можно будет обновлять штатно, у конфигурации появится второй поставщик.
5. В окне сравнения снимите все флажки, затем отметьте только нужные подсистемы. Кнопка отбора по подсистемам подтягивает связанные объекты.
6. Выполните объединение, затем обновление конфигурации базы данных.

Для БСП в комплекте поставки есть отдельная обработка и документация по первому внедрению: в ней описано, какие подсистемы от каких зависят и какой код нужно дописать в модулях вашей конфигурации. Выбирать подсистемы «на глаз» рискованно — недостающая зависимость всплывёт ошибкой компиляции.

Права доступа и безопасный режим

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

Безопасный режим и профили безопасности

• 🔒 Внешние обработки и отчёты, открытые в безопасном режиме, не могут подключать внешние компоненты и создавать COM-объекты.
• 🛡️ Если на кластере включены профили безопасности, разрешённые компоненты, COM-классы и приложения задаются в свойствах профиля в консоли администрирования серверов 1С. Без разрешения вызов на сервере завершится ошибкой.
• 🧩 Расширения конфигурации тоже могут работать в безопасном режиме — это задаётся в свойствах расширения. Для расширения с компонентой этот флажок придётся снять, если профиль её не разрешает.

Права пользователя ОС

На клиенте компонента устанавливается в профиль текущего пользователя Windows, прав администратора для этого не нужно. Поэтому каждый новый пользователь компьютера проходит установку заново — это нормально.

На сервере всё выполняется от имени учётной записи службы сервера 1С. Ей нужны права на чтение папки с COM-библиотекой. Для внешних COM-серверов (.exe) могут понадобиться ещё и права запуска в настройках DCOM — dcomcnfg.

Права в самой 1С

Отдельного права «подключать компоненты» в ролях нет. Ограничивают через код: команду, которая вызывает компоненту, кладут в модуль или форму, доступные только нужной роли. На сервере проверку делают через РольДоступна или функции БСП работы с правами.

Обновление подключённой библиотеки

Как обновлять, зависит от способа подключения.

Для макета откройте его двойным щелчком и загрузите новый файл на место старого. Имя макета не меняйте — иначе придётся править все вызовы в коде.

Для COM-библиотеки старую регистрацию снимают командой regsvr32 /u с путём к DLL, затем копируют новую версию и регистрируют её. Пока процесс 1С держит DLL загруженной, файл не заменить. На сервере это значит перезапуск службы.

Обновление библиотечной конфигурации идёт строго по версиям: БСП нельзя «перепрыгнуть» на любую версию. Допустимые переходы перечислены в описании поставки. Если ваша версия слишком старая, обновляйтесь цепочкой.

Где взять готовые библиотеки и как написать свою

Готовые библиотеки

• 🏢 Поставщики оборудования и сервисов. Драйверы весов, сканеров, ККТ, банковских терминалов распространяются как внешние компоненты. Берите только с сайта производителя.
• 📦 Комплекты поставки 1С. БСП, библиотека интернет-поддержки и другие библиотеки скачиваются с портала обновлений при наличии договора сопровождения.
• 🌐 Открытые проекты. На GitHub публикуют компоненты с исходным кодом: работа с окнами, HTTP, регулярными выражениями, штрихкодами. Плюс — можно проверить код и собрать самому.
• 🛒 Каталоги разработок для 1С. Удобно искать по задаче, но качество разное.

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

Своя внешняя компонента

Native API-компонента пишется на C++. Отправная точка — шаблон и описание технологии создания внешних компонент от фирмы 1С: там есть заголовочные файлы с интерфейсами и пример проекта.

Что придётся реализовать:

1. Класс, наследующий IComponentBase, с методами описания свойств и методов компоненты.
2. Экспортируемые функции GetClassNames, GetClassObject, DestroyObject и SetPlatformCapabilities.
3. Сборки под каждую нужную пару «ОС + разрядность».
4. MANIFEST.XML и ZIP-архив, как в шаге 1 выше.

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

Своя библиотечная конфигурация

Если нужно переиспользовать код 1С между проектами, сделайте отдельную конфигурацию-библиотеку: общие модули, подсистема, нужные справочники. Затем через Конфигурация → Поставка конфигурации создайте файлы поставки .cf и .cfu. Потребители подключат её объединением, как БСП, и будут обновлять через механизм поддержки.

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

Ошибки при подключении и что с ними делать

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

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