Подключение внешних компонент, расширений и обработок к 1С:Предприятию 8.3

Интегрировать модуль в 1С можно тремя способами. Готовую библиотеку (DLL или SO) добавляют как внешнюю компоненту: кладут её в общий макет и подключают методом ПодключитьВнешнююКомпоненту(). Собственный код на встроенном языке оформляют расширением конфигурации (.cfe). Разовый инструмент выносят во внешнюю обработку (.epf).

Способ выбирают до того, как открыть Конфигуратор . От выбора зависит, придётся ли снимать конфигурацию с поддержки, как пройдёт обновление типовой и какие права нужны пользователю. Всё ниже относится к платформе 8.3 и типовым конфигурациям на БСП: Бухгалтерии 3.0, ЗУП 3.1, УТ 11.

С чего начать: какой способ интеграции модуля выбрать

Слово «модуль» в 1С означает разное. Сначала разберитесь, что именно у вас на руках.

Перед началом проверьте четыре вещи:

• 🧩 Разрядность. Если компонента 32-битная, а клиент или сервер 1С 64-битный, библиотека не загрузится. Нужна сборка под каждую платформу.
• 🖥️ Где будет работать код. На клиенте, на сервере или там и там. Компонента для сервера под Linux должна иметь сборку .so.
• 🔒 Режим конфигурации. Типовая на поддержке без возможности изменения? Тогда только расширение или внешние обработки.
• 💾 Копия базы. Выгрузите .dt через Администрирование → Выгрузить информационную базу в Конфигураторе. Дальше будем менять структуру.

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

Внешняя компонента — это библиотека, написанная на C++ (технология Native API) или COM-сервер. Встроенный язык 1С видит её как объект с методами и свойствами.

Шаг 1. Подготовьте архив компоненты

Поставщик обычно отдаёт ZIP-архив. Внутри лежат библиотеки под разные ОС и разрядности и файл MANIFEST.XML. Манифест сообщает платформе, какую библиотеку брать на Windows x86, Windows x86-64, Linux и так далее.

Если пришла одна DLL без манифеста, попросите у поставщика полный пакет. Без манифеста компонента подключится только под ту платформу, под которую собрана.

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

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

Если конфигурация на поддержке без права изменения, создайте этот макет не в основной конфигурации, а в расширении. Так тоже работает.

Шаг 3. Сохраните и обновите базу

Нажмите F7 или выберите Конфигурация → Обновить конфигурацию базы данных. Добавление макета не меняет структуру таблиц, поэтому обновление пройдёт быстро. Но если в том же сеансе вы меняли реквизиты, потребуется монопольный доступ.

Альтернатива: компонента из файла

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

Интеграция модуля через расширение конфигурации

Расширение — отдельная маленькая конфигурация, которая накладывается на основную. В ней можно создавать свои объекты и заимствовать типовые: общие модули, формы, документы. Механизм появился в платформе 8.3.6 и с тех пор сильно развился.

Создание расширения в Конфигураторе

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

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

Как изменить поведение типовой процедуры

Чтобы вмешаться в типовой общий модуль, заимствуйте его: правый щелчок по объекту в основной конфигурации → «Добавить в расширение». Затем в модуле расширения создайте обработчик с аннотацией:

Загрузка готового .cfe в пользовательском режиме

Если расширение прислал разработчик, Конфигуратор не нужен. В типовых конфигурациях на БСП откройте Администрирование → Печатные формы, отчеты и обработки → Расширения и добавьте файл. Альтернатива в любой конфигурации — Все функции → Стандартные → Управление расширениями конфигурации.

В Конфигураторе загрузка файла .cfe и обновление конфигурации базы данных — два отдельных шага. Без второго расширение не заработает.

Внешняя обработка как подключаемый модуль

Когда доработка не должна жить в базе постоянно, её выносят в файл .epf. Это удобно для выгрузок, загрузок из Excel и разовых исправлений данных.

Есть два варианта работы:

• 📂 Открыть разово через меню «Файл → Открыть». Подходит для администратора и разовой задачи.
• 🗂️ Зарегистрировать в справочнике Администрирование → Печатные формы, отчеты и обработки → Дополнительные отчеты и обработки. Тогда обработка появится в нужном разделе или в форме документа как команда печати или заполнения.

