Пакетная система для установки и обновления

Термины

Пакетная система – механизм, позволяющий осуществлять установку, обновление и удаление компонентов и модулей системы ELMA, используя так называемые пакеты.

Пакет – файл определенного формата, содержащий внутри себя описание модуля, скомпилированный код модуля, а также при необходимости исходный код модуля.

Менеджер пакетной системы – программа, позволяющая осуществлять установку, обновление и удаление компонентов и модулей системы ELMA из пакетов, а также создавать новые пакеты.

Компонент ELMA – одна из составных частей системы ELMA: Дизайнер, Веб-часть, Внутренний сервер, сервер Firebird и т.д.

Структура пакета

Пакет представляет собой zip-архив в виде файла с расширением nupkg.

Имя файла формируется в виде <Имя пакета>.<Номер версии>.nupkg.

Внутри файла находятся:

файл спецификации (описания) пакета – <Имя пакета>.<Номер версии>.nuspec. Формат этого файла приведен в отдельном подпункте ниже;
служебные файлы, формируемые автоматически менеджером пакетной системы при создании пакета: [Content_Types].xml, Files_Attributes.xml, папки _rels и package.

Также внутри файла могут находиться (в зависимости от компонентов ELMA, для которых предназначен пакет):

файлы в папке lib\net40 – библиотеки .NET и сопутствующие им файлы (например .xml или .pdb, ресурсные файлы) модуля, находящегося в данном пакете. Данные файлы устанавливаются в папку с библиотеками соответствующего компонента ELMA. Для Веб-части это Web\bin, для Дизайнера - корень папки Designer. Данную папку следует использовать для серверных модулей системы ELMA;
папка src – исходный код модуля, находящегося в данном пакете. Данные файлы при установке пакета не распаковываются в компоненты ELMA и служат только для хранения исходного кода модуля. Наличие данной папки не обязательно;
папка ELMA\Designer – файлы, предназначенные для Дизайнера ELMA. Устанавливаются в корень папки Designer;
папка ELMA\WebModule – файлы веб-модуля. Внутри нее обязательно должна находиться подпапка с именем модуля. Файлы устанавливаются в папку Web\Modules.

Файл спецификации пакета

Файл спецификации (описания) пакета представляет собой xml-файл с расширением nuspec.

Данный файл используется как для создания файла пакета, так и установки пакета (находится внутри файла пакета).

Для начала приведем пример.

<?xml version="1.0"?>
<package>
  <metadata>
    <id>$id$</id>
    <title>Собственный модуль - Web</title>
    <version>$version$</version>
    <description>Пример собственного модуля - веб-часть.</description>
    <authors>My Company</authors>
    <tags>[OwnerId:EleWise.ELMA.MyModule] [Component:Web]</tags>
    <dependencies>
      <dependency id="Autofac.Integration.Web" version="[2.2.4, 2.2.5)" />
      <dependency id="EleWise.ELMA.BPM" version="[3.2.0, 3.3.0)" />
      <dependency id="EleWise.ELMA.BPM.Web.Common" version="[3.2.0, 3.3.0)" />
      <dependency id="EleWise.ELMA.BPM.Web.Content" version="[3.2.0, 3.3.0)" />
      <dependency id="EleWise.ELMA.BPM.Web.Security" version="[3.2.0, 3.3.0)" />
      <dependency id="EleWise.ELMA.SDK" version="[3.2.0, 3.3.0)" />
      <dependency id="EleWise.ELMA.SDK.Web" version="[3.2.0, 3.3.0)" />
      <dependency id="Microsoft.AspNet.Mvc" version="[3.0.0, 3.0.1)" />
      <dependency id="Telerik.Web.Mvc" version="[3.2.0, 3.2.1)" />
    </dependencies>
  </metadata>
  <files>
    <file src="**\*.*" exclude="bin\**\*.*;obj\**\*.*" target="ELMA\WebModule\EleWise.ELMA.MyModule.Web" />
    <file src="bin\EleWise.ELMA.MyModule.Web.*" exclude="bin\*.pdb" target="ELMA\WebModule\EleWise.ELMA.MyModule.Web\bin" />
  </files>
</package>

Секция metadata

Описание тэгов внутри данной секции (звездочкой помечены обязательные тэги):

id* – уникальный идентификатор (имя) пакета (например, EleWise.ELMA.Projects);
title* – имя пакета в понятном человеку виде (например, Управление проектами). Используется при отображении списка модулей;
version* – версия пакета в формате вида 1.2.3 (или 1.2.3.4);
description* – полное описание пакета;
authors* – авторы кода пакета (если авторов несколько, для разделения используется запятая);
owners – владельцы (создатели) пакета. Обычно это тот же список, что и в authors;
releaseNotes – информация об изменениях в каждой версии данного пакета;
summary – краткое описание пакета. Используется при отображении списка модулей;
language – идентификатор локализации пакета (например, en-us);
projectUrl – URL страницы с информацией о пакете;
iconUrl – URL для иконки пакета;
licenseUrl – URL страницы с лицензионным соглашением для данного пакета;
copyright – авторские права для пакета;
dependencies – список зависимостей для пакета: имена и версии пакетов, которые требуются для установки данного пакета;
tags – список тэгов (меток), разделенный пробелами. Используется для поиска пакетов, а также для задания служебной информации системы ELMA (значения в квадратных скобках).

Остановимся подробнее на некоторых тэгах:

version:

