Структура проекта расширения

Структура проекта расширения базируется на стандартных принципах построения проектов в «1С:Шине», но включает специфические элементы, обеспечивающие связь с расширяемыми проектами. Расширение состоит из файла описания проекта, модуля проекта и двух видов подсистем: собственных и подсистем-расширений. Также расширение может использовать или расширять библиотеки.

Файл описания проекта

Основным файлом конфигурации является элемент проекта Описание проекта. В нем указывается вид проекта — Расширение, а также другие свойства расширения (например, список проектов, которые изменяет данное расширение).

Подробнее о свойствах проекта

Расширяемые проекты

Свойство РасширяемыеПроекты содержит массив проектов, к которым применимо данное расширение. Для каждого расширяемого проекта указываются поставщик, имя и диапазон версий.

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

Диапазон версий

Для каждого расширяемого проекта можно задать Версии — диапазон, определяющий совместимые версии расширяемого проекта. Диапазон задается границами От и До. Каждая граница описывается версией и флагом Включать (по умолчанию Истина).

Примеры задания различных диапазонов:

• x == 1.0: От: 1.0, До: 1.0.
• x <= 1.0: До: 1.0.
• x < 1.0: До: 1.0, Включать: Ложь.
• x >= 1.0: От: 1.0.
• 1.0 < x < 2.0: От: 1.0, Включать: Ложь, До: 2.0, Включать: Ложь.

При установке расширения в приложение проверяется, что в приложении присутствуют все расширяемые проекты с версиями, попадающими в указанные диапазоны.

важно

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

Пример файла Проект.yaml

ВидПроекта: Расширение
Поставщик: e1c
Имя: РасширениеБазыЗадач
Версия: 1.0
РасширяемыеПроекты:
  -
    Поставщик: e1c
    Имя: БазаЗадач
    Версии:
        От:
            Версия: 1.0
        До:
            Версия: 2.0
            Включать: Ложь

Модуль проекта

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

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

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

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

• Обновляется проект приложения и одно или несколько расширений — сначала запускается обработчик обновления для проекта приложения, затем — обработчики расширений.

примечание

Добавление, обновление, включение, выключение расширений и изменение их порядка запускают процедуру обновления приложения.

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

Подробнее про запуск обработчиков обновления

Пример применения нескольких проектов

Рассмотрим вызов обработчиков обновления при одновременном применении следующих проектов.

Проект приложения зависит от Библиотеки А, которая, в свою очередь, зависит от Библиотеки Б и Библиотеки В:

Проект приложения
└── Библиотека А
    ├── Библиотека Б
    └── Библиотека В

Расширение 1 зависит от Библиотеки Б и Библиотеки Г:

Расширение 1
├── Библиотека Б
└── Библиотека Г

Расширение 2 зависит от Библиотеки А, Библиотеки Г и Библиотеки Д:

Расширение 2
├── Библиотека А
├── Библиотека Г
└── Библиотека Д

Схема зависимостей проектов выглядит следующим образом:

Применение начинается с проекта приложения. Сначала в порядке обратного обхода зависимостей запускаются обработчики обновления всех библиотек проекта, затем — обработчик самого проекта.

Далее обрабатываются расширения в порядке их применения. Для Расширения 1 запускаются обработчики обновления его библиотек, если они еще не запускались. Обработчики Библиотеки Б уже были запущены при применении проекта приложения, поэтому запускаются только обработчики Библиотеки Г, а затем — обработчики самого расширения.

Для Расширения 2 запускаются только обработчики обновления Библиотеки Д, так как обработчики Библиотеки А и Библиотеки Г уже отработали на предыдущих шагах. После обработки библиотек запускаются обработчики самого расширения.

Итоговая последовательность запуска обработчиков:

1. Библиотека Б
2. Библиотека В
3. Библиотека А
4. Проект приложения
5. Библиотека Г
6. Расширение 1
7. Библиотека Д
8. Расширение 2

Собственные подсистемы

Собственные подсистемы расширения представляют собой обычные подсистемы. Их пространство имен формируется по стандартному правилу: ИмяПоставщикаРасширения::ИмяПроектаРасширения::ИмяПодсистемы.

Элементы из таких подсистем имеют доступ к элементам расширяемого проекта с видимостью ВПроекте.

Собственные подсистемы расширения можно использовать в пользовательским интерфейсе приложения: они добавляются в автоматический командный интерфейс приложения в соответствии со значением свойства ВключатьВАвтоИнтерфейс.

РасширениеПодсистемы

Для непосредственного изменения поведения расширяемого проекта используются специальные подсистемы вида РасширениеПодсистемы, или подсистемы-расширения. Это подсистемы, которые дополняют уже имеющиеся подсистемы в расширяемом проекте.

Пространство имен подсистемы-расширения: ИмяПоставщикаРасширения::ИмяПроектаРасширения::ИмяПодсистемы[::ИмяПакета]. Имя файла описания — Подсистема.Расширение.yaml.

Свойства подсистемы-расширения

Свойства подсистемы-расширения имеют ряд отличий от свойств обычной подсистемы:

• Использование — массив подсистем, используемых данной подсистемой-расширением. В отличие от обычной подсистемы имеет следующие ограничения:
  • Подсистемы, которые использует расширяемая подсистема, не становятся используемыми в подсистеме-расширении.
  • Подсистемы, которые использует подсистема-расширение, не добавляются в список используемых расширяемой подсистемы.
• РасширяемаяПодсистема — свойство, доступное только для подсистемы-расширения. Пространство имен подсистемы расширяемого проекта, которую расширяет данная подсистема. Это свойство обязательно, если расширение изменяет несколько проектов. Если проект один, расширяемая подсистема определяется по совпадению имен.

Ресурсы

В подсистеме-расширении и ее пакетах можно добавлять собственные ресурсы.

Область видимости, заданная в файле описания ресурсов, влияет только на ресурсы подсистемы-расширения и не изменяет область видимости ресурсов расширяемой подсистемы.

Доступ к ресурсам может осуществляться программно с помощью типа ПакетРесурсов или с помощью литералов. Из кода расширяемого проекта нет доступа к ресурсам из подсистемы-расширения — при попытке обращения будет выдана ошибка применения. Из кода самого расширения доступен как поиск в текущем пространстве имен (Ресурс{Иконка.svg}), так и явное обращение к ресурсам расширяемой подсистемы (Ресурс{БазаЗадач::Основная::Иконка.svg}).

примечание

Ресурсы, добавленные в подсистему-расширение, доступны только в рамках самой подсистемы-расширения и недоступны в расширяемом проекте.

Доступность элементов и ограничения

Элементы, находящиеся в подсистеме-расширении, имеют доступ:

• к элементам расширяемой подсистемы с видимостью ВПодсистеме,
• к другим подсистемам расширяемого проекта с видимостью ВПроекте,
• к другому расширяемому проекту (если их несколько) с видимостью ВПроекте,
• к другим подсистемам самого расширения с видимостью ВПроекте.

Подсистемы-расширения могут содержать как обычные элементы, так и элементы-расширения.

Действуют следующие структурные ограничения:

• В одном расширении только одна подсистема может расширять конкретную подсистему из расширяемого проекта.
• Изменение свойств самой расширяемой подсистемы не поддерживается.