Как сделать библиотеку в 1С

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

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

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

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

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

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

Создание общего модуля — ядра библиотеки

Откройте конфигуратор, в дереве конфигурации найдите ветку «Общие» → «Общие модули» и добавьте новый объект. Имя давайте с префиксом библиотеки, чтобы избежать конфликтов: например, «МБ_РаботаСФайлами», где «МБ» — краткий код вашей библиотеки. Префикс — главная защита от совпадения имён при внедрении в типовые конфигурации.

В свойствах модуля установите флажки контекста исполнения. Для серверной логики включите «Сервер» и «Вызов сервера», если модуль должен быть доступен с клиента. Флажок «Клиент (управляемое приложение)» ставьте только для модулей, реально работающих на клиенте. Флажок «Привилегированный режим» включайте осознанно: он отключает проверку прав доступа, и ошибка в таком модуле открывает доступ к данным без ограничений.

Внутри модуля разделите код на области: программный интерфейс (экспортные процедуры), служебный программный интерфейс (для связи модулей библиотеки между собой) и служебные процедуры (внутренняя реализация, без экспорта). Это стандарт структуры, принятый в библиотеке стандартных подсистем.

#Область ПрограммныйИнтерфейс

// Преобразует строку в формат, безопасный для имени файла.
//
// Параметры:
//   ИсходнаяСтрока - Строка - произвольный текст.
//
// Возвращаемое значение:
//   Строка - безопасное имя файла.
//
Функция БезопасноеИмяФайла(ИсходнаяСтрока) Экспорт
Результат = ИсходнаяСтрока;
Недопустимые = "\/:*?""<>|";
Для Н = 1 По СтрДлина(Недопустимые) Цикл
Результат = СтрЗаменить(Результат, Сред(Недопустимые, Н, 1), "_");
КонецЦикла;
Возврат Результат;
КонецФункции

#КонецОбласти

Организация нескольких модулей и подсистемы

Когда функций становится много, разделите их по модулям с суффиксами, отражающими контекст: «МБ_Файлы» (сервер), «МБ_ФайлыКлиент» (клиент), «МБ_ФайлыВызовСервера» (прокси для вызова с клиента), «МБ_ФайлыПовтИсп» (модуль с повторным использованием возвращаемых значений для кэширования). Такое соглашение сразу показывает, где исполняется код.

Модуль с повторным использованием — отдельный инструмент оптимизации. В его свойствах установите «Повторное использование возвращаемых значений» в значение «На время вызова» или «На время сеанса». Функции, возвращающие неизменные данные (константы, настройки), помещайте туда — платформа закэширует результат и не будет выполнять запрос повторно. Не помещайте туда функции, читающие изменяемые данные: кэш вернёт устаревшее значение.

Для визуальной группировки создайте подсистему: ветка «Общие» → «Подсистемы». Включите в неё все объекты библиотеки через кнопку настройки состава. Подсистема не влияет на исполнение кода, но упрощает навигацию, настройку прав и выгрузку объектов при переносе.

1. 1
   Создайте общие модули с префиксом библиотеки
2. 2
   Добавьте подсистему в ветке Общие → Подсистемы
3. 3
   Включите в состав подсистемы все объекты библиотеки
4. 4
   Проверьте права: создайте роль с доступом к объектам библиотеки
5. 5
   Обновите конфигурацию базы данных и проверьте вызов функций из внешней обработки

Хранение настроек и данных библиотеки

Если библиотеке нужны настройки, не храните их в константах типовой конфигурации — при обновлении они могут конфликтовать. Создайте собственные объекты с тем же префиксом: константу «МБ_Настройки» (можно типа «ХранилищеЗначения» для сериализации структуры) или регистр сведений «МБ_НастройкиОбмена».

Для списков значений, которые администратор редактирует вручную, подойдёт собственный справочник. Для фиксации событий — журнал регистрации платформы (через «ЗаписьЖурналаРегистрации») или собственный регистр сведений, если записи нужно показывать пользователю в интерфейсе.

Интеграция с типовой конфигурацией

Библиотека редко живёт отдельно: её вызывают из документов, обработок и отчётов. Чтобы не править типовые модули, используйте подписки на события — создайте подписку на «ПриЗаписи» или «ОбработкаПроведения» нужных документов и укажите обработчик в своём модуле. Подписка — новый объект, она не меняет типовой код.

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

Если вы внедряете библиотеку в конфигурацию на базе БСП, изучите её соглашения: модули с суффиксом «Переопределяемый» предназначены именно для точек расширения. Заполнение таких модулей — штатный способ интеграции, поддерживаемый поставщиком.

Поставка и обновление библиотеки

Для переноса библиотеки между проектами создайте пустую конфигурацию, перенесите в неё все объекты библиотеки и настройте поставку: меню «Конфигурация» → «Поставка конфигурации» → «Настройка поставки». Укажите поставщика, версию и состав объектов. Затем создайте файл поставки (.cf) — его внедряют в целевую конфигурацию через «Сравнить, объединить с конфигурацией из файла».

Ведите нумерацию версий и журнал изменений хотя бы в текстовом файле внутри общего макета. При обновлении библиотеки в проекте вы должны точно знать, какая версия стоит сейчас и что изменилось. Добавьте функцию «ВерсияБиблиотеки()» в программный интерфейс — она позволит проверять версию программно, например при запуске обновления данных.

Функция ВерсияБиблиотеки() Экспорт
	Возврат "1.0.3.12";
КонецФункции

Если библиотека добавляет объекты метаданных (регистры, справочники), предусмотрите обработчик обновления: при первом запуске новой версии он должен заполнить начальные данные. Размещайте такой код в модуле с суффиксом «ОбновлениеДанных» и вызывайте его из штатного механизма обновления конфигурации или из регламентного задания.

Проверка результата и типичные ошибки

После создания библиотеки проверьте её в изоляции: создайте внешнюю обработку, вызовите каждую экспортную функцию с корректными и заведомо ошибочными параметрами. Библиотека не должна «падать» с необработанным исключением — ошибки либо обрабатывайте с записью в журнал регистрации, либо вызывайте явно через «ВызватьИсключение» с понятным текстом.

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