Native API 1С: что это и как создать внешнюю компоненту

Native API 1С — это технология создания внешних компонент, позволяющая расширять возможности платформы «1С:Предприятие» с помощью библиотек, написанных на языке C++. Через такие компоненты встроенный язык 1С получает доступ к функциям, которых нет в платформе: работе с оборудованием, низкоуровневым API операционной системы, сторонними библиотеками и вычислительно тяжёлыми алгоритмами.

Технология основана на кроссплатформенном интерфейсе, опубликованном фирмой «1С». Компонента компилируется в динамическую библиотеку — DLL для Windows, SO для Linux, bundle для macOS — и подключается к платформе методом ПодключитьВнешнююКомпоненту(). После подключения её методы и свойства становятся доступны из кода на встроенном языке так же, как объекты самой платформы.

Native API чаще всего применяют там, где стандартных средств недостаточно: драйверы торгового оборудования, криптографические операции, работа с COM-портами, интеграция с нестандартными протоколами обмена, ускорение расчётов. Понимание устройства этой технологии нужно и тем, кто только подключает готовые компоненты, — например, компоненту сканирования штрихкодов или печати этикеток, поставляемую в составе типовых конфигураций.

Чем Native API отличается от других способов расширения платформы

У разработчика 1С есть несколько механизмов выхода за пределы встроенного языка, и Native API — только один из них. Выбор зависит от задачи, целевых платформ и требований к поддержке.

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

Способы расширения платформы

Native API

Кроссплатформенность, работа на сервере и мобильной платформе. Требует знания C++ и аккуратной сборки под каждую ОС.

COM-компоненты

Проще в разработке, но только Windows и только клиентские приложения. Не работают на сервере Linux и в веб-клиенте.

HTTP-сервисы и внешние программы

Логика выносится в отдельный сервис. Нет ограничений по языку, но нужен сетевой обмен и отдельное развёртывание.

Ключевое практическое отличие: Native API — единственный вариант, если компонента должна работать на сервере под Linux, на мобильной платформе или в веб-клиенте. Если же задача ограничена Windows-рабочими местами, иногда рациональнее выбрать COM и сэкономить время разработки.

Как устроена внешняя компонента Native API

Компонента реализует несколько обязательных интерфейсов, описанных в заголовочных файлах из поставки технологии. Главные из них — IComponentBase (регистрация свойств и методов, их вызов) и IInitDoneBase (инициализация, получение указателя на интерфейсы платформы, регистрация имени компоненты).

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

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

Что понадобится для разработки компоненты

Минимальный набор: компилятор C++ (Visual Studio для Windows, GCC/Clang для Linux и macOS), заголовочные файлы Native API из поставки технологии и шаблон проекта. Фирма «1С» публикует пример компоненты с исходным кодом, который удобно взять за основу — в нём уже реализованы все обязательные интерфейсы и корректная работа с памятью.

Типовой порядок создания компоненты выглядит так:

1. 1
   Скопируйте шаблонный проект Native API и переименуйте компоненту, задайте её программное имя (латиница, без пробелов)
2. 2
   Зарегистрируйте методы и свойства в функциях RegisterMethodAs / RegisterProp — имена задаются в двух языковых вариантах при необходимости
3. 3
   Реализуйте логику методов, корректно заполняя tVariant и освобождая память через IMemoryManager
4. 4
   Соберите библиотеки под все целевые платформы и разрядности (x86, x64, ARM при необходимости)
5. 5
   Упакуйте библиотеки в ZIP-архив с файлом manifest.xml, где перечислены компоненты для каждой платформы
6. 6
   Поместите архив в макет конфигурации с типом «Двоичные данные» и подключите из кода

Файл manifest.xml внутри архива описывает, какая библиотека соответствует какой платформе. Платформа 1С при подключении сама выбирает подходящий файл. Ошибка в манифесте — типичная причина сообщения «Внешняя компонента не найдена» на конкретной ОС при работающей компоненте на другой.

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

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

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

Компонента = Новый("AddIn.MyComponent.MyObject");
Результат = Компонента.ВыполнитьДействие(Параметр);

Второй параметр ПодключитьВнешнююКомпоненту — псевдоним, под которым компонента регистрируется в текущем сеансе. Объект создаётся конструкцией Новый("AddIn.Псевдоним.ИмяОбъекта"), где имя объекта совпадает с именем, зарегистрированным компонентой при инициализации.

Контрольные точки

Как проверить, что компонента подключилась

Возврат ПодключитьВнешнююКомпоненту

Норма

Возвращает Истина

Тревожный признак

Возвращает Ложь — проверьте макет, манифест и разрядность платформы

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