Регистрация возможна, только если в модуле объекта обработки есть экспортная функция СведенияОВнешнейОбработке(). Её пишет разработчик по правилам БСП. Обработку без этой функции можно только открыть через меню.

Из кода внешнюю обработку подключают на сервере так:

АдресВХранилище = ПоместитьВоВременноеХранилище(ДвоичныеДанныеФайла);
ИмяОбработки = ВнешниеОбработки.Подключить(АдресВХранилище, , Ложь);
Обработка = ВнешниеОбработки.Создать(ИмяОбработки, Ложь);
Результат = Обработка.ВыполнитьВыгрузку();

Третий параметр Ложь у Подключить() отключает безопасный режим. Используйте его, только если доверяете автору файла.

Вызов методов модуля из кода 1С

После подключения компонента превращается в объект встроенного языка. Имя типа складывается так: AddIn.<ИмяИзПодключения>.<ИмяКлассаИзКомпоненты>. Имя класса берётся из документации поставщика.

Синхронный вызов на сервере

&НаСервере
Функция ПрочитатьВесСВесов()

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

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

	Весы = Новый("AddIn.Vesy.Main");
	Весы.Порт = "COM3";
	Возврат Весы.ПолучитьВес();

КонецФункции

Методы и свойства (Порт, ПолучитьВес) у каждой компоненты свои. Их список даёт поставщик, обычно на русском и английском языке .

Подключение на клиенте

На клиенте компоненту сначала устанавливают на компьютер пользователя, потом подключают. Для веб-клиента и тонкого клиента в современных платформах применяют асинхронные методы:

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

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

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

	Если Подключено Тогда
		Сканер = Новый("AddIn.Scanner.Main");
	КонецЕсли;

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

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

Вызов методов своего модуля из расширения

С общим модулем расширения всё проще. Он виден как обычный общий модуль: мр_ИнтеграцияСервер.ОтправитьЗаказ(Ссылка). Метод должен быть помечен Экспорт. Чтобы вызвать серверный метод с клиента, у модуля нужен флажок «Вызов сервера».

Отладка и диагностика ошибок подключения

Расширения отлаживаются так же, как основная конфигурация. Откройте конфигурацию расширения, поставьте точку останова (F9) и запустите Отладка → Начать отладку → 1С:Предприятие. Для серверного кода на клиент-серверной базе включите отладку на сервере 1С. Без этого точки останова в серверных процедурах не сработают.

С компонентой отладчик 1С доходит только до вызова её метода. Внутрь библиотеки он не заходит. Поэтому оборачивайте вызовы в Попытка … Исключение и пишите ОписаниеОшибки() в журнал регистрации через ЗаписьЖурналаРегистрации().

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

Безопасность и ограничения при интеграции

Любой внешний модуль выполняет код с правами процесса 1С. Платформа даёт несколько уровней защиты.

• 🛡️ Безопасный режим. В нём недоступны работа с файлами, COM-объекты, внешние компоненты и привилегированный режим. Расширения по умолчанию загружаются в безопасном режиме. Снимать флажок — только для проверенных расширений.
• 🧾 Профили безопасности. На серверной базе администратор кластера задаёт профиль и перечисляет, какие компоненты, адреса и каталоги разрешены. Типовые конфигурации на БСП умеют сами запрашивать нужные разрешения.
• ⚠️ Защита от опасных действий. Включается в свойствах пользователя. При открытии внешней обработки или загрузке расширения платформа показывает предупреждение. Не отключайте её массово, чтобы «не мешала».
• 👤 Права. Загружать расширения и регистрировать дополнительные обработки должен администратор, а не каждый пользователь.

Отдельно о COM-объектах. Они работают только в Windows, требуют регистрации библиотеки в системе (regsvr32 имя.dll из командной строки администратора) и не переносятся вместе с базой. При переезде на Linux-сервер такую интеграцию придётся переделывать на Native API или на HTTP-обмен.

Ограничения расширений, которые чаще всего мешают:

1. В расширении нельзя удалить объект основной конфигурации и убрать реквизит у типового документа.
2. Добавленные в расширение реквизиты типовых объектов хранятся в отдельных таблицах, и при неосторожной доработке это сказывается на скорости запросов.
3. Если в базе несколько расширений заимствуют один и тот же метод, порядок срабатывания обработчиков зависит от порядка расширений в списке.

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