Copy page

PowerShell Module

RuntimePackages module

Module: businessdev.ALbuild.RuntimePackages  •  Tier: Licensed  •  Cmdlets: 7

The RuntimePackages module builds signed Business Central runtime packages for on-premise distribution — one per supported platform version — using a batched, parallel and incremental engine. See the Runtime packages deep dive. This is a licensed feature, enforced at runtime by Assert-ALbuildLicensed.

Cmdlets in this module

---

Build-BcRuntimePackages

Builds runtime packages for one or more apps across Business Central platform versions (licensed).

Implements the batched/incremental runtime-package engine: for each target platform version it creates a single container, publishes all apps into it, generates each app's runtime package and packs a runtime NuGet package (id '<publisher>.<name>.runtime-<appversion>', package version = platform version, resolvable by platform version), then removes the container. One container per version (not per app x version) minimises spin-ups; running this per version on separate agents provides the parallel dimension. A valid ALbuild license is required.

Syntax

Code
Build-BcRuntimePackages
    -App <Object[]>
    -PlatformVersion <String[]>
    [-Type <String>]
    [-Country <String>]
    [-Credential <PSCredential>]
    [-OutputFolder <String>]
    [-DockerExecutable <String>]

Parameters

Output

PSCustomObject per produced runtime package (Version, App, RuntimeApp, NuGetPackage).

---

Get-BcRuntimePackageBuildPlan

Determines which Business Central platform versions still need a runtime package built.

Given the candidate platform versions, the app's minimum supported version, and the set of already-built versions, returns the versions that need building - the "incremental" part of the batched runtime-package engine. Versions below the app's minimum, or already built, are excluded.

Syntax

Code
Get-BcRuntimePackageBuildPlan
    -ArtifactVersion <String[]>
    [-MinimumVersion <String>]
    [-AlreadyBuilt <String[]>]

Parameters

Output

System.String - the platform versions to build, ascending.

Examples

Example 1

Code
Get-BcRuntimePackageBuildPlan -ArtifactVersion $versions -MinimumVersion '25.0.0.0' -AlreadyBuilt $built

---

Get-BcRuntimeWorkSet

Plans outstanding runtime-package work, grouped by BC platform version across all products.

Turns "which (product, app version, platform version) runtime packages are still missing?" into an ordered, sliceable plan. It is a pure function - no feed, blob or artifact calls - so the whole planning policy is unit-testable and a run can be inspected before a single container starts.

WHY GROUPING BY PLATFORM VERSION IS THE WHOLE POINT A runtime package is produced server-side by a running BC service tier, and Microsoft only guarantees it on the exact platform version it was produced on - so the (product x platform) matrix is irreducible. What IS reducible is the container count. Measured on build 27197, provisioning a container costs 238-564 s depending on the major, while the value-adding work per product is a constant ~80 s. Iterating platform-versions-per-product, as one pipeline per product does, pays that provisioning cost once per product; iterating products-per-platform-version pays it once, full stop. For a 12-product catalogue over ~192 versions that is ~2 300 container starts against 192.

It also removes a failure mode rather than working around it: several products depend on other products in the same catalogue (Extension License, 365 business API). Per-product pipelines had to fetch those dependencies' runtime packages from blob storage and SKIP the platform version when they were not there yet. Built in one container in dependency order, the dependency is simply present - it was built moments earlier, in the same container.

LANES A product release invalidates the entire matrix at once, and a full rebuild is hours of work no matter how it is scheduled. Customers, however, pull the newest majors first. -FastLaneMinMajor splits the plan so those versions are built and published first, and the long tail follows behind without holding the release up.

SLICES Each slice is the unit of work for one agent job. -MaxVersionsPerSlice bounds how long a single job runs, which matters because a job holds one of the organisation's few parallel slots for its whole lifetime - and because a job that dies loses only its in-flight version, not the run.

Syntax

Code
Get-BcRuntimeWorkSet
    -Product <Object[]>
    -PlatformArtifact <Object[]>
    [-ExistingPackage <String[]>]
    [-ExistingFeedPackage <String[]>]
    [-SkipPlatformVersion <String[]>]
    [-FastLaneMinMajor <Int32>]
    [-Lane <String>]
    [-MaxVersionsPerSlice <Int32>]

Parameters

Output

PSCustomObject with Slices (Index, Lane, Items[]) and Summary (per-product counts).

Examples

Example 1

