Внешние компоненты 1С 8.3: установка, регистрация и подключение без ошибок

Чтобы установить компоненту в 1С, сначала определите её тип. COM-компоненту (файл .dll с регистрацией в Windows) регистрируют командой regsvr32 от имени администратора. Native-компоненту (архив .zip с файлом MANIFEST.XML) не регистрируют вовсе: её подключает сама платформа 1С:Предприятие из макета конфигурации, из файла или из базы.

Почти все проблемы при установке внешних компонентов сводятся к двум вещам. Это разрядность (32-битный клиент не загрузит 64-битную библиотеку и наоборот) и место выполнения: компонента стоит у пользователя, а код вызывает её на сервере. Порядок ниже рассчитан на платформу 8.3 и Windows, отдельно разобраны сервер 1С, Linux и веб-клиент.

Какие бывают внешние компоненты 1С и чем они отличаются

Внешняя компонента — это библиотека, которая добавляет 1С то, чего нет в платформе. Типичные примеры: драйвер весов или сканера штрихкодов, работа с криптографией, генерация QR-кодов, обмен с банк-клиентом, нестандартный принтер этикеток.

Технологий подключения несколько, и от технологии зависит весь порядок установки.

Как отличить на практике:

• 📦 Поставщик прислал архив .zip, внутри есть MANIFEST.XML — это Native, регистрировать нечего.
• 🧩 Пришёл одиночный .dll и в инструкции упомянут ProgID (строка вида Vendor.ObjectName) — это COM.
• 💿 Пришёл setup.exe или .msi — инсталлятор сам скопирует файлы и зарегистрирует COM-объект.

Native-технология современнее. Она не требует прав администратора на рабочих местах, работает на сервере под Linux и не конфликтует с другими версиями той же библиотеки. Новые драйверы подключаемого оборудования поставляются именно так.

Подготовка: разрядность, права и место запуска

До установки ответьте себе на три вопроса. Это займёт пару минут и сбережёт час на поиск ошибки.

1. Какой разрядности клиент или сервер 1С

Библиотека должна совпадать по разрядности с процессом, который её загружает. Разрядность Windows значения не имеет.

• 🖥 Тонкий или толстый клиент. Посмотрите папку установки: C:\Program Files (x86)\1cv8\ — 32-битная платформа, C:\Program Files\1cv8\ — 64-битная. Ещё один способ: в клиенте откройте Справка → О программе, разрядность указана рядом с версией платформы.
• 🗄 Сервер 1С. Процессы ragent, rmngr, rphost в Диспетчере задач. На 64-битном сервере компонента для серверного кода тоже нужна 64-битная.

2. Где выполняется код, который вызывает компоненту

Это самый частый источник путаницы. Если вызов стоит в процедуре с директивой &НаКлиенте, компонента нужна на компьютере пользователя. Если &НаСервере — на каждом рабочем сервере кластера. В файловой базе «сервер» — это тот же компьютер пользователя, но в клиент-серверной это другая машина.

3. Хватает ли прав

• 🔑 Регистрация COM пишет в реестр, поэтому командная строка нужна от имени администратора.
• 👤 Native-компонента на клиенте ставится в профиль пользователя, админ-права не нужны.
• 🛡 На сервере COM-объект должен быть доступен учётной записи, под которой работает служба 1С (по умолчанию USR1CV8).

Автоматическая установка внешних компонентов: инсталлятор и запрос платформы

Самый простой путь — дать установке пройти автоматически. Вариантов три.

Инсталлятор поставщика

Если в поставке есть setup.exe или .msi, запускайте его через правую кнопку мыши → «Запуск от имени администратора». Инсталлятор скопирует файлы, зарегистрирует COM-объект и при необходимости поставит зависимости.

Ставьте версию той же разрядности, что и клиент 1С. У многих поставщиков есть оба варианта, и при 32-битном клиенте на 64-битной Windows нужен именно 32-битный.

Драйверы подключаемого оборудования

В типовых конфигурациях на БСП драйверы касс, сканеров и весов загружают прямо из программы. В БП 3.0 это раздел Администрирование → Подключаемое оборудование, в УТ 11 он находится в разделе НСИ и администрирование. Там открывается список драйверов: можно добавить новый из файла архива поставщика, а затем установить его на текущее рабочее место. Конфигурация сохранит архив в базе и при первом обращении поставит его другим пользователям.

