Подключение внешней компоненты в 1С 8.3: от файла до вызова методов

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

Ниже — порядок действий для платформы 8.3 с интерфейсом «Такси»: как разложить файлы, куда положить компоненту, как зарегистрировать COM-вариант и как вызвать её методы из встроенного языка. Инструкция общая для платформы и не зависит от конфигурации — подключение работает одинаково в Бухгалтерии, ЗУП, УТ и в собственных разработках.

Native или COM: какой тип компоненты выбрать

В 8.3 есть две технологии внешних компонент, и способ подключения у них разный.

Native API — современный стандарт. Такая компонента работает на всех платформах, где запускается 1С: Windows, Linux, macOS, причём в тонком клиенте, веб-клиенте и на стороне сервера. Регистрировать её в операционной системе не нужно — платформа загружает файл напрямую. Все новые компоненты (в том числе драйверы оборудования от 1С) делают именно по Native API.

COM/ActiveX — старая технология. Работает только под Windows и только в толстом клиенте либо на Windows-сервере. Перед использованием библиотеку нужно зарегистрировать в системе через regsvr32. COM-компоненту берут, когда нет Native-сборки, а переписывать её некому.

Разрядность компоненты обязана совпадать с разрядностью той программы, которая её грузит. Серверная 1С и большинство клиентов сегодня 64-битные, значит и компонента нужна x64. Если подключение идёт на сервере — смотрите разрядность rphost, а не клиента.

Что должно быть в комплекте компоненты

Прежде чем подключать, разберитесь, что вам передал разработчик. Правильно собранная Native-компонента — это, как правило, ZIP-архив, внутри которого:

• 📄 MANIFEST.xml — описание: имя компоненты, список бинарных файлов и платформы, под которые они собраны.
• ⚙️ бинарные файлы: .dll для Windows, .so для Linux, .dylib для macOS — по одному на каждую разрядность и ОС.
• иногда — отдельные файлы для разных платформ, перечисленные в манифесте.

Именно этот архив целиком загружается в макет конфигурации. Распаковывать его вручную не нужно — платформа читает MANIFEST.xml сама и выбирает подходящий бинарник под текущую ОС и разрядность.

COM-компонента выглядит проще: это одна .dll (реже .ocx), которую регистрируют в системе. Манифеста у неё нет.

Проверьте, под какую ОС и разрядность собрана компонента. Эти данные есть в манифесте Native-архива; для COM — уточняйте у поставщика. Несовпадение разрядности — причина номер один, по которой компонента «не подключается» без внятной ошибки.

Куда положить компоненту: макет, файл или адрес

У функции подключения первый параметр — местоположение. Вариантов три.

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

1. Откройте конфигуратор, в дереве метаданных найдите ветку Общие → Общие макеты.
2. Добавьте новый общий макет, тип макета — Двоичные данные.
3. В поле выбора файла укажите ZIP-архив компоненты и сохраните.
4. Запомните имя макета — по нему вы будете обращаться к компоненте: "ОбщийМакет.ИмяВашегоМакета".

Внешним файлом на диске — удобно при отладке или когда компонента меняется чаще, чем конфигурация. В местоположении указывают полный путь к файлу, например "C:\addin\scanner.dll". Минус — файл надо разложить на каждой машине, где работает компонента.

По адресу в интернете — компонента скачивается с URL. Применяют редко, в основном для веб-клиента, когда архив лежит на сервере приложения.

Для тиражного решения выбирайте макет: не придётся ходить по рабочим местам и следить за путями.

Подключение в коде: пошагово

Подключение выполняет глобальная функция:

ПодключитьВнешнююКомпоненту(<Местоположение>, <Имя>, <Тип>)

• Местоположение — имя макета, путь к файлу или URL (см. выше).
• Имя — символическое имя, под которым компонента регистрируется в текущем сеансе. Его вы придумываете сами, латиницей.
• Тип — ТипВнешнейКомпоненты.Native, .COM или .Любой.

Функция возвращает Истина при успехе и Ложь, если подключить не удалось. Результат нужно обязательно проверять.

Подключение из макета для толстого и тонкого клиента :

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

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

Веб-клиент: сначала установка

