Внешние компоненты в 1С 8.3: от DLL и макета до вызова из кода

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

Типичная ситуация: поставщик весов или сканера прислал архив с парой DLL и коротким письмом «подключите к 1С». Программист добавляет вызов в форму, а пользователь видит Тип не определен (AddIn...). Почти всегда причина в одном из трёх мест: тип компоненты, разрядность или сторона (клиент/сервер), где идёт подключение.

1. С чего начать: какой тип компоненты у вас на руках

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

Как понять, что прислали:

• 📦 Архив .zip с файлом MANIFEST.XML внутри — это готовый пакет Native API (иногда в него входят и COM-варианты).
• 🧩 Одна .dll и инструкция «зарегистрируйте» — скорее всего COM.
• 🐧 Есть файлы .so — компонента собрана и под Linux, это точно Native API.
• 📄 Нет документации — спросите у поставщика ProgID (для COM) или имена объектов (для Native API). Без них из кода к компоненте не обратиться.

Что подготовить заранее

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

2. Регистрация COM-компоненты в Windows

Этот шаг нужен только для COM. Компоненты Native API в реестре не регистрируются: платформа сама извлекает их из макета.

Регистрация через regsvr32

Откройте командную строку от имени администратора и выполните команду для нужной разрядности:

:: 64-битная DLL — утилита из System32
C:\Windows\System32\regsvr32.exe "C:\Components\MyComponent64.dll"

:: 32-битная DLL на 64-битной Windows — утилита из SysWOW64
C:\Windows\SysWOW64\regsvr32.exe "C:\Components\MyComponent.dll"

Путаница здесь классическая: в 64-битной Windows папка System32 хранит 64-битные программы, а SysWOW64 — 32-битные. Если зарегистрировать 32-битную DLL не той утилитой, она либо не зарегистрируется, либо 64-битный клиент 1С её не увидит.

Удаление регистрации — тем же regsvr32 с ключом /u:

C:\Windows\System32\regsvr32.exe /u "C:\Components\MyComponent64.dll"

Где регистрировать

• 🖥️ Компонента работает на клиенте — регистрируйте на каждом компьютере пользователя.
• 🗄️ Компонента вызывается в серверном коде — регистрируйте на каждом рабочем сервере кластера 1С.
• 🌐 Терминальный сервер — один раз на сервере, всем пользователям хватит.

3. Как добавить внешнюю компоненту в конфигурацию

Хранить компоненту внутри конфигурации удобнее всего: она обновляется вместе с базой, её не нужно раскладывать по компьютерам вручную. Для Native API это основной способ.

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

Если поставщик прислал готовый ZIP с MANIFEST.XML, переходите к шагу 2. Если есть только файлы библиотек, создайте манифест сами:

<?xml version="1.0" encoding="UTF-8"?>
<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle">
  <component os="Windows" path="MyComp32.dll" type="native" arch="i386"/>
  <component os="Windows" path="MyComp64.dll" type="native" arch="x86_64"/>
  <component os="Linux" path="libMyComp32.so" type="native" arch="i386"/>
  <component os="Linux" path="libMyComp64.so" type="native" arch="x86_64"/>
</bundle>

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

Шаг 2. Создайте общий макет

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

Вариант для внешней обработки

У внешней обработки нет общих макетов конфигурации. Добавьте в саму обработку макет типа «Двоичные данные» с тем же ZIP, а перед подключением поместите его во временное хранилище:

&НаСервере
Функция АдресКомпоненты()
    Макет = РеквизитФормыВЗначение("Объект").ПолучитьМакет("КомпонентаВесов");
    Возврат ПоместитьВоВременноеХранилище(Макет, УникальныйИдентификатор);
КонецФункции

Полученный адрес передаётся первым параметром в метод подключения вместо строки ОбщийМакет.Имя.

4. Подключение и вызов внешней компоненты из кода модуля

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

Синхронный вариант (сервер и старые конфигурации)

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

Если Не Подключено Тогда
    ВызватьИсключение "Не удалось подключить компоненту КомпонентаВесов";
КонецЕсли;

Весы = Новый("AddIn.Scales.Device"); // Device — имя объекта из документации

