Подключение внешней компоненты в 1С 8.3: Native API, COM и сервер

Внешнюю компоненту в 1С 8.3 устанавливают по-разному в зависимости от её технологии. Компоненту Native API (ZIP-архив с MANIFEST.XML и DLL/SO внутри) ставит сама платформа: методом УстановитьВнешнююКомпоненту() или через справочник внешних компонент в типовой конфигурации. Компоненту COM (одиночная DLL) сначала регистрируют в Windows командой regsvr32 от имени администратора, и только потом подключают из 1С.

Чаще всего компонента «не встаёт» по трём причинам: не совпала разрядность, её поставили на клиент, а код выполняется на сервере, или COM-библиотека не зарегистрирована.

1. Подготовка: определите тип компоненты и разрядность платформы

Прежде чем что-то устанавливать, откройте то, что прислал поставщик. По содержимому сразу видно, какой путь установки нужен.

Как прочитать манифест

Манифест Native API-компоненты перечисляет сборки под разные системы. Типичный вид:

<?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>

Если в манифесте нет строки под вашу ОС и разрядность, компонента на этой машине не подключится, как её ни устанавливай.

Как узнать разрядность 1С

• 💻 Клиент. Откройте Справка → О программе (или значок «i» в заголовке окна). В строке версии платформы указано «(64-bit)» для 64-разрядного клиента; если пометки нет — клиент 32-разрядный.
• 🖥️ Сервер. Смотрите, в какой папке установлен сервер: C:\Program Files\1cv8\ — 64-разрядный, C:\Program Files (x86)\1cv8\ — 32-разрядный.
• 🔢 Версия платформы. Номер в окне «О программе». Поставщик компоненты часто указывает минимальный номер, например «не ниже 8.3.10».

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

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

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

:: 64-разрядная DLL для 64-разрядного клиента или сервера 1С
C:\Windows\System32\regsvr32.exe "C:\1C_AddIns\MyComponent64.dll"

:: 32-разрядная DLL для 32-разрядного клиента 1С
C:\Windows\SysWOW64\regsvr32.exe "C:\1C_AddIns\MyComponent32.dll"

4. Дождитесь сообщения об успешной регистрации. Отмена регистрации делается той же командой с ключом /u.

Если у COM-компоненты есть зависимости (например, библиотеки Microsoft Visual C++ Redistributable), их ставят до регистрации. Список зависимостей обычно указан в документации поставщика.

3. Подключение внешней компоненты в конфигураторе и в типовой базе

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

Через справочник внешних компонент (БСП)

В актуальных релизах конфигураций на Библиотеке стандартных подсистем есть отдельный список внешних компонент. Он находится в разделе Администрирование → Печатные формы, отчеты и обработки, ссылка «Внешние компоненты» (в старых релизах ссылки может не быть).

1. Откройте список и нажмите «Добавить из файла».
2. Выберите ZIP-архив компоненты.
3. Проверьте, что программа прочитала идентификатор и версию, и запишите элемент.

Из этого списка компоненту берут встроенные механизмы и внешние обработки, которые обращаются к ней по идентификатору. Драйверы торгового оборудования ставятся отдельно — в разделе Администрирование → Подключаемое оборудование, в карточке экземпляра оборудования.

Через общий макет в конфигураторе

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

Теперь код подключает компоненту по имени макета:

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

ИмяОбъекта замените на имя класса из документации компоненты. Полное имя всегда собирается по схеме AddIn.<Имя из ПодключитьВнешнююКомпоненту>.<Имя класса>.

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

Зарегистрированная COM-компонента подключается по своему ProgID, без макета:

Подключено = ПодключитьВнешнююКомпоненту("ProgID.Компоненты");

ProgID берут из документации. COM работает только в Windows: в Linux-клиенте и на Linux-сервере такой способ невозможен.

Компонента внутри внешней обработки

Если конфигурацию менять нельзя, компоненту кладут в макет самой внешней обработки (.epf). В конфигураторе откройте обработку, добавьте макет с типом «Двоичные данные» и загрузите в него ZIP-архив.

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

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

Адрес из временного хранилища передаётся в УстановитьВнешнююКомпоненту() и ПодключитьВнешнююКомпоненту() вместо строки ОбщийМакет.…. Так поставщики распространяют обработки для весов, сканеров и печати этикеток: одна обработка, без правки базы.

Как проверить, что всё работает

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

4. Внешняя компонента в клиент-серверном варианте 1С

В файловой базе всё просто: код, клиент и компонента живут на одном компьютере. В клиент-серверной базе сначала ответьте на вопрос: где выполняется код, который вызывает компоненту?

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

• 🔁 Все рабочие серверы. Если в кластере два-три рабочих сервера, сеанс может попасть на любой. COM-компоненту регистрируют на каждом, иначе ошибка будет «плавающей».
• 👤 Права учётной записи. Служба «Агент сервера 1С:Предприятия 8.3» работает от своего пользователя (часто USR1CV8). У него должны быть права на чтение папки с DLL.
• 🐧 Linux-сервер. Подойдёт только Native API со сборкой .so под Linux. В манифесте должна быть строка os="Linux".
• 🧱 Сбой компоненты. Код компоненты работает внутри процесса rphost. Если он аварийно завершится, оборвутся сеансы всех пользователей, обслуживаемых этим процессом.

Native API-компоненту из макета на сервере отдельно устанавливать не надо: ПодключитьВнешнююКомпоненту() в серверном коде сам извлечёт её из макета.

5. Ошибки при установке внешней компоненты и как их разобрать

Если ошибка не уходит

• 🧹 Кэш установленных компонент. На клиенте Windows платформа хранит установленные компоненты в профиле пользователя, в папке %APPDATA%\1C\1cv8\ExtCompT. Закройте 1С, очистите эту папку и запустите установку снова.
• 🧾 Журнал регистрации. Серверные ошибки подключения пишутся в журнал: Администрирование → Обслуживание → Журнал регистрации, отбор по уровню «Ошибка».
• 🛡️ Антивирус. Он может удалять неизвестные DLL при распаковке. Проверьте карантин и добавьте папку компоненты в исключения, если поставщик вам известен.
• 🔄 Версия платформы. Компоненты, собранные под свежую платформу, иногда не работают на номере ниже заявленного. Сверьте с требованиями поставщика.

6. Безопасность и обновление внешних компонент

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

Правила безопасности

• ✅ Ставьте компоненты только от известного поставщика: официальный сайт разработчика, поставка вместе с оборудованием или конфигурацией.
• ✅ Если платформа или конфигурация спрашивает подтверждение установки, читайте, что именно ставится, а не нажимайте «Да» по привычке.
• ✅ Для серверных баз с профилями безопасности компоненту разрешают в профиле явно: без этого её загрузка будет запрещена.
• ❌ Не берите «доработанные» сборки с форумов. Подменённая DLL получает доступ ко всему, что видит рабочий процесс.

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

1. Получите новую версию и проверьте манифест: сборки под все нужные ОС и разрядности на месте.
2. Обновите источник: загрузите новый ZIP в справочник внешних компонент или в общий макет, затем обновите конфигурацию базы данных.
3. На клиентах очистите кэш ExtCompT или дождитесь, пока платформа предложит переустановить компоненту.
4. Для COM: отмените регистрацию старой DLL (regsvr32 /u), замените файл, зарегистрируйте заново.
5. На сервере уже загруженная компонента держится в памяти рабочего процесса до его перезапуска.

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