Как правильно установить и подключить внешнюю компоненту Native API в 1С

← На главную

При разработке и интеграции собственных внешних компонент (Native API) разработчики часто сталкиваются с ошибкой «Установка внешней компоненты не выполнена». Эта ошибка обычно возникает на этапе вызова метода УстановитьВнешнююКомпоненту, когда в качестве параметра передается обычный путь к файлу на локальном диске. Разберем детально, почему возникает данное поведение платформы «1С:Предприятие» и как правильно организовать подключение как на этапе разработки, так и при промышленной эксплуатации.

В чем причина ошибки при вызове метода УстановитьВнешнююКомпоненту

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

Метод УстановитьВнешнююКомпоненту не предназначен для работы с прямыми путями файловой системы (например, D:\Phone-Native.dll или D:\Phone-Native.zip). В качестве параметра он ожидает:

Полное имя макета конфигурации, содержащего ZIP-архив с компонентой (например, "ОбщийМакет.ДрайверОборудования").
Навигационную ссылку на двоичные данные ZIP-архива во временном хранилище или в информационной базе (полученную через ПолучитьНавигационнуюСсылку()).

Если передать в метод строку с путем к локальному диску, платформа не сможет распознать ресурс и вернет ошибку установки.

Вариант 1. Прямое подключение DLL-файла с диска при разработке и отладке

Если вы находитесь в процессе компиляции и отладки исходного кода C++, упаковывать библиотеку в ZIP-архив каждый раз неудобно. В этом случае вызывать УстановитьВнешнююКомпоненту вообще не нужно. Платформа умеет подключать скомпилированную DLL напрямую с локального диска.

Посмотрим на пример правильного подключения файла библиотеки:


АдресВнешнейКомпоненты = "D:\Phone-Native.dll";
Результат = ПодключитьВнешнююКомпоненту(АдресВнешнейКомпоненты, "Datum", ТипВнешнейКомпоненты.Native);

Если Результат Тогда
    // Создаем экземпляр объекта компоненты
    ОбъектВК = Новый("AddIn.Datum.PhoneClass");
Иначе
    ВызватьИсключение "Не удалось подключить внешнюю компоненту!";
КонецЕсли;

Обратите внимание на инициализацию объекта: первым сегментом имени выступает префикс AddIn, вторым — символическое имя подключения (в примере Datum), а третьим — имя класса, зарегистрированное в исходном коде библиотеки в методе GetClassNames.

Вариант 2. Распространение через общий макет конфигурации в ZIP-архиве

Рассмотрим порядок действий для штатного встраивания компоненты в конфигурацию «1С:Предприятия». Чтобы компонента автоматически доставлялась на рабочие места пользователей тонкого клиента, выполним следующие шаги:

Подготовка файла манифеста MANIFEST.xml: создадим в текстовом редакторе файл манифеста, описывающий разрядность и операционную систему для каждой сборки библиотеки.


<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle">
    <component os="Windows" path="Phone-Native-32.dll" type="native" arch="i386"/>
    <component os="Windows" path="Phone-Native-64.dll" type="native" arch="x86_64"/>
</bundle>

Упаковка архива: поместим файл MANIFEST.xml и скомпилированные DLL-файлы нужных разрядностей в корень ZIP-архива (без создания лишних вложенных папок).
Добавление в конфигурацию: создадим ОбщийМакет с типом Двоичные данные и загрузим туда подготовленный ZIP-архив.
Программная установка и подключение: вызовем поочередно методы установки и подключения.

Разберем программный код для установки и подключения компоненты из макета:


ИмяМакета = "ОбщийМакет.AddInPhoneNative";
СимволическоеИмя = "PhoneDriver";

// 1. Распаковываем компоненту в кэш клиента
Установлено = УстановитьВнешнююКомпоненту(ИмяМакета);

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

Использование современных асинхронных методов

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


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

Чек-лист частых технических проблем при подключении Native API

Если даже при корректном синтаксисе методов 1С функция ПодключитьВнешнююКомпоненту возвращает Ложь, проверим следующие критические моменты:

Разрядность клиента 1С и DLL: разрядность сборки библиотеки (x86 или x64) должна строго совпадать с разрядностью исполняемого файла клиента 1С (1cv8c.exe), а не с общей разрядностью Windows.
Зависимости от Microsoft Visual C++ Runtime: если библиотека собрана с динамической линковкой к CRT, на клиентском ПК должны быть установлены соответствующие пакеты Visual C++ Redistributable. Для исключения внешних зависимостей рекомендуется компилировать код со статическим связыванием рантайма (параметр /MT в Visual Studio).
Экспорт служебных функций: в C++ коде все обязательные функции интерфейса платформы (GetClassObject, DestroyObject, GetClassNames, SetPlatformCapabilities) должны быть объявлены как extern "C" и экспортированы без искажения имен через DEF-файл или __declspec(dllexport).