В веб-клиенте просто подключить компоненту нельзя — её сначала нужно установить в браузер пользователя. Для этого есть отдельная процедура НачатьУстановкуВнешнейКомпоненты(), а само подключение в веб-клиенте делают асинхронно через НачатьПодключениеВнешнейКомпоненты() с описанием оповещения.

Порядок для веб-клиента:

1. У пользователя должно быть установлено расширение работы 1С для его браузера.
2. Вызовите установку компоненты — платформа предложит пользователю подтвердить.
3. После успешной установки подключите компоненту асинхронно.

Создание объекта и вызов методов

Подключение только регистрирует компоненту. Чтобы работать с ней, создайте экземпляр через Новый с префиксом AddIn:

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

    Устройство = Новый("AddIn.Scanner.Driver");
    // Scanner — имя из подключения, Driver — класс внутри компоненты

    Устройство.Открыть();
    Штрихкод = Устройство.ПоследнийКод();
    Устройство.Закрыть();

КонецЕсли;

Имя класса (Driver в примере) задаёт разработчик компоненты — оно указано в её документации. Если компонента содержит один класс, иногда допустимо обращение короче: Новый("AddIn.Scanner"). Но надёжнее всегда писать полное имя с классом.

Набор методов, свойств и событий у каждой компоненты свой. Их список берут из документации поставщика: придумывать имена методов нельзя — несуществующий метод вызовет ошибку во время выполнения. Если документации нет, а компонента поддерживает события, их обрабатывают через процедуру-обработчик ОбработкаВнешнегоСобытия().

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

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

Этот раздел нужен только для COM/ActiveX — Native-компоненту регистрировать не надо.

COM-библиотеку регистрируют в системе утилитой regsvr32 от имени администратора:

regsvr32 "C:\addin\mycom.dll"

Ключевой момент — разрядность. Если 1С 64-битная, а компонента 32-битная (или наоборот), обычный regsvr32 зарегистрирует её «не туда». Для 32-битной библиотеки на 64-битной Windows используйте regsvr32 из SysWOW64:

C:\Windows\SysWOW64\regsvr32.exe "C:\addin\mycom.dll"

После регистрации подключайте с типом COM:

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

Здесь местоположение — это ProgID из реестра (например "AddIn.MyCom"), а не путь к файлу. ProgID указан в документации компоненты.

Частые ошибки подключения и их причины

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

Ещё одна неочевидная причина — кэш клиента. Native-компонента кэшируется на клиентской машине, и старая версия может «залипнуть» после обновления макета. Если вы обновили компоненту, а поведение не изменилось — очистите кэш клиента (запуск с ключом /ClearCache или удаление каталога кэша).

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

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

Несколько правил:

• 🔒 Берите компоненты только от проверенных поставщиков. Для оборудования — это драйверы из состава библиотеки подключаемого оборудования 1С.
• 🧩 На сервере контролируйте доступ через профили безопасности. По умолчанию профиль запрещает внешние компоненты — разрешать нужно явно, перечислив конкретные компоненты.
• 🧪 Новую компоненту сначала проверьте в тестовой базе, а не сразу в рабочей.

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

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

Какие внешние компоненты встречаются на практике

Чаще всего внешние компоненты появляются там, где 1С работает с оборудованием или с внешним кодом, которого нет во встроенном языке.

• 🔌 Торговое оборудование. Сканеры штрихкодов, фискальные регистраторы, эквайринговые терминалы, весы с печатью этикеток, дисплеи покупателя — все они подключаются через драйверы-компоненты. В типовых конфигурациях для этого есть библиотека подключаемого оборудования: драйверы там уже оформлены как внешние компоненты, и подключение идёт через настройку оборудования, а не вручную кодом.
• 🔐 Криптография и подписи. Отдельные решения по работе с криптопровайдерами и носителями ключей поставляют как внешние компоненты, когда стандартных средств платформы не хватает.
• 📡 Обмен и интеграции. Компоненты для работы с нестандартными протоколами, устройствами сбора данных (ТСД), специфическими файловыми форматами.

Логика подключения у всех одинаковая: архив в макет (или регистрация COM), подключение функцией, создание объекта через Новый("AddIn.…"), вызов методов из документации. Разница только в именах классов и методов, которые задаёт поставщик.

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

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