Package system for installation and update

Terms

Package system - is a mechanism that allows installing, updating and deleting ELMA components and modules using packages.

Package - a file in a specific format, that contains the description of a module, compiled the code of the module, and the source code of the module if necessary.

Package system manager - a program that allows installing, updating and deleting ELMA components and modules using packages, as well as create new packages.

ELMA component - one of constituents of ELMA: Designer, Web Application, Internal Server, Firebird Server, etc.

Package structure

A package is a zip-archive as a nupkg file.

The file name is generated as "<Package name>.<Version number>.nupkg".

Inside the file are:

The package specification file - "<Package name>.<Version number>.nuspec". The format of this file is described below in a separate paragraph.
Service files, generated automatically by the package system manager when creating a package - [Content_Types].xml, Files_Attributes.xml, folders _rels, and package.

Also, inside the file there may be (depending on the ELMA components, for which the package is intended):

Files in the folder lib\net40 - of the .NET library and accompanying files (e.g. .xml or .pdb, resource files) of the module, in this package. These files are installed to the folder with the libraries of the respective ELMA component. Web\bin - for the web part, Designer folder root - for the Designer. This folder should be used for server modules of ELMA.
src folder - is the source code of the module in this package. These files are not unpacked to ELMA components upon installation and only serve to store the module source code. This folder is not necessary.
ELMA\Designer folder - files, intended for the ELMA Designer. Installed to the root of the Designer folder.
ELMA\WebModule folder - web module files. It must contain a subfolder with the module name. Files are installed in the Web\Modules folder.

Package specification file

A package specification file is an xml file with the nuspec extension.

This file is used both for creating a package file and for installing the package (it is inside the package file).

Here is an example:

<?xml version="1.0"?>
<package>
  <metadata>
    <id>$id$</id>
    <title>Custom module - Web</title>
    <version>$version$</version>
    <description>Example of a custom module - web part.</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 section

Description of tags in this section (the required tags are marked with asterisks):

id* - Unique package identifier (name), e.g. EleWise.ELMA.Projects.

title* - Package name in an understandable format, e.g. Project Management. Used in the displayed module list.

version* - Package version in the 1.2.3 format (or 1.2.3.4).

description* - Full package description.

authors* - Package code authors (if there are several authors, they are separated by commas).

owners - Package owners (creators). Usually the same, as in the "authors".

releaseNotes - Information about the changes in each version of this package.

summary - Package brief description. Used in the displayed module list.

language - Package localization ID, e.g. en-us.

projectUrl - URL of the page with the package information.

iconUrl - URL of the package icon.

licenseUrl - URL of the page with the license agreement of the package.

dependencies - List of package dependencies - names and versions of packages, required for the installation of this package.

tags - List of tags, separated by spaces. Used for searching packages and for setting service information of ELMA system (values in brackets).

Let's take a closer look at some of the tags:

version

The version number consists of 3 or 4 numbers separated by full stops. In ELMA, packages are numbered according to the following rules:

First and second numbers - major version number (3.9, 3.11, etc.).

Third number - minor version number.

Fourth number - build number.

It is recommended to stick to the rule that the module's public API does not change within one major version (it can be extended, but existing methods must remain).

dependencies

Dependencies are used by the Package System Manager to check that there are required packages upon installation.

If a required package is not installed (or an older version is installed), but available for installation, it will be installed automatically. If a package is not installed and cannot be installed, the Package System Manager will return an error, that installing the module is impossible.

Each dependency is a dependency tag with the id and version attributes.

id specifies the required package ID.

version defines the range of versions. Below are the examples (before "=" is a range, specified in the version attribute, and after "=" is a description of the range).

1.0 = 1.0 ≤ x
(,1.0] = x ≤ 1.0
(,1.0) = x < 1.0
[1.0] = x == 1.0
(1.0) = incorrect
(1.0,) = 1.0 < x
(1.0,2.0) = 1.0 < x < 2.0
[1.0,2.0] = 1.0 ≤ x ≤ 2.0

files section

This section contains the description of the files, that will be included in the created package. Used only when creating a package. In a finished package, this section is absent.

The "files" element is an optional element inside the "package" element and contains a list of "file" elements. Each "file" element defines the source location of the file ("src" attribute) and the location inside the package ("target" attribute). You can also specify the "exclude" attribute to exclude some files from those, specified in the "src" attribute.

These attributes are described below.

src - The location of the source file or files to include in the package. A path is specified relative to the project folder, or the full path to the file. Using a template character - (*) asterisk - is allowed. Using a double asterisk (**) means the recursive inclusion of files from all subfolders.
target - Relative path inside the package, where the source files will be placed.
exclude - File or files, to NOT include in the package. Used if a template is specified in the "src" attribute, and some files need to be excluded from the those that comply with the template. You can specify several files in this attribute, separating their paths with semi-columns. Using templates is also allowed (single and double asterisk).

If the specification source file does not contain this section, then the following files will be included in the package depending on its type.

A web project:

<files>

<file src="**\*.*" exclude="bin\**\*.*;obj\**\*.*;<Project name>.csproj.user;Content\Help\**\*.*;**\*.snk" target="ELMA\WebModule\<Project folder name>" />

<file src="<OutputPath>\<Project name>.*" exclude="<OutputPath>\*.pdb" target="ELMA\WebModule\<Project folder name>\bin" />

</files>

For other projects - a compiled project library and the corresponding documentation (*.xml) and configuration (*.exe.config) files. The debugging file (*.pdb) is not included.

Creating packages

To create a package:

Open the solution with your project (or projects) in Visual Studio.
Create a package specification file in the project root or in the Properties subfolder. The file name must be in the form "<Project name>.nuspec".
Start the Package System Manager, having passed it a command to start assembling a package, a Visual Studio solution file name, a version number and a folder, where the package will be created. The Package System Manager will create a package for each project from the Visual Studio solution, which is selected for assembly.

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