номер версии формируется в виде 3 или 4 чисел, разделенных точкой. В системе ELMA для пакетов приняты следующие правила нумерования:

1-е и 2-е число – номер мажорной версии (3.1, 3.2 и т.д.);

3-е число – номер минорной версии;

4-е число – номер сборки (ревизия).

Рекомендуется придерживаться правила, что в рамках одной мажорной версии публичный API модуля не меняется (может дополняться, но существующие методы должны оставаться).

dependencies:

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

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

Каждая зависимость представляет собой тэг dependency с атрибутами id и version:

в id указывается идентификатор требуемого пакета;
в version – диапазон версий. Ниже приведены примеры (до знака равно сам диапазон, который нужно указывать в атрибуте version, после знака – математическое описание данного диапазона).

1.0 = 1.0 ≤ x
(,1.0] = x ≤ 1.0
(,1.0) = x < 1.0
[1.0] = x == 1.0
(1.0) = неверный номер
(1.0,) = 1.0 < x
(1.0,2.0) = 1.0 < x < 2.0
[1.0,2.0] = 1.0 ≤ x ≤ 2.0

tags:

в данный элемент можно включать следующие тэги со служебной информацией (все тэги являются необязательными):

[Type:<Значение>] – указывает тип пакета. Допустимые значения: Core (пакет с системным модуль, по умолчанию не показывается в списке модулей в веб-части), Module (пакет с основным модулем, по умолчанию показывается в списке модулей в веб-части), Integration (пакет для интеграции нескольких модулей), Help (пакет со справкой для какого-либо модуля). Пример: [Type:Module];
[OwnerId:<Идентификатор пакета>] – указывает идентификатор "пакета-владельца" для данного пакета. При установке "пакета-владельца" будут автоматически установлены те пакеты, где в OwnerId указан идентификатор данного "пакета-владельца". Пример: есть пакет с серверным модулем MyCompany.CustomModule, а также пакет с веб-модулем MyCompany.CustomModule.Web, в котором указан тэг [OwnerId:MyCompany.CustomModule]. При установке модуля MyCompany.CustomModule будет автоматически установлен пакет MyCompany.CustomModule.Web. Для пакетов интеграции модулей данный тэг может повторяться несколько раз – это будут имена пакетов, для которых предназначена данная интеграция. При установке всех этих пакетов пакет интеграции будет установлен автоматически;
[Component:<Компонент ELMA>] – указывает rомпонент ELMA, для которого предназначен данный пакет. Допустимые значения: Web (веб-часть), Designer (Дизайнер ELMA);
[Edition:<Редакция ELMA>] – указывает редакцию системы ELMA, для которой предназначен данный пакет. Допустимые значения: Express, Standart, Enterprise. На данный момент тэг предназначен только для информации;
[Priority:<Целое число>] – указывает приоритет, по которому производится сортировка при выводе списка модулей.

Секция files

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

Элемент files является необязательным элементом внутри элемента package и содержит внутри список элементов file. Каждый элемент file определяет исходное расположение файла (атрибут src) и расположение внутри пакета (атрибут target). Также может быть указан атрибут exclude, если необходимо исключить некоторые файлы из тех, которые указаны в атрибуте src.

Ниже приведено описание данных атрибутов:

src – расположение исходного файла или файлов, которые нужно включить в пакет. Путь указывается относительно папки проекта, либо полный путь до файла. Допускается использование символа шаблона – звездочки (*). Использование двойной звездочки (**) обозначает рекурсивное включение файлов по всем подпапкам;
target – относительный путь внутри пакета, куда будут помещены исходные файлы;
exclude – файл или файлы, которые НЕ нужно включать в пакет. Используется, когда в атрибуте src указан шаблон и необходимо исключить некоторые файлы из тех, что удовлетворяют данному шаблону. В данном атрибуте можно указывать несколько файлов, используя точку с запятой для разделения их путей. Также допускается использование символов шаблонов (одиночная и двойная звездочка);
если в исходном файле спецификации данная секция отсутствует, то в пакет будут включены следующие файлы в зависимости от типа пакета.
Для веб-проекта:

<files>;

<file src="**\*.*" exclude="bin\**\*.*;obj\**\*.*;<Имя проекта>.csproj.user;Content\Help\**\*.*;**\*.snk" target="ELMA\WebModule\<Имя папки проекта>" />

<file src="<OutputPath>\<Имя проекта>.*" exclude="<OutputPath>\*.pdb" target="ELMA\WebModule\<Имя папки проекта>\bin" />

</files>

Для остальных проектов – скомпилированная библиотека проекта и соответствующие ей файлы документации (*.xml) и конфигурации (*.exe.config). Файл отладки (*.pdb) не включается.

Создание пакетов

Для создания пакета необходимо:

открыть в Visual Studio решение с вашим проектом (или несколькими проектами);
создать файл спецификации пакета в корне проекта или в подпапке Properties. Имя файла должно быть в виде <Имя проекта>.nuspec;
запустить Менеджер пакетной системы, передав ему на вход команду сборки пакета, имя файла решения Visual Studio, номер версии, а также папку, где будет создан пакет. Менеджер пакетной системы создаст пакет для каждого проекта из решения Visual Studio, который отмечен для сборки.

..\PackageManager\EleWise.ELMA.Packaging.Console.exe packSln %~dp0WebApplication\ELMA.WebApplication.sln -v 1.0.0.1000 -out %~dp0Packages