App Package

Create a package for your Business Central apps and include it in your installations. The package takes care of installing and updating the app, synchronizing the schema, and ensuring multiple apps are installed in the correct order due to dependencies

There are different ways to create packages for apps:

  • From App's Context
    • New-AppPackageFromContext
    • Description:
      • To create a package from an existing app file.
      • Automatically adds dependencies to the package from the app (app.json).
      • Can generate package ID and name from the app.
      • Uses version from app.
    • Scenario:
      • Own apps.
      • 3rd party apps.
  • From AL Project
    • LS Update Service Workspace (VS Code extension)
    • Invoke-AlProjectBuild
    • Description:
      • To create a package from AL project/source code.
      • Use Invoke-AlProjectBuild to produce app and package files.
      • Downloads symbols from the Update Service server instead of a service tier.
      • Produces both app and package files.
      • Compiles multiple projects in dependency order.
    • Scenario:
      • Own apps from AL project.
  • From App, Basic
    • New-AppPackage
    • Description:
      • To create a package from an existing app file.
    • Scenario:
      • Own apps.
      • 3rd party apps.
      • More control over dependencies.
  • Runtime App Package
    • New-RuntimeAppPackage
    • Description:
      • To create a runtime app and a package.
      • Produces runtime app from existing Business Central installation.
      • Runtime app is required if object ID range is not included in the license.
    • Scenario:
      • Modifing LS Central app.
      • Partner app.
      • Object IDs not included in the license.
      • Customer license.

From App's Context

Using New-AppPackageFromContext is the easiest way to create an app package. If your app only has dependencies to Business Central application or LS Central, you only need to specify the app's path and the output directory.

For example, for an app named Cronus Base App and version 1.0.0.0 and has dependencies to the Business Central application and LS Central app:

Import-Module LsPackageTools\AppPackageCreator
New-AppPackageFromContext -Path 'c:\path\to\app\Cronus_Cronus Base App_1.0.0.0.app' -OutputDir 'c:\path\to\output'

This example would produce a new package with the following values:

  • ID: cronus-base-app
  • Name: Cronus Base App
  • Version: 1.0.0.0
  • Dependencies:
    • bc-application >=18.0
    • ls-central-app >=18.0

You can also specify a fixed ID and name for the package:

Import-Module LsPackageTools\AppPackageCreator
New-AppPackageFromContext -Path 'c:\path\to\app\Cronus_Cronus Base App_1.0.0.0.app' -OutputDir 'c:\path\to\output' -Id 'cronus-base-app' -Name 'Cronus Base App'

You can specify multiple app files with internal dependencies. Now, if we have another app called Cronus Api App, which only depends on Cronus Base App:

Import-Module LsPackageTools\AppPackageCreator

$Apps = @('c:\...\Cronus_Cronus Base App_1.0.0.0.app', 'c:\...\Cronus_Cronus Api App_1.0.0.0.app')

$Apps | New-AppPackageFromContext -OutputDir 'c:\path\to\output'

This example would produce two new packages, the one mentioned above and a another one with the following values:

  • ID: cronus-api-app
  • Name: Cronus Api App
  • Version: 1.0.0.0
  • Dependencies:
    • cronus-api-app >=1.0.0.0

See here for more examples.

Note

To create a package for a runtime app file using New-AppPackageFromContext, you must first install the AL Compiler:

Install-UscPackage -PackageId 'bc-al-compiler' -InstanceName 'AlCompiler'

From AL Project

Using the LS Update Service Workspace (VS Code extension), you can use tools to build your AL projects to produce both the apps and packages. Here are some of the benefits:

  • Install Business Central instance tailored to your project, with the required apps, database, and license.
  • Create the app package in your continuous integration processes.
  • Compile the extension without involving the service tier.
  • Check if the app compiles against the defined dependencies.
  • Compile multiple projects in dependency order.
  • Manage dependencies with app.json.

If you have added LS Update Service Workspace to your project, build the project to produce app and package files:

