Как написать компоненту для 1С

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

Прежде чем писать собственную компоненту, проверьте, действительно ли она нужна. Многие задачи решаются штатными средствами: HTTP-запросами, COM-объектами, веб-сервисами, расширениями конфигурации или внешними обработками. Компонента оправдана, когда нужна высокая производительность, прямой доступ к драйверу устройства или вызов готовой нативной библиотеки. Ошибка на этапе выбора технологии оборачивается неделями лишней работы и проблемами с сопровождением.

Ниже разобран полный цикл: от подготовки среды разработки до подключения готовой компоненты в конфигурации и проверки её работы. Материал ориентирован на разработчика, знакомого со встроенным языком 1С и базовыми навыками C++.

Что такое внешняя компонента и когда она нужна

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

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

Подготовка среды разработки

Для работы потребуется комплект разработки внешних компонент — он доступен на портале 1С в разделе загрузок и содержит заголовочные файлы, документацию и пример шаблона проекта. Дополнительно нужен компилятор C++: Visual Studio под Windows, GCC или Clang под Linux. Удобно сразу настроить CMake, чтобы собирать библиотеку под несколько платформ из одного проекта.

Проверьте разрядность целевой платформы. 64-разрядный клиент 1С загружает только 64-разрядную библиотеку, 32-разрядный — соответственно 32-разрядную. Если в компании используются оба варианта, компоненту нужно собрать в двух версиях и упаковать их в один архив с правильными именами файлов.

1. 1
   Скачайте комплект разработки внешних компонент с портала 1С
2. 2
   Установите компилятор C++ и CMake
3. 3
   Скопируйте шаблонный проект в рабочий каталог
4. 4
   Соберите шаблон без изменений и убедитесь, что он компилируется
5. 5
   Подключите собранную тестовую библиотеку в пустой базе 1С

Структура проекта компоненты

Шаблонный проект состоит из нескольких обязательных частей. Точка входа — функция GetClassObjectFactory, через которую платформа получает фабрику классов. Класс компоненты наследует базовый класс из комплекта и переопределяет методы регистрации: RegisterExtensionAs (имя компоненты), RegisterPropAs (свойства), RegisterMethodAs (методы), а также обработчики вызовов CallAsProc и CallAsFunc.

Имя, заданное в RegisterExtensionAs, — это то имя, под которым объект будет создан в коде 1С через конструктор Новый("AddIn.ИмяКомпоненты"). Выбирайте короткое уникальное имя латиницей: при конфликте имён двух компонент в одной информационной базе возникнут ошибки подключения.

long CMyComponent::RegisterExtensionAs(WCHAR_T** wsExtensionName)
{
    const wchar_t* wsExtension = L"MyComponent";
    return convToShortWchar(wsExtensionName, wsExtension);
}

Реализация методов и свойств

Каждый метод компоненты регистрируется с именем, числом параметров и признаком наличия возвращаемого значения. В обработчике вызова параметры приходят в виде массива структур tVariant — универсального контейнера, который хранит строки, числа, булевы значения и даты. Перед использованием параметра проверяйте его тип: платформа не гарантирует, что из кода 1С передали именно то, что вы ожидали.

Свойства реализуются через пары методов Get/Set по индексу свойства. Для обмена большими объёмами данных удобно передавать строки (например, XML или JSON) или двоичные данные — это проще и надёжнее, чем многочисленные вызовы отдельных методов.

Сборка и упаковка компоненты

После компиляции библиотеки упаковываются в ZIP-архив с манифестом manifest.xml. В манифесте перечисляются файлы для каждой платформы и разрядности: Windows x86, Windows x64, Linux и другие. Платформа при подключении сама выбирает подходящий файл из архива, поэтому ошибки в манифесте проявляются как «компонента не найдена» на части рабочих мест.

Готовый архив загружается в конфигурацию как макет с типом «Двоичные данные» — обычно в общие макеты. Это позволяет хранить компоненту внутри информационной базы и разворачивать её на любых рабочих местах без ручного копирования файлов.

Подключение компоненты в конфигурации

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

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

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

Типичные ошибки и их устранение

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

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