Разработка внешней компоненты для 1С:Предприятие

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

Проще всего, на мой взгляд, за основу взять пример для 5-й Дельфи, поставляемый на диске ИТС. Недостаток этого примера, являющийся, как ни странно, следствием достоинства - пример весьма мощный и демонстрирует практически все возможности внешних компонент. Поэтому разобраться в нем было не так-то просто...

Под рукой (то бишь установленные) у меня были Delphi 7 и Borland Developer Studio 2006. Из-за того, что по документации необходимо в опциях компиляторах устанавливать генерацию .OBJ-файлов (а не .DCU), в 2006 проект компилироваться не хотел. Поэтому пришлось использовать 7-ю версию Delphi. Однако и с этой версией были небольшие проблемы: в примере используется идентификатор Unassigned, который 7-й Delphi не распознал.

Итак, к нашему примеру (речь идет о 1CIts\EXE\VNCOMP\V80\DELPHI5\SAMPLE). Проект состоит из модулей AddInLib (очень полезная библиотека с описанием всех интерфейсов), AddInObj (основной модуль) и PropPage (страница свойств компоненты). Наибольший интерес, конечно же, представляет AddInObj. Собственно, прокомментировать этот модуль я и хотел в этой статье, потому что в нем, в общем-то, заключается вся суть внешней компоненты для 1С.

Первое, что нас интересует - это секция resourcestring. В примере перечисляются названия свойств и методов внешней компоненты, причем как на русском, так и английском языке. Я думаю, нет причин поступать как-то иначе при разработке собственной компоненты, все довольно удобно получается в итоге.

В примере объявлена всего одна константа, но очень важная: это GUID нашей компоненты. Разумеется, ее сразу же необходимо заменить на свою (в Дельфи сгенерировать GUID можно комбинацией Ctrl+Shift+G, квадратные скобки можно убрать).

Далее идет секция объявления типов. В примере решили объявить перечисления TProperties и TMethods. В принципе, обойтись можно и без них, однако все-равно надо как-то запоминать, какой номер что означает, так что лучше сделать по аналогии. Сначала меня смутило наличие неких LastProp и LastMethod. Оказалось, что это "заглушки", благодаря которым легко и непринужденно возвращается количество свойств и методов (plMethods := Integer(LastMethod) в методе GetNMethods, например).

Следующим идет собственно описание класса компоненты. В примере он поддерживает практически все возможные интерфейсы, однако без некоторых интерфейсов можно прекрасно обойтись, например ISpecifyPropertyPages и IPropertyLink нужны только если применяется страница свойств.

boolIsEnabled и Timer особого интереса не представляют - это просто члены класса. А вот дальше идут переменные, предназначенные для взаимодействия с 1С:Предприятием: pConnect (связь с Предприятием в целом), pErrorLog (протоколирование ошибок, надо полагать ), pEvent (возможность вызывать обработчик события в 1С:Предприятии), pProfile (чтобы сохранять/загружать настройки), pStatusLine (для работы со строкой состояния). Так что можно этим всем пользоваться, однако если компонента простая, можно обойтись и без них.

Load/Save properties также можно убрать, если не используются свойства, которые еще вдобавок в профиле необходимо хранить.

А вот без последующего большого набора методов нам не обойтись (разве что GetPages не потребуется, если не используются страницы свойств): реализация интерфейса InitDone обязательна, без LanguageExtender'а какого-то особого смысла во внешней компоненте тоже нет, согласитесь , IDispatch также обязателен к реализации. IPropertyLink да, необязателен, как мы уже раньше говорили, OnMyTimer - обработчик события таймера в примере, похоже, что он точно не понадобится

Теперь как же все-таки работает LanguageExtender? Меня это, кстати, интересовало очень давно, особенно вызов "русских" методов. Оказывается, все довольно просто: есть метод (в интерфейсе), который определяет номер метода/свойства по его наименованию, а собственно выполнение происходит опять же через вызов интерфейсной процедуры, в которую, в частности, передается номер метода.

Благодаря примеру, наша жизнь, как разработчика, упрощена для предела: написана процедура TermString, благодаря которой удобно работать с русскими и английскими наименованиями свойств и методов (помните resourcestring?). Get/PutNParam - работа с массивами параметров (для реализации тех процедур и функций, которым требуются параметры).

