Create a Package

A package is a zip archive containing the following files:

Manifest.json: A file containing meta information, such as name, package id, version and other data needed.
Package.psm1: PowerShell installation script with instruction to install, update and remove the package.
One or more installation files: Such as a setup executable, files to copy or other files.

This how to will describe step-by-step the process to create a basic package able to install an application. The how to is split into two sections, it first describes how to create the package by hand to give a solid understanding of what a package is, and then another section on how to generate a package through a PowerShell script, which is the recommended usage.

Note

You can get the examples in this how-to in the server install directory: C:\Program Files (x86)\LS Retail\Update Service\Server\Examples

Create a Package with PowerShell

In a location of your choice, create the following file structure:
```
Example App Package
│   CreatePackages.ps1
│
└───example-app
│   │   Package.psm1
│   │   Example App.exe
```
- CreatePackages.ps1 will contain our script to create the package, start with an empty text file.
- example-app directory contains files to be included in our package.
- Package.psm1 will contain the functions to execute the package, such as install, update and remove. Start with an empty text file.
- Example App.exe is our installation file, you can replace it with any installer that can be installed silently.
Edit Package.psm1 and open it with PowerShell ISE or your favorite PowerShell editor and add the following content to it:
```
$ErrorActionPreference = 'stop'

function Install-Package($Context)
{
    # Path to the setup file during execution:
    $SetupExe = Join-Path $Context.TemporaryDirectory 'Example App.exe'
    # Execute the setup file with silent parameters:
    & $SetupExe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART | Out-Null
    # Check if the execution was successful, else throw an error which Update Service will act on:
    if ($LastExitCode -ne 0)
    {
        throw 'Error occurred while installing Example App.exe'
    }
}
```
Now lets break down what this does: We created the function Install-Package, this will be our entry point to the package and later in this how-to we will define it to execute when the package is installed for the first time and update.

The function accepts the parameter $Context, which Update Service will set during execution and contains context for the package, such as path to the directory containing the package content in $Context.TemporaryDirectory. Further description of the $Context variable can be found here.

Next the Example App.exe installer is located with the $Context.TemporaryDirectory and then executed with silent parameters. The installer is created with Inno Setup.

Finally, if the exit code is not 0 an error is thrown, which will fail the installation.

Also, notice the top line in the file, $ErrorActionPreference = 'stop', by default PowerShell can be very forgiven when specific types of errors occur and will continue the script execution even if they occur. We recommend to change this behavior by adding this line to the top of the script which makes the PowerShell script stop for any error and rather make exceptions for errors you know you want to allow (either will try/catch or the -ErrorAction Continue argument).
Edit CreatePackages.ps1, in the Example App Package directory and add the following content:
```
$ErrorActionPreference = 'stop'
Import-Module UpdateServiceServer

$ExampleApp = @{
    Id = 'example-app'
    Name = 'Example App'
    Version = '1.0'
    Commands = @{
        Install = 'Package.psm1:Install-Package'
        Update = 'Package.psm1:Install-Package'
    }
    InputPath = @(
        Join-Path $PSScriptRoot 'example-app\*' # Add all files to package from directory.
    )
    OutputDir = (Join-Path $PSScriptRoot 'Output')
}

New-UssPackage @ExampleApp -Force
```
Our package is more or less defined with by the $ExampleApp variable. It gives the package a name, id and a version. The id is a unique identifier for the package and is used for reference.

There are two Commands defined, Install and Update, which means that our package will execute the function Install-Package in the Package.psm1 file, both during first time install and during update.

InputPath lists the files that should be included in the package, in this example we include all the files in the example-app directory, which includes the Package.psm1 and Example app.exe. The files listed will be placed in the root of the package archive.

At last, the $ExampleApp variable is passed to New-UssPackage (using splatting), which creates a new package archive using the information we defined.
Execute the CreatePackages.ps1 script and your package will be created in a new folder Output.
Your package is now ready to be imported to your Update Service Server.

Next Steps

Import a Package to a Server.