Запрос платформы при первом обращении

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

Не отказывайтесь от установки в этом окне, если не уверены в источнике. Лучше закройте форму и уточните у администратора: при отказе код получит «компонента не подключена», и форма будет работать с ошибками до следующего запроса.

Ручная регистрация COM-компоненты через regsvr32

Если поставщик прислал только .dll, регистрируйте её сами.

1. Скопируйте библиотеку в постоянную папку, например C:\1C_Components\. Не регистрируйте из «Загрузок» и с рабочего стола: при удалении файла регистрация останется, а объект перестанет создаваться.
2. Откройте командную строку от имени администратора: меню «Пуск» → наберите cmd → правая кнопка → «Запуск от имени администратора».
3. Выполните команду той разрядности, которая нужна.

Для 64-битной библиотеки:

C:\Windows\System32\regsvr32.exe "C:\1C_Components\MyComponent64.dll"

Для 32-битной библиотеки на 64-битной Windows:

C:\Windows\SysWOW64\regsvr32.exe "C:\1C_Components\MyComponent32.dll"

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

4. Дождитесь сообщения об успешном выполнении DllRegisterServer.
5. Проверьте в 1С: в обработке или в модуле создайте объект по ProgID из документации поставщика.

Попытка
    Объект = Новый COMОбъект("Vendor.ObjectName");
    Сообщить("Компонента создана");
Исключение
    Сообщить(ОписаниеОшибки());
КонецПопытки;

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

C:\Windows\SysWOW64\regsvr32.exe /u "C:\1C_Components\MyComponent32.dll"

Старые компоненты в технологии AddIn регистрируются так же, а в 1С подключаются через ПодключитьВнешнююКомпоненту по ProgID и создаются как Новый("AddIn.ИмяКомпоненты"). Точное имя объекта смотрите в документации компоненты.

Native-компоненты: архив, MANIFEST.XML и пути подключения

Native-компонента — это архив, в котором лежат библиотеки под разные системы и манифест. Манифест говорит платформе, какой файл брать на какой ОС и разрядности:

<?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.18 и новее поддерживает асинхронные методы:

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

ИмяОбъекта — имя класса из документации компоненты. Имя "Скан" вы выбираете сами, оно становится частью строки AddIn.Скан.….

Куда ставится компонента на компьютере пользователя

Установленные Native-компоненты платформа кладёт в профиль пользователя Windows: %APPDATA%\1C\1cv8\ExtCompT\. Это объясняет две частые ситуации:

• 👥 Компоненту поставили одному сотруднику, а у коллеги на том же компьютере снова просит установку. Профили разные — это нормально.
• 🔄 Разработчик обновил макет, а у пользователя работает старое поведение. Помогает закрыть 1С и очистить папку ExtCompT: при следующем запуске платформа поставит свежую версию.

Компоненты на сервере 1С, в Linux и в веб-клиенте

Сервер 1С

На сервере Native-компонента из макета не требует УстановитьВнешнююКомпоненту: достаточно вызвать ПодключитьВнешнююКомпоненту в серверной процедуре, и платформа сама извлечёт нужную библиотеку.

С COM на сервере больше работы:

1. Зарегистрируйте библиотеку на каждом рабочем сервере кластера. Если серверов два, а зарегистрировано на одном, ошибка будет «плавающей»: сеанс попал на один сервер — работает, на другой — нет.
2. Разрядность библиотеки должна совпадать с разрядностью rphost.
3. Учётная запись службы 1С должна иметь доступ к папке с библиотекой и её зависимостями.

Linux

COM в Linux не существует. Под Linux работают только Native-компоненты, у которых в манифесте есть строка с os="Linux" и библиотека .so нужной разрядности. Если поставщик даёт только Windows-версию, перенос серверного кода на Linux-сервер сломает функцию.

Веб-клиент

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

Ошибки регистрации и подключения компонентов: диагностика

Найдите своё сообщение в списке и раскройте решение.

Если ни одна строка не подошла, запустите тот же код в отдельной внешней обработке и выведите ОписаниеОшибки() полностью. В тексте после кода ошибки обычно есть подсказка от самой библиотеки.

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