Символическое имя Scales — ваше, оно связывает вызов подключения и строку AddIn.Scales.... Имя объекта Device задаёт автор компоненты, его берут только из документации.

Асинхронный вариант на клиенте

В свойствах корня конфигурации есть параметр «Режим использования синхронных вызовов расширений платформы и внешних компонент». В современных типовых он стоит в «Не использовать». Тогда синхронный ПодключитьВнешнююКомпоненту на клиенте вызовет ошибку, и нужен асинхронный вызов (платформа 8.3.18 и новее):

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

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

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

    Если Подключено Тогда
        Весы = Новый("AddIn.Scales.Device");
        // дальше вызываете методы компоненты по её документации
    Иначе
        Сообщить("Компонента весов не подключена");
    КонецЕсли;

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

На платформе ниже 8.3.18 вместо Асинх/Ждать используют пару НачатьПодключениеВнешнейКомпоненты и НачатьУстановкуВнешнейКомпоненты с обработчиками через ОписаниеОповещения.

Подключение COM-компоненты

Для зарегистрированной в системе COM-компоненты местоположение — это её ProgID, а тип — ТипВнешнейКомпоненты.COM:

Подключено = ПодключитьВнешнююКомпоненту("ProgID.От.Поставщика", "Scanner", ТипВнешнейКомпоненты.COM);

Если компонента — обычный COM-объект, а не внешняя компонента в смысле 1С, подключать её не нужно. Достаточно Новый COMОбъект("ProgID") — так работают, например, с Excel.

Что ещё стоит знать про код

• 🔁 Подключайте компоненту один раз за сеанс и храните объект в переменной модуля формы или в параметрах приложения. Повторное подключение с тем же именем лишнего не сломает, но и пользы не даст.
• 📡 Компоненты оборудования присылают события. Их ловят в процедуре ОбработкаВнешнегоСобытия(Источник, Событие, Данные) модуля формы или модуля управляемого приложения.
• 🧰 В конфигурациях на БСП есть готовая обёртка ОбщегоНазначенияКлиент.ПодключитьКомпонентуИзМакета: она сама устанавливает компоненту при первом запуске и показывает понятные сообщения.

5. Почему компонента не подключается: разбор ошибок

Проверки, которые экономят время

1. Логический результат. Всегда проверяйте, что вернул метод подключения. Ложь без исключения — это отказ, и причину платформа не пишет.
2. Разрядность процесса. Запустите клиент, откройте Справка → О программе: там видны версия и разрядность платформы.
3. Зависимости библиотеки. Компонента может требовать Visual C++ Redistributable в Windows или системные библиотеки в Linux. В Linux недостающие библиотеки показывает ldd libMyComp64.so.
4. Права в профиле. Платформа извлекает компоненты Native API в каталог пользователя (папка ExtCompT внутри профиля 1С). Если папка закрыта политиками, установка молча не проходит.
5. Безопасный режим. Код внешних обработок может выполняться в безопасном режиме или под профилем безопасности, где внешние компоненты запрещены. Проверьте настройки профиля безопасности для информационной базы.

6. Внешняя компонента в клиент-серверной базе

В файловом варианте всё выполняется на компьютере пользователя, и клиент со «сервером» совпадают. В клиент-серверном варианте серверный код работает в процессах rphost на сервере 1С, и это меняет правила.

Что учитывать на сервере:

• 🗄️ Сервер 1С почти всегда 64-битный. В архиве должна быть сборка x86_64 под ОС сервера: Windows или Linux.
• 🔐 Служба сервера работает от служебной учётной записи (часто USR1CV8). У неё должны быть права на чтение и запуск DLL и на её рабочий каталог.
• ⚙️ Установка на сервере не нужна: ПодключитьВнешнююКомпоненту в серверном коде сам извлекает компоненту из макета.
• 🧱 Компонента с окнами и диалогами на сервере работать не будет: у службы нет рабочего стола. Оборудование (весы, сканеры, ККТ) подключают на клиенте.

Как обновить компоненту на сервере

Загруженная DLL заблокирована процессом rphost, пока он жив. После замены макета новые сеансы могут продолжать работать со старой сборкой.

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

7. Частые вопросы о подключении внешних компонент