Процедуру Init можно почистить, если какие-то из возможностей не используются. Вообще говоря, она должна вернуть S_OK, если все в порядке, или E_FAIL в противном случае. Все остальное, в принципе, на совести разработчика Done - обратная операция. То есть своего рода OnCreate и OnClose

GetInfo должен вернуть некоторую информацию о компоненте. Теоретически можно возвращать целый массив всяких параметров, но подразумевается, что нулевым параметром передается версия компоненты. Что в примере и сделано, менять, во всяком случае по началу, особого смысла нет. Лично мне все же не совсем понятно, подразумевается ли тут версия с точки зрения разработчика компоненты, или же с точки зрения 1С:Предприятия (1-я или 2-я версия компонент; вторая версия поддерживает больше возможностей).

Далее важный метод - RegisterExtensionAs. Процитирую документацию: "Для использования этого расширения необходимо вызвать функцию СоздатьОбъект (Новый в 1C:Предприятии 8.0), передав ей строку вида "AddIn.<ИмяРасширения>", где <ИмяРасширения> возвращается методом этого интерфейса. Затем можно использовать созданный объект, вызывая его методы и свойства." Вот такой волшебный метод В примере компоненту назвали 'AddInExtension', лучше всего это, конечно, изменить на нечто более соответствующее действительности.

GetNProps возвращает количество свойств компоненты (если вы воспользовались предложенной технологией - перечисление с "затычкой" на конце, то все будет замечательно работать "на автомате"). FindProp - определение номера свойства по строке. В общем-то, нетрудно переделать эту функцию под свои нужды по аналогии. GetPropName - обратная операция. GetPropVal - по номеру свойства необходимо "положить" в pvarPropVal значение этого свойства, SetPropVal - установить значение свойства. IsPropReadable, IsPropWritable - соответственно, какие свойства могут быть прочитаны, какие можно записывать. Потенциально можно установить какое-либо свойство "только на запись", однако это не является широко распространенной практикой В общем-то, почти везде используется преобразование либо из Integer в TProperties (перечисление свойств), либо наоборот с сопутствующим case. Возвращаемым значением самих функций будут S_OK, если все в порядке, и S_FALSE в противном случае.

С методами ситуация примерно такая же, только добавляется еще несколько функций. GetNParams (не путать с GetNParam!) должна "положить" в plParams количество параметров того или иного метода. GetParamDefValue - можно задать некоторые значения параметров по умолчанию (по номеру метода и параметра "кладем" в pvarParamDefValue это самое значение по умолчанию). В примере ни один из методов не использует значение по умолчанию, если у вас такая же ситуация, соответственно, эту функцию трогать не надо С помощью HasRetVal 1С:Предприятие сможет определить, какие из методов являются функциями, а какие - процедурами. CallAsProc - "обертка" для вызовов методов как процедур (заодно можно запретить вызов функций как процедур). CallAsFunc - "обертка" для вызовов методов как функций (тут уже нужно запретить вызывать процедуры как функции, потому что, согласитесь, ерунда получится).

get_Enabled и put_Enabled в данном примере отвечают за "включение" и "отключение" компоненты, если такая функциональность не нужна, убираем эти методы.

OnMyTimer - это обработчик события таймера, в общем-то, демонстрация того, как вызывать обработчик внешнего события в 1С:Предприятии.

Следующие методы реализуют интерфейс IDispatch, я думаю, вносить в них какие-то модификации можно, если только вы знаете, что делаете

И последний штрих - регистрация компоненты при инициализации модуля. Строчку ComServer.SetServerName('AddIn') оставляем без изменения. А вот TComObjectFactory.Create нужно актуализировать: вторым параметром передать класс нашей компоненты (если вы изменяли TAddInObject на что-то другое; я думаю, что как раз изменить стоит, чтобы ничего не перепуталось), CLSID_AddInObject - это константа с GUID (помните, мы в самом начале должны были сгенерировать свой GUID?). Следующим параметром (и это важно!) необходимо передать строку, совпадающую с именем библиотеки! Далее передаем строку 'V7 AddIn 1.0' или 'V7 AddIn 2.0', с помощью которой сообщаем версию технологии компоненты, и, наконец, ciSingleInstance для 1-й версии технологии, а для 2-й можно использовать ciMultiInstance (по документации, компоненту, сделанную по 2-й версии технологии, можно использовать в нескольких экземплярах).

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

Обсуждение, связанное с написание внешних компонент