Import-Module LsPackageTools\Workspace

Invoke-AlProjectBuild -ProjectDir 'c:\path\to\AL\Project\Cronus.Base' -Verbose

To compile multiple projects at once:

Import-Module LsPackageTools\Workspace

$Projects = @('c:\path\to\AL\Project\Cronus.Base', 'c:\path\to\AL\Project\Cronus.Api')

Invoke-AlProjectBuild -ProjectDir $Projects -Verbose

See here for more examples.

From App, Basic

The New-AppPackage function is a base for the two methods above. Use this function if you want to set the version and/or dependencies by yourself:

$ErrorActionPreference = 'stop'

Import-Module LsPackageTools\AppPackageCreator
Import-Module UpdateServiceServer

$Package = @{
    Id = 'my-app'
    Name = 'My App'
    Version = '1.0.0'
    Path = 'c:\path\to\extension.app'
    OutputDir = 'c:\MyGoCPackages\Output'
    Dependencies = @(
        @{ Id = 'bc-system-symbols'; Version = ">=16.0.11233.12061" }
        @{ Id = 'bc-base-application'; Version = ">=16.0" }
        @{ Id = 'ls-central-app'; Version = ">=16.0" }
    )
}

New-AppPackage @Package | Import-UssPackage

The specific parameters for this cmdlet are:

  • Id, Name, Version and OutputDir are common package parameters.
  • Path: Specify the path to your app file to include in the package.
  • Dependencies: Specifies dependencies required by the app. This list should reflect the dependencies listed in app.json used to create the app, by listing relevant packages, for instance, if the app has dependencies to:
    • The app System Application by Microsoft (app id: 63ca2fa4-4f03-4f2b-a480-172fef340d3f) then add dependency to the package bc-system-application.
    • The app Base Application by Microsoft (app id: 437dbf0e-84ff-417a-965d-ed2bb9650972) then add dependency to the package bc-base-application.
    • The app LS Central by LS Retail (app id: 5ecfc871-5d82-43f1-9c54-59685e82318d) then add dependency to the package ls-central-app.
    • If the app is standalone, has no dependencies to any other apps, then add a dependency to bc-system-symbols package.

Runtime App Package

Runtime app may be required in setups where a developer license is not available or object IDs are not included in the target license. We have included a convenient function in LsPackageTools to produce runtime apps and create a package with appropriate dependencies.

To create a runtime package for a particular app, you need to:

  1. Supply the target app.
  2. Create a package for the app using one of the methods described above. For example, with the package id my-app.

  3. Install a BC instance with the non-runtime version of the target app.

        $Arguments = @{
        'bc-server' = @{
            NewDatabase = 'true'
            LicenseUri = 'c:\Path\To\License.flf'
        }
    }
    Install-UscPackage -Id 'my-app' -InstanceName 'ProduceRuntime' -Arguments $Arguments

  4. Run New-RuntimeAppPackage to produce a runtime version of the app and a package:

    Import-Module LsPackageTools\RuntimeAppPackageCreator
New-RuntimeAppPackage -InstanceName 'ProduceRuntime' -Id 'my-app' -OutputDir 'c:\Output'
    • This will create a new package called my-app-runtime and will placed in the c:\Output directory.

Complete example:

$AppId = 'my-app'
$Version = '' # Empty for latest
$InstanceName = 'ProduceRuntime'

$Arguments = @{
    'bc-server' = @{
        NewDatabase = 'true'
        LicenseUri = 'c:\Path\To\License.flf'
    }
}
Install-UscPackage -Id $AppId -Version $Version -InstanceName $InstanceName -Arguments $Arguments

Import-Module LsPackageTools\RuntimeAppPackageCreator
New-RuntimeAppPackage -InstanceName $InstanceName -Id $AppId -OutputDir 'c:\Output'

# Optionally, you may want to clean up the service tier:
# Uninstall-UscPackage -InstanceName $InstanceName

Next Steps