Норма

Новый("AddIn...") выполняется без исключения

Тревожный признак

Ошибка «Тип не определён» — неверный псевдоним или имя объекта

Вызов метода

Норма

Метод возвращает ожидаемое значение

Тревожный признак

Аварийное завершение клиента — ошибка работы с памятью в коде компоненты

На сервере 1С компонента подключается тем же кодом, но библиотека должна соответствовать ОС и разрядности сервера. Учитывайте: код, исполняемый на сервере, не может использовать компоненты, собранные только для Windows-клиента, если сервер работает под Linux.

Где Native API применяют на практике

Наиболее массовый сценарий — драйверы торгового оборудования. Сканеры штрихкодов, принтеры этикеток, весы, терминалы сбора данных подключаются к 1С через внешние компоненты, написанные по Native API или COM. Типовые конфигурации поставляются с набором таких компонент в макетах.

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

Третий сценарий — производительность. Тяжёлые вычисления (обработка изображений, парсинг больших файлов, математические расчёты) на C++ выполняются заметно быстрее, чем на встроенном языке. Перед выбором этого пути стоит честно измерить узкое место: часто проблема решается оптимизацией запросов или выносом операции на сервер, без написания компоненты.

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

Типичные ошибки и ограничения технологии

Главный источник проблем — некорректная работа с памятью в коде C++. Строки, возвращаемые платформе, должны выделяться через IMemoryManager, а структура tVariant — корректно инициализироваться и очищаться. Ошибка здесь проявляется не сразу, а как случайные падения клиентского приложения, которые сложно диагностировать.

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

Как выбрать: Native API, COM или внешний сервис

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

Маршрут решения

Как выбрать подход

Код должен работать на сервере Linux, в веб-клиенте или на мобильной платформеВыбирайте Native API — другие варианты компонент там недоступны

Нужна только Windows и клиентские приложения, сроки сжатыеРассмотрите COM-компоненту — разработка проще, отладка удобнее

Логика объёмная, меняется часто и не требует мгновенного откликаВынесите её во внешний HTTP-сервис — проще сопровождать и обновлять без переподключения компонент

Нужен доступ к оборудованию с рабочего места пользователяВнешняя компонента на клиенте (Native API или COM) — сервис не имеет доступа к локальным портам

Компромиссный вариант — гибрид: небольшая компонента Native API решает задачу доступа к оборудованию или системным API, а сложная бизнес-логика остаётся в конфигурации или внешнем сервисе. Так компонента получается маленькой, стабильной и редко требующей обновлений.

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

Можно ли писать компоненту Native API не на C++, а на C# или другом языке?

Напрямую — нет: интерфейс Native API определён на уровне C++ и бинарного формата библиотеки. На практике делают тонкую обёртку на C++, которая вызывает код на другом языке (например, через C++/CLI для .NET или через встраивание интерпретатора). Это усложняет сборку и отладку, поэтому такой подход оправдан только при необходимости переиспользовать готовую библиотеку.

Почему компонента подключается на одном компьютере, но не на другом?

Чаще всего причины три: несовпадение разрядности (32-разрядный клиент и 64-разрядная библиотека), отсутствие записи для нужной ОС в manifest.xml архива либо отсутствие системных зависимостей (например, библиотек Visual C++ Redistributable на Windows). Проверяйте разрядность клиента 1С и зависимости DLL через стандартные средства ОС.

Нужно ли подписывать внешнюю компоненту для работы в веб-клиенте?

Для веб-клиента компонента доставляется через механизм расширения работы с файлами и внешних компонент, и браузеры предъявляют требования к безопасности таких загрузок. Конкретные требования зависят от браузера и версии платформы; на корпоративных рабочих местах часто дополнительно требуется настройка доверия. Тестируйте подключение именно в целевых браузерах пользователей.

Можно ли отладить компоненту, подключённую к 1С?

Да. Скомпилируйте компоненту в отладочной конфигурации, запустите отладчик (Visual Studio или GDB), присоединитесь к процессу клиентского приложения или сервера 1С и поставьте точки останова в коде компоненты. Для удобства полезно предусмотреть в компоненте метод вывода диагностической информации и вести журнал вызовов.

Что происходит с компонентой при обновлении конфигурации?

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

Чем Native API отличается от технологии создания внешних компонент версии 2.x и 3.x?

Это версии одного интерфейса: более новые редакции добавляют возможности (например, асинхронные вызовы и расширенную работу с типами), сохраняя обратную совместимость. Компонента, написанная под старую версию интерфейса, продолжает работать, но для использования новых функций платформы её нужно пересобрать с актуальными заголовочными файлами.