Внешние компоненты в 1С:Предприятии 8.3: от ZIP-архива до регистрации DLL на сервере
Содержание
Внешнюю компоненту 1С ставят по-разному в зависимости от её типа. Компоненту Native API (ZIP-архив с файлом MANIFEST.XML) не нужно регистрировать в Windows: конфигурация сама устанавливает её методом УстановитьВнешнююКомпоненту, а в типовых решениях на БСП её достаточно загрузить в справочник «Внешние компоненты». Компоненту COM (одна DLL) сначала регистрируют командой regsvr32 от имени администратора на каждом компьютере, где она будет работать, — у пользователя или на сервере 1С.
Дальше всё упирается в три вопроса. Где выполняется код: на клиенте или на сервере. Какая разрядность у процесса 1С. И есть ли у компоненты сборка под нужную ОС и браузер. Ошибись в любом из них — и получите сообщение Не удалось подключить внешнюю компоненту без внятных подробностей.
Сначала определите тип компоненты и где она будет работать
Посмотрите, что вам выдал поставщик. По составу поставки тип понятен сразу.
| Признак поставки | Технология | Где работает | Регистрация в Windows |
|---|---|---|---|
ZIP с MANIFEST.XML и несколькими DLL/SO внутри | Native API | Толстый, тонкий, веб-клиент, сервер; Windows и Linux — если в архиве есть сборки | Не нужна |
| Одна DLL или OCX, в документации указан ProgID | COM (ActiveX) | Только Windows: толстый и тонкий клиент, сервер 1С | Обязательна, regsvr32 |
Драйвер торгового оборудования с установщиком .exe | Обычно COM, иногда Native | Компьютер, к которому подключено устройство | Делает установщик |
Откройте MANIFEST.XML в блокноте. В нём перечислены сборки: для какой ОС (Windows, Linux, MacOS), какой разрядности (i386, x86_64) и для какого клиента. Если там нет строки под ваш 64-битный сервер на Linux, на этом сервере компонента не заработает, как её ни устанавливай.
Второй вопрос — контекст исполнения. Компонента живёт в том процессе, который её загрузил:
- 💻 код с директивой
&НаКлиенте— в процессе клиента у пользователя (1cv8c.exe,1cv8.exeили браузер); - 🖥️ код
&НаСерверев клиент-серверной базе — в рабочем процессеrphostна сервере 1С; - 📁 код
&НаСерверев файловой базе тонкого клиента — в том же клиентском процессе на компьютере пользователя.
Последний пункт часто сбивает с толку. Файловая база «работает», пока её переносят на сервер 1С. После переноса серверный код уходит на другую машину, и компоненту приходится ставить уже там.
Установка внешней компоненты в файловой базе
В файловом варианте всё происходит на компьютере пользователя. Порядок зависит от того, как компоненту подключает конфигурация.
Типовая конфигурация на БСП
В современных релизах БП 3.0, ЗУП 3.1, УТ 11 и других решениях на БСП есть справочник «Внешние компоненты». Его используют сервисы самой программы: сканеры штрихкодов, криптография, распознавание документов.
- Включите показ команды «Все функции»:
Главное меню → Сервис → Параметры, флажок «Отображать команду “Все функции”». - Откройте
Главное меню → Все функции → Справочники → Внешние компоненты. - Нажмите кнопку добавления и выберите загрузку из файла. Укажите ZIP-архив от поставщика.
- Программа прочитает манифест и заполнит идентификатор и версию. Проверьте, что они совпадают с документацией.
- Если подключена интернет-поддержка, компоненты из списка поддерживаемых можно загрузить и обновить с портала, без ручного поиска файла.
После загрузки компонента хранится в базе. При первом обращении программа сама предложит установить её на компьютер пользователя — пользователь соглашается, и всё.
Своя конфигурация или обработка
Если компонента подключается из вашего кода, положите архив в общий макет с типом «Внешняя компонента». Дальше код работает так: пробует подключить, при неудаче — устанавливает и подключает снова.
&НаКлиенте
Асинх Процедура ПодключитьКомпоненту(Команда)
Подключено = Ждать ПодключитьВнешнююКомпонентуАсинх(
"ОбщийМакет.МояКомпонента", "Comp", ТипВнешнейКомпоненты.Native);
Если Не Подключено Тогда
Ждать УстановитьВнешнююКомпонентуАсинх("ОбщийМакет.МояКомпонента");
Подключено = Ждать ПодключитьВнешнююКомпонентуАсинх(
"ОбщийМакет.МояКомпонента", "Comp", ТипВнешнейКомпоненты.Native);
КонецЕсли;
Если Подключено Тогда
// имя объекта после "AddIn.Comp." берите из документации компоненты
Объект = Новый("AddIn.Comp.ИмяОбъекта");
Иначе
Сообщить("Компонента не подключена");
КонецЕсли;
КонецПроцедуры
Асинхронные методы ...Асинх с Ждать появились в платформе 8.3.18. На платформе с номером ниже используйте пару НачатьУстановкуВнешнейКомпоненты и НачатьПодключениеВнешнейКомпоненты с описанием оповещения.
Установленные на клиенте компоненты лежат в профиле пользователя Windows, в папке %APPDATA%\1C\1cv8\ExtCompT. Это пригодится при диагностике.
Компонента на сервере 1С и в веб-клиенте
Клиент-серверный вариант добавляет два места установки: сервер 1С и браузер. Разберём их отдельно.
Серверный код
Native-компонента, подключённая из общего макета на сервере, разворачивается рабочим процессом сама. От администратора нужно три вещи:
- 🧩 В манифесте есть сборка под ОС и разрядность сервера. 64-битный сервер 1С грузит только 64-битную сборку.
- 📂 У пользователя, от имени которого запущена служба 1С (по умолчанию
USR1CV8), есть права на запись в свой профиль и во временный каталог. Туда распаковываются файлы. - 🛡️ Если для базы назначен профиль безопасности, в нём разрешена работа с этой компонентой (о профилях ниже).
Если в кластере несколько рабочих серверов, компонента разворачивается на каждом, где окажется сеанс. Сборка нужна под каждый из них. Разнородный кластер (Windows и Linux) — частая причина «плавающей» ошибки: на одном сервере подключилось, на другом нет.
Веб-клиент
В браузере компонента работает только через расширение для работы с 1С:Предприятием. Порядок:
- Пользователь открывает базу в браузере и выполняет действие, которому нужна компонента.
- Платформа предлагает установить расширение браузера — его ставят из магазина расширений браузера.
- Затем запускается установка самой компоненты: браузер скачивает установщик из макета, пользователь его запускает.
- Страницу перезагружают, и вызов
ПодключитьВнешнююКомпонентуАсинхвозвращаетИстина.
В веб-клиенте работают только компоненты Native API, в чьём манифесте есть сборки для браузера. COM-объекты в веб-клиенте недоступны в принципе. Если поставщик дал только DLL с ProgID, остаётся тонкий клиент или перенос вызова на сервер.
Регистрация COM-объекта и проверка в реестре
COM-компоненту регистрирует администратор Windows, а не 1С. Делается это на каждой машине, где её будут вызывать: у пользователей для клиентского кода, на сервере 1С — для серверного.
Как зарегистрировать DLL
Главное правило — разрядность DLL совпадает с разрядностью процесса 1С, который её загрузит. 32-битный клиент не видит 64-битную DLL и наоборот.
| Разрядность DLL | Чем регистрировать на 64-битной Windows |
|---|---|
| 64-бит | C:\Windows\System32\regsvr32.exe |
| 32-бит | C:\Windows\SysWOW64\regsvr32.exe |
Запустите командную строку от имени администратора и выполните:
cd /d C:\Components\MyComp
C:\Windows\SysWOW64\regsvr32.exe MyComp.dll
Должно появиться окно «DllRegisterServer в MyComp.dll успешно выполнен». Чтобы снять регистрацию перед обновлением, добавьте ключ /u:
C:\Windows\SysWOW64\regsvr32.exe /u MyComp.dll
Не регистрируйте DLL из папки «Загрузки» или с рабочего стола. Регистрация запоминает полный путь к файлу. Удалите файл — и компонента пропадёт у всех. Держите её в постоянном каталоге, например C:\Components.
Проверка в реестре
Если 1С пишет, что не находит объект, откройте regedit и найдите ProgID из документации:
- 🔎
HKEY_CLASSES_ROOT\<ProgID>\CLSID— здесь лежит GUID класса; - 🔎
HKEY_CLASSES_ROOT\CLSID\{GUID}\InprocServer32— путь к DLL для 64-битных процессов; - 🔎
HKEY_CLASSES_ROOT\WOW6432Node\CLSID\{GUID}\InprocServer32— то же для 32-битных.
Путь указывает на несуществующий файл — перерегистрируйте DLL. Запись есть только в ветке WOW6432Node, а сервер 1С 64-битный — нужна 64-битная сборка.
В коде COM-компоненту подключают по ProgID: ПодключитьВнешнююКомпоненту("ProgID") для компонент AddIn или Новый COMОбъект("ProgID") для обычных COM-объектов. Какой способ нужен, сказано в документации поставщика.
Права пользователей и профили безопасности
Компонента — это чужой машинный код внутри процесса 1С. Поэтому платформа ограничивает её запуск на нескольких уровнях.
Права в конфигурации
Ручная загрузка в справочник «Внешние компоненты» обычно доступна только роли полных прав. Рядовой пользователь компоненту использует, но добавить новую не может. Если сотрудник видит ошибку доступа при установке, проверьте не платформу, а его профиль групп доступа.
Безопасный режим и профили безопасности кластера
Внешние обработки и расширения часто работают в безопасном режиме. В нём нельзя подключать произвольные компоненты из файлов на диске — только из макетов конфигурации.
Если администратор кластера включил профили безопасности, для базы назначен профиль с ограничениями. Тогда:
- Откройте консоль администрирования серверов 1С.
- Найдите профиль безопасности в разделе кластера и откройте его свойства.
- Разрешите в нём нужные внешние компоненты или полный доступ к ним — решение за администратором, это вопрос политики безопасности.
Типовые конфигурации на БСП при включённых профилях сами формируют запрос разрешений. Администратор видит его при первом использовании и подтверждает в той же консоли.
Лицензия самой компоненты
Многие коммерческие компоненты проверяют собственную лицензию: файл ключа рядом с DLL, ключ в реестре или аппаратный ключ. Это не связано с лицензией 1С.
- 🔑 Лицензия «на рабочее место» — ключ ставится на каждый компьютер пользователя.
- 🔑 Лицензия «на сервер» — ставится на сервер 1С, и тогда компоненту вызывают из серверного кода.
- 🔑 Пробный период — компонента работает с ограничениями. Узнать срок можно только у поставщика.
Компонента подключилась, но методы возвращают ошибку или пустые значения — сначала проверьте лицензию по документации поставщика.
Почему компонента не подключается: диагностика
Метод ПодключитьВнешнююКомпоненту при неудаче возвращает Ложь без подробностей. Причину ищут по косвенным признакам.
Журнал регистрации
В типовых конфигурациях на БСП ошибки установки и подключения пишутся в журнал регистрации. Откройте Администрирование → Обслуживание → Журнал регистрации и отберите события по уровню «Ошибка» и времени попытки. Там бывает текст исключения и имя компоненты.
Для серверных сбоев журнала мало. Включите технологический журнал через файл logcfg.xml и соберите события EXCP за время воспроизведения. В тексте исключения обычно видно, какую библиотеку не удалось загрузить.
Переустановка на клиенте
Если клиент «застрял» на битой или старой версии:
- Попросите пользователя закрыть все окна 1С.
- Удалите содержимое
%APPDATA%\1C\1cv8\ExtCompT. - Запустите базу и повторите действие — компонента установится заново.
Если компонента стоит на сервере и после замены DLL работает старая версия, сервер держит библиотеку загруженной в процессе rphost. Помогает перезапуск рабочих процессов или службы 1С. Это оборвёт сеансы всех пользователей кластера — делайте вечером, предупредив людей заранее.
Перед обновлением компоненты
Новая версия компоненты — тоже установка, только с риском сломать то, что работало. Короткий порядок:
- 📦 Сохраните предыдущий архив или DLL. Откат — это просто загрузка старого файла.
- 🧪 Проверьте новую версию на копии базы. Особенно если компонента печатает чеки или подписывает документы.
- 🔁 Для COM: снимите регистрацию со старой DLL (
regsvr32 /u), замените файл, зарегистрируйте заново. - 🧹 Для Native в справочнике «Внешние компоненты»: загрузите новый архив в ту же запись — программа обновит версию, а клиенты получат её при следующем подключении.