Code
$plan = Get-BcRuntimeWorkSet -Product $catalogue -PlatformArtifact $artifacts `
            -ExistingPackage $blobNames -FastLaneMinMajor 27 -Lane FastLane
$plan.Slices | ForEach-Object { Invoke-BcRuntimeFactory -WorkItem $_.Items ... }

---

Invoke-BcRuntimeFactory

Builds runtime packages for a slice of platform versions, several containers at a time.

Runs the work items from Get-BcRuntimeWorkSet through a pool of worker threads, each owning one BC container for one platform version, and checkpoints every version as soon as it is done.

WHY A POOL INSIDE ONE JOB Throughput here is capped by the organisation's four parallel self-hosted jobs, not by the build host - which has 36 cores and 192 GB of RAM and was measured with ~72 GB still free while four containers ran. Adding pipeline stages cannot get past that cap; adding workers inside a job does, and costs nothing.

WHY CHECKPOINTING Build 27197 built 186 runtime packages and shipped 130 of them. Upload ran once, after the whole loop, so when the run was cancelled ten hours of finished work was thrown away. -OnVersionComplete runs after each platform version, so a cancelled or crashed run loses at most the version still in flight.

The callback runs on the DISPATCHER thread, deliberately. Uploading to blob storage and pushing to a feed needs an Azure PowerShell context, and those context objects are not safe to share across runspaces. Workers produce files; the dispatcher ships them.

PER-APP VISIBILITY Azure DevOps renders a stage as a single icon, and giving every app its own stage would mean a container per (app, platform version) - the arrangement the factory exists to remove. So the per-app result is carried in the artefacts a job can publish instead:

• the log, one collapsible '##[group]' per platform version with one line per app;
• -JUnitPath, one test case per app per version for PublishTestResults@2, which is what puts a green/red/skipped entry per app into the Tests tab;
• -SummaryPath, the app x version matrix for '##vso[task.uploadsummary]'.

Worker output is captured to a per-version file and replayed by the dispatcher when the version finishes, so the log reads as ordered blocks instead of interleaved lines from parallel workers.

Syntax

Code
Invoke-BcRuntimeFactory
    -WorkItem <Object[]>
    -WorkRoot <String>
    -OutputFolder <String>
    [-Throughput <Int32>]
    [-MemoryLimit <String>]
    [-ReserveHostGb <Int32>]
    [-Credential <PSCredential>]
    [-LicenseFile <String>]
    [-LegacyLicenseFile <String>]
    [-Signing <Hashtable>]
    [-TeardownMode <String>]
    [-UseImageCache]
    [-OnVersionComplete <ScriptBlock>]
    [-LogFolder <String>]
    [-JUnitPath <String>]
    [-SummaryPath <String>]
    [-DockerExecutable <String>]
    [-NoAzureDevOpsLogging]

Parameters

Output

PSCustomObject: Produced, Failed, Skipped, Results[], WorkerCount.

---

New-BcIndirectNuGetPackage

Creates an "indirect" NuGet package that maps platform versions to runtime packages.

Produces a dependency-only NuGet package whose dependencies are the per-platform-version runtime packages. A consumer resolving against a specific Business Central build pulls the matching runtime package through this single, stable package id.

Syntax

Code
New-BcIndirectNuGetPackage
    -PackageId <String>
    -Version <String>
    -RuntimePackage <Object[]>
    [-Authors <String>]
    [-Description <String>]
    [-OutputFolder <String>]

Parameters

Output

System.String - the path to the created .nupkg.

---

New-BcRuntimePackage

Generates a runtime package for a published app from a Business Central container.

Runs Get-NAVAppRuntimePackage inside the container to produce a platform-specific runtime (.runtime.app) for an already-published app, then copies it to the host. Runtime package generation is an NST (server) operation and therefore requires the container.

Syntax

Code
New-BcRuntimePackage
    -Name <String>
    -AppName <String>
    -AppPublisher <String>
    -AppVersion <String>
    -OutputFolder <String>
    [-ServerInstance <String>]
    [-DockerExecutable <String>]

Parameters

Output

System.String - the path to the generated runtime .app on the host.

---

Publish-BcRuntimePackage

Publishes a runtime NuGet package to a feed (licensed).

Pushes a runtime (or indirect) NuGet package to a NuGet v3 feed. A valid ALbuild license is required.

Syntax

Code
Publish-BcRuntimePackage
    -PackagePath <String>
    -Url <String>
    -ApiKey <String>
    [-FailOnConflict]

Parameters

Examples

Example 1

Code
Publish-BcRuntimePackage -PackagePath .\pkg.nupkg -Url $feed -ApiKey $key

---