Copy page

PowerShell Module

Apps module

Module: businessdev.ALbuild.Apps  •  Tier: Free  •  Cmdlets: 36

The Apps module covers everything you do with an AL app: compile (container or container-less), publish/sync/install/uninstall/unpublish, sign, run tests, validate, manage app versions, install 365 business development apps, and create/sync/validate XLIFF translations.

Cmdlets in this module

---

Convert-BcCodeCoverage

Converts raw Business Central code coverage (.dat CSV from Invoke-BcContainerTest -CodeCoverage) into ALbuild JSON, Cobertura XML and/or a Markdown summary.

The raw rows are VariableText CSV: ObjectType, ObjectID, LineNo, CoverageStatus, NoOfHits. This aggregates them per object (max hit count per line - union semantics across chunks), attaches each object to its source file via the workspace AL object map, computes line coverage, and emits the requested formats. With -WorkspaceRoot the result is restricted to objects whose source is in the workspace (your app code); without it, every tracked object is included.

Syntax

Code
Convert-BcCodeCoverage
    -CoveragePath <String>
    [-WorkspaceRoot <String>]
    [-Format <String[]>]
    [-DenominatorMode <String>]
    [-OutputFolder <String>]
    [-TestQuality <Object>]
    [-ExcludeNeverExecutedObjects]
    [-ExcludeProjects <String[]>]

Parameters

Output

PSCustomObject: Summary, Objects, TestQuality, Outputs (the written file paths).

---

Get-BcCodeCoverageDelta

Computes "patch coverage" -- how well the lines you changed (vs a git baseline) are covered by tests.

Overall coverage rewards a big tested codebase even when new code is untested; patch coverage answers the question that matters on a pull request: are the lines I just added/changed actually exercised? This diffs the workspace against a git baseline ref, keeps the added/modified .al lines that BC would treat as executable (Get-BcAlExecutableLines), and checks each against the coverage data. Files/objects with no executable changes are ignored.

Syntax

Code
Get-BcCodeCoverageDelta
    -BaselineRef <String>
    [-HeadRef <String>]
    -WorkspaceRoot <String>
    -CoveragePath <String>
    -SummaryPath <String>

Parameters

Output

PSCustomObject: Summary { changedExecutableLines, coveredChangedLines, deltaCoverage, fileCount }, Files[].

---

Get-BcCodeCoverageSummary

Returns the ALbuild code-coverage summary (and per-object lines) without writing report files.

A read-only convenience over the coverage data: point it at raw *.dat (with -WorkspaceRoot for the honest source-based denominator) or at an existing coverage-summary.json. Returns the same { lineCoverage, coveredLines, totalExecutableLines, objectCount, denominatorMode } summary plus the per-object breakdown, so agents and scripts can inspect coverage without re-emitting Cobertura/Markdown.

Syntax

Code
Get-BcCodeCoverageSummary
    -CoveragePath <String>
    [-WorkspaceRoot <String>]
    [-DenominatorMode <String>]
    -SummaryPath <String>

Parameters

Output

PSCustomObject: Summary, Objects.

---

Get-BcContainerAppDiagnostic

Explains why publishing, installing or synchronising an app in a container fails.

A failed publish reports a symptom ("an earlier version was already installed", "the extension is not synchronized") but never the state that produced it. From outside the container that state is invisible, so the caller is left guessing which of several very different situations it is in.

This collects the evidence in one pass and turns it into named blockers:

• every PUBLISHED version of the app (Get-NAVAppInfo on the server instance), and
• per version, the TENANT's view (Get-NAVAppInfo -TenantSpecificProperties): IsInstalled, SyncState, NeedsUpgrade and ExtensionDataVersion - the version the tenant's DATA is at, which is what actually decides whether an install or a data upgrade is required, and
• the tail of the Business Central server event log, which is where schema-sync failures record the offending table/field.

Every blocker carries a stable code (DATA_UPGRADE_REQUIRED, VERSION_ALREADY_PUBLISHED, NOT_SYNCHRONIZED, SCHEMA_CONFLICT) and the command that clears it, so a caller can branch on the cause instead of pattern-matching a PowerShell message that changes between BC versions.

Read-only: it publishes, installs, syncs and removes nothing.

Syntax

Code
Get-BcContainerAppDiagnostic
    -Name <String>
    [-AppName <String>]
    [-ServerInstance <String>]
    [-Tenant <String>]
    [-EventLogEntries <Int32>]
    [-DockerExecutable <String>]

Parameters

Output

PSCustomObject with Container, Apps, SyncErrors, EventLog and Blockers.

Examples

Example 1

Code
Get-BcContainerAppDiagnostic -Name albmcp01480a -AppName '365 business Banking'

Reports the published versions, the tenant data version and the blockers preventing a publish.

---

Get-BcTestQuality

Heuristically assesses the QUALITY of AL tests (assertions, arrange/act/assert) -- not their coverage.

Code coverage is not test quality: a [Test] method can execute every line of the code under test and still assert nothing, so it would show as "covered" while catching no regression. This scans the AL [Test] methods in a workspace and flags quality smells per test:

• NoAssertions - the body contains no assertion (no Assert/LibraryAssert call, no TestField, no asserterror, no guard Error()), so it cannot fail on a wrong result.
• Empty - the body has no executable statements.
• NoAct - the body asserts but never invokes anything outside the assertion library (a test that only checks constants).

It returns a per-test breakdown and a suite summary with a 0-100 quality score (share of tests that actually assert, penalised for empty tests). The heuristics are intentionally conservative and documented; treat the score as a smell detector, not a grade.

Syntax

Code
Get-BcTestQuality
    -WorkspaceRoot <String>
    -Path <String>

Parameters

Output

PSCustomObject: Summary, Tests[].

---

Get-BcTranslationUnit

Lists the translation units of an AL XLIFF file as structured objects (the read surface behind albuild translation list).

Projects each trans-unit to { id, source, developerNote, context (Xliff-Generator note), currentTarget, state, tmOrigin } using the shared Get-BcXliffUnit reader. This is the stable input a consumer uses to translate the remaining open strings. -OnlyMissing returns just the units that still need a translation (empty target or a needs-translation/-adaptation state); -State filters by an explicit target state.

Syntax

Code
Get-BcTranslationUnit
    -Path <String>
    [-OnlyMissing]
    [-State <String>]

Parameters

Output

PSCustomObject per unit: { id, source, developerNote, context, currentTarget, state, tmOrigin }.

---

Get-BcVersionComponents

Splits a Business Central version into its components plus a 3-part SemVer form.

Pure helper (no I/O, unit-testable) used by the Stamp Build Version task to expose the version as individual pipeline variables. Missing lower components are normalised to 0 (a 2-part '1.2' yields Build 0, Revision 0). The 'Short' value (Major.Minor.Build) is a valid 3-part SemVer for feeds that reject a 4-part version - e.g. Azure Universal Packages, which require X.Y.Z.

Syntax

Code
Get-BcVersionComponents
    -Version <Version>

Parameters

Output

PSCustomObject: Major, Minor, Build, Revision (int) and Short (string 'Major.Minor.Build').

---

Import-BcTranslationMemory

Builds (and caches) a deterministic translation-memory index from prioritised reference XLIFFs.

Reads a prioritised, ordered list of reference XLIFF files and builds an in-memory index of known source->target translations, for Merge-BcTranslationMemory to apply to new units. Two keys per unit: a context-sensitive "GenNote|source" (e.g. "Table Vendor - Field No.|No.") and a plain "source" fallback. On a key collision the higher-priority reference wins (equal priority: the earlier reference wins), so an app's own / sibling-app terms override the Microsoft BC base.

The index is cached under LOCALAPPDATA/ALbuild/tm (or ~/.local/share/ALbuild/tm) keyed by the reference files' paths + last-write-times + sizes, so the large BC base XLF (>100k units) is only re-parsed when a reference actually changed. Deterministic and offline: no network, no LLM.

Syntax

Code
Import-BcTranslationMemory
    -Reference <Object[]>
    [-ContextAware <Boolean>]
    [-CacheDir <String>]
    [-NoCache]

Parameters

Output

PSCustomObject { ContextAware, Count, Entries (hashtable key -> { Target, Origin, Priority }) }.

---

Install-Bc365App

Installs one or more 365 business development apps into a Business Central container.

Installs 365 business development dependency apps (by app id) into a build container using the 365 business development app installer. The installer script is downloaded inside the container and run with the requested app ids; it resolves and installs each app for the container's BC version. Requires Windows + a running Docker engine. Native replacement for the V1 Install365App task.

Syntax

Code
Install-Bc365App
    -Name <String>
    -AppId <String[]>
    [-InstallerUrl <String>]
    [-DockerExecutable <String>]

Parameters

Output

PSCustomObject: Container, AppId, InstallerUrl.

Examples

Example 1

Code
Install-Bc365App -Name bld -AppId '0f94d4ef-5c3a-4002-93f2-2a2be05219c0'

---

Install-BcAlTool

Ensures the cross-platform AL Tool CLI is installed (as a .NET global tool) and on PATH.

Installs 'Microsoft.Dynamics.BusinessCentral.Development.Tools' as a dotnet tool so the 'al' command (which wraps the AL compiler, alc) is available to Invoke-BcCompiler's AlTool engine on a build agent. Requires the .NET SDK ('dotnet').

VERSION MATTERS. The AL Tool's MAJOR version is the AL runtime it can compile (17.x -> runtime 17 = BC28, 18.x -> runtime 18 = BC29); a compiler older than the app's declared runtime fails with AL1043 ("The runtime version 'x' is not supported by the AL compiler"). Pass -BcVersion (or -RuntimeVersion) and the required version is derived and resolved for you - including the PRERELEASE compiler that is the only one available while a BC major is still in preview (NextMajor). See Resolve-BcAlToolVersion.

Given a required runtime, the tool is installed into a PER-VERSION folder under the ALbuild base cache (--tool-path) instead of the machine-wide global tool. Build agents run several stages (Current / NextMinor / NextMajor) against different BC majors, often concurrently, and a single global tool cannot serve them: one stage would silently re-point the compiler of another - and a shipping product would get built by a beta compiler. The per-version folder is reused across builds, so this costs one download per runtime major per agent.

Idempotent: an AL Tool that already satisfies the requirement is left alone (unless -Force). Without any version requirement the historical behaviour is unchanged - a global install that no-ops whenever some 'al' is already resolvable - and after installing, the global-tools folder is added to PATH for the current session.

Syntax

Code
Install-BcAlTool
    [-PackageId <String>]
    [-Version <String>]
    [-BcVersion <String>]
    [-RuntimeVersion <String>]
    [-Prerelease <String>]
    [-ToolPath <String>]
    [-Global]
    [-Force]
    [-Source <String>]
    [-DotNetExecutable <String>]

Parameters

Output

PSCustomObject: Installed (bool), Path, Version, RequiredRuntimeMajor, Prerelease, ToolPath.

Examples

Example 1

Code
Install-BcAlTool

Example 2

Code
Install-BcAlTool -BcVersion '29.0.53586.0'
# BC29 -> AL runtime 18 -> the newest 18.x AL Tool (a '-beta' while BC29 is in preview),
# installed side by side under <base>\altool\<version>.

---

Install-BcAzureSignTool

Syntax

Code
Install-BcAzureSignTool
    [-PackageId <String>]
    [-Version <String>]
    [-Force]
    [-Source <String>]
    [-DotNetExecutable <String>]

Parameters

---

Install-BcContainerApp

Installs a published AL app in a Business Central container.

Syntax

Code
Install-BcContainerApp
    -Name <String>
    -AppName <String>
    [-AppVersion <String>]
    [-ServerInstance <String>]
    [-Tenant <String>]
    [-DockerExecutable <String>]

Parameters

---

Install-BcContainerDependency

Publishes and installs an AL project's resolved dependency apps into a container, in dependency order.

The runtime counterpart to compile-time symbol resolution: an app can only be installed and tested once the apps it depends on are installed. This stages the .app packages found in -PackageFolder into the container's shared folder, then - inside the container - reads each package with Get-NAVAppInfo (which handles both regular and encrypted runtime packages, unlike a host-side ZIP reader), orders them so each app is published after the apps it depends on, and publishes/synchronises/installs each. Apps already installed (e.g. Microsoft first-party / the toolkit) are skipped; dependencies outside the set are assumed already present. Requires Windows + Docker.

Syntax

Code
Install-BcContainerDependency
    -Name <String>
    [-PackageFolder <String[]>]
    [-PackageFile <String[]>]
    [-ServerInstance <String>]
    [-SkipVerification <Boolean>]
    [-OperationTimeoutSeconds <Int32>]
    [-DockerExecutable <String>]

Parameters

Output

System.String lines describing what was installed/skipped.

---

Invoke-BcAppSigning

Signs one or more AL .app files using AzureSignTool and an Azure Key Vault certificate.

Signs the given .app file(s) with AzureSignTool, authenticating to Key Vault with a service principal. When AzureSignTool is not on PATH it is auto-installed as a .NET global tool (as ALbuild V1 did); pass -SkipAutoInstall to require a pre-installed tool, or -SignToolPath to point at a specific executable.

Syntax

Code
Invoke-BcAppSigning
    -Path <String[]>
    -KeyVaultUrl <String>
    -TenantId <String>
    -ClientId <String>
    -ClientSecret <String>
    -CertificateName <String>
    [-TimestampUrl <String>]
    [-SignToolPath <String>]
    [-SkipAutoInstall]

Parameters

Examples

Example 1

Code
Invoke-BcAppSigning -Path .\out\*.app -KeyVaultUrl $url -TenantId $t -ClientId $c -ClientSecret $s -CertificateName $name

---

Invoke-BcCompiler

Compiles an AL project into an .app package.

Compiles an AL project using either the cross-platform AL compiler (default) or a container's compiler: -Engine AlTool (default) invokes the AL compiler executable (alc) on the host. Symbols are taken from the package cache (.alpackages), which Resolve-BcDependencies populates; the AL compiler does not download dependencies itself. -Engine Container runs the compiler inside a Business Central container via the exec seam. The output file name follows the BC convention "<publisher><name><version>.app", derived from app.json.

Syntax

Code
Invoke-BcCompiler
    -ProjectFolder <String>
    [-OutputFolder <String>]
    [-Engine <String>]
    [-CompilerPath <String>]
    [-ContainerName <String>]
    [-ContainerCompilerPath <String>]
    [-PackageCachePath <String[]>]
    [-Analyzer <String[]>]
    [-RuleSet <String>]
    [-AssemblyProbingPath <String[]>]
    [-LogLevel <String>]
    [-BuildBy <String>]
    [-BuildUrl <String>]
    [-SourceRepositoryUrl <String>]
    [-SourceCommit <String>]
    [-DockerExecutable <String>]
    [-NoDiagnosticOutput]

Parameters

Output

PSCustomObject with Success, OutputFile, ExitCode, Output.

Examples

Example 1

Code
Invoke-BcCompiler -ProjectFolder ./app

---

Invoke-BcContainerTest

Runs AL tests in a Business Central container and collects/parses the results.

ALbuild's built-in AL test runner. It drives the AL Test Tool page inside the container (no BcContainerHelper) and produces a JUnit/XUnit result file that is copied to the host, parsed into a summary, and optionally used to fail the build.

Test apps are taken from -ProjectFolder (every AL test app found is run) or from an explicit -ExtensionId list. For folder-based discovery the optional ALbuild 'pipeline.config' beside each app.json is honoured: its 'alTestRunnerId' selects the test-runner codeunit. The runner codeunit otherwise defaults to 130450 (test isolation) or, with -DisableIsolation, 130451 (isolation disabled); an explicit -TestRunnerCodeunitId overrides everything.

For advanced scenarios a custom in-container invocation can still be supplied via -TestExecution (a script block that writes the result file to $ResultPathInContainer); when given, ALbuild only collects and parses the result and does not use the built-in runner.

Syntax

Code
Invoke-BcContainerTest
    -Name <String>
    [-ProjectFolder <String>]
    -ExtensionId <String[]>
    -TestExecution <ScriptBlock>
    [-Credential <PSCredential>]
    [-TestSuite <String>]
    [-TestRunnerCodeunitId <Int32>]
    [-DisableIsolation]
    [-Tenant <String>]
    [-CompanyName <String>]
    [-Culture <String>]
    [-Auth <String>]
    [-AzureDevOps]
    [-ResultPath <String>]
    [-ResultPathInContainer <String>]
    [-FailOnTestFailure]
    [-CodeCoverageTrackingType <String>]
    [-CodeCoverageMap <String>]
    [-CodeCoveragePath <String>]
    [-DockerExecutable <String>]

Parameters

Output

PSCustomObject with Passed, Failed, Skipped, Total, Failures, Success, ResultPath.

Examples

Example 1

Code
Invoke-BcContainerTest -Name bld -ProjectFolder $env:BUILD_REPOSITORY_LOCALPATH -FailOnTestFailure

Example 2

Code
Invoke-BcContainerTest -Name bld -ExtensionId '5e8c2f...' -Credential $cred -AzureDevOps

---

Invoke-BcTranslationSync

Syncs a project's target-language XLFs from its generated .g.xlf and fills them from the translation memory (the orchestration behind albuild translation sync).

For each target language: locates the generated base file (<App>.g.xlf, from the AL compiler's TranslationFile feature) and the target XLF under the project's translations folder, runs Sync-BcTranslation (structural merge), then - unless -NoMemory - builds a prioritised translation memory (Import-BcTranslationMemory) from the configured sources and applies it (Merge-BcTranslationMemory). Deterministic and offline: only exact TM matches are filled; the rest stay needs-translation for a downstream consumer.

Sources (priority: self > sibling apps > BC base):

• self: the app's own *.<lang>.xlf (highest)
• xlf: a path/glob to other apps' XLFs (from albuild.json translation.memory.sources)
• bc-base: Microsoft Base/System Application <lang> XLFs, resolved from the BC artifact cache of the project's target application version (best-effort: skipped with a warning when not present in the cache - never triggers a download).

With -Check nothing is written: each language is synced into a temp copy and compared to the committed XLF; a difference is reported as drift (for the CI 'check' pipeline mode).

Syntax

Code
Invoke-BcTranslationSync
    -ProjectFolder <String>
    [-WorkspaceRoot <String>]
    [-Language <String[]>]
    [-BaseFile <String>]
    [-DetectSourceChanges <Boolean>]
    [-NoMemory]
    [-Check]

Parameters

Output

PSCustomObject { skipped?, translationsFolder, baseFile, languages: [ { language, targetFile, added, kept, adapted, tm { filled, skipped, byOrigin }, drift? } ] }.

---

Invoke-BcValidation

Validates an AL app by compiling it against one or more Business Central versions (licensed).

For each target Business Central artifact, creates a temporary container, compiles the app (optionally with analyzers/ruleset such as AppSourceCop for AppSource submissions), records the outcome, and removes the container. This catches version-compatibility and analyzer issues before submission. A valid ALbuild license is required.

Symbols are expected in the project's .alpackages (resolve them first with Resolve-BcDependencies). Analyzer assemblies must be passed by path via -Analyzer.

Syntax

Code
Invoke-BcValidation
    -ProjectFolder <String>
    [-ArtifactUrl <String[]>]
    [-Country <String>]
    [-Select <String[]>]
    [-Credential <PSCredential>]
    [-Analyzer <String[]>]
    [-RuleSet <String>]
    [-DockerExecutable <String>]

Parameters

Output

PSCustomObject with Success and per-version Results.

---

Merge-BcCodeCoverage

Merges raw Business Central coverage (.dat) from several runs into one dataset (union, max hits per line).

Parallel/sharded test runs each emit their own coverage .dat files. This unions them by (Object, Line), keeping the highest hit count seen for each line, and writes a single merged .dat in BC's VariableText CSV shape (ObjectType,ObjectID,LineNo,Status,Hits) that Convert-BcCodeCoverage / Get-BcCodeCoverageSummary can consume. Status is written as 0 (Covered) because BC only ever exports executed lines.

Syntax

Code
Merge-BcCodeCoverage
    -CoveragePath <String[]>
    -OutputPath <String>

Parameters

Output

PSCustomObject: OutputFile, ObjectCount, LineCount.

---

Merge-BcTranslationMemory

Fills untranslated units in a target XLIFF from a translation-memory index (deterministic, exact).

For each unit still in a needs-translation / needs-adaptation state (or with an empty target), looks up the index built by Import-BcTranslationMemory: first the context-sensitive "GenNote|source" key, then the plain "source" key. On an exact match it writes the <target>, sets state="translated", and records the origin in an auditable note (<note from-tool='albuild-tm'> origin=<self|app:...|bc-base></note>). Units without a match are left untouched (needs-translation) so a downstream consumer can translate the true new strings. No fuzzy matching, no LLM.

Syntax

Code
Merge-BcTranslationMemory
    -Path <String>
    -Index <PSObject>

Parameters

Output

PSCustomObject { filled, skipped, byOrigin (hashtable origin -> count), file }.

---

New-BcTranslationFile

Creates a new AL XLIFF target-language file from a generated base file.

Clones the generated base XLIFF (.g.xlf), sets the target language, and marks every unit needs-translation, producing a ready-to-translate target file.

Syntax

Code
New-BcTranslationFile
    -BaseFile <String>
    -TargetLanguage <String>
    [-OutputPath <String>]

Parameters

Output

System.String - the created file path.

Examples

Example 1

Code
New-BcTranslationFile -BaseFile .\App.g.xlf -TargetLanguage de-DE

---

Publish-BcAppToDevEndpoint

POSTs an .app to a Business Central development service endpoint (the VS Code 'Publish' mechanism).

Uploads the .app as multipart/form-data to a '<devUrl>/dev/apps' endpoint with HTTP Basic auth, which publishes + synchronises + installs it as a development (ModernDev) extension - replaceable without a version bump. Mirrors ALbuild V1 / BcContainerHelper -useDevEndpoint. Kept as its own function so callers can resolve the URL however they like (e.g. a container's IP) and so it is mockable in tests.

Syntax

Code
Publish-BcAppToDevEndpoint
    -Url <String>
    -AppFile <String>
    -Credential <PSCredential>
    [-IgnoreSslErrors]

Parameters

---

Publish-BcContainerApp

Publishes an AL app (.app) to a Business Central container, optionally syncing/installing.

Copies the .app into the container and publishes it with the BC server management cmdlets, then optionally synchronises and installs it. Requires Windows + Docker.

Syntax

Code
Publish-BcContainerApp
    -Name <String>
    -AppFile <String>
    [-SkipVerification]
    [-Sync]
    [-Install]
    [-SyncMode <String>]
    [-Scope <String>]
    [-ServerInstance <String>]
    [-Tenant <String>]
    [-OperationTimeoutSeconds <Int32>]
    [-DockerExecutable <String>]
    [-Development]
    [-Credential <PSCredential>]

Parameters

---

Publish-BcTestinyResult

Publishes a JUnit test result file to Testiny via the Testiny importer CLI.

Uploads AL test results (a JUnit XML file, e.g. the one produced by Invoke-BcContainerTest) to Testiny using the official Testiny importer command-line tool. The importer is taken from -ImporterPath if supplied, otherwise downloaded and extracted from -ImporterUrl. Native replacement for the V1 PublishTestResultsTestiny task. For standard pipeline reporting use the built-in Azure DevOps PublishTestResults task instead; this is for teams that mirror results into Testiny.

Syntax

Code
Publish-BcTestinyResult
    -ResultsFile <String>
    -ApiKey <String>
    -ProjectId <String>
    [-RunId <String>]
    [-Format <String>]
    [-ImporterUrl <String>]
    [-ImporterPath <String>]

Parameters

Output

PSCustomObject: ResultsFile, ProjectId, RunId.

Examples

Example 1

Code
Publish-BcTestinyResult -ResultsFile .\TestResults.xml -ApiKey $key -ProjectId '42'

---

Resolve-BcAnalyzerConfig

Determines the code analyzers and ruleset for a compile, layering the sources by precedence.

Precedence (highest first): an explicit value (the task input) > the project's albuild.json (Analyzers / RuleSet) > the project's .vscode/settings.json ('al.codeAnalyzers' / 'al.ruleSetPath'). Only the highest source that supplies a value is used (the sources do not merge), matching how an explicit pipeline input overrides committed config. Analyzer entries are returned as given (tokens / short names / DLL paths - Resolve-BcAnalyzer maps them at compile time); a relative ruleset path is resolved against the project folder.

Syntax

Code
Resolve-BcAnalyzerConfig
    -ProjectFolder <String>
    [-WorkspaceRoot <String>]
    [-InputAnalyzers <String>]
    [-InputRuleSet <String>]

Parameters

Output

PSCustomObject: Analyzers (string[]), RuleSet (string), AnalyzersSource, RuleSetSource.

---

Set-BcAppVersion

Sets the version of one or more Business Central apps by updating their app.json.

Updates the top-level "version" field of every app.json found under -Path (recursively, excluding symbol/package folders) - or a single app.json if -Path points directly at one. The new version is either an explicit -Version or computed from a token -Schema applied to each app's current version (see the schema tokens below). The version value is rewritten in place with a targeted text replacement so the rest of the file (ordering, indentation, comments-as-properties) is preserved; only the top-level version value changes.

Schema tokens (one per dotted position, case-insensitive): a number = literal; 'increment' = current component + 1; 'build-id' = the -BuildId value; 'no-of-commits' = the repository's git commit count; 'date' = today's date as yyyyMMdd; 'major'/'minor'/'build'/'revision'/ 'latest'/'keep' = keep the current component. Example: 'major.minor.increment.0' or the V1-style 'major.no-of-commits.build-id.date'.

The 'no-of-commits' token reads the git commit count from the repository, and 'date' reads the current date; both are computed once per call (stable across all apps stamped in that call). Apart from that (and the -OnlyUpdateOnChangedSource change check) this cmdlet only reads/writes app.json. Use Invoke-BcBuildVersionStamp for the pipeline-level "stamp + claim a build branch" flow.

Syntax

Code
Set-BcAppVersion
    [-Path <String>]
    [-Schema <String>]
    -Version <String>
    [-BaseVersion <Version>]
    [-BuildId <String>]
    [-OnlyUpdateOnChangedSource]

Parameters

Output

PSCustomObject per app: AppJsonPath, AppFolder, PreviousVersion, NewVersion, Changed, Skipped.

Examples

Example 1

Code
Set-BcAppVersion -Path . -Schema 'major.minor.build-id.0' -BuildId $env:BUILD_BUILDID

Example 2

Code
Set-BcAppVersion -Path .\app -Version '2.3.0.0'

---

Set-BcTranslationUnit

Sets the target text (and state) of a single translation unit in an AL XLIFF file.

The supported, auditable single-unit write path behind albuild translation set - no raw XML editing. Selects the unit by id or by exact source text, writes the <target>, and sets its state: 'translated' (a completed translation) or 'needs-work' (mapped to the XLIFF 'needs-adaptation' state). Namespace-agnostic (XLIFF 1.2/2.0) via the shared Get-BcXliffUnit reader.

Syntax

Code
Set-BcTranslationUnit
    -Path <String>
    [-Id <String>]
    [-Source <String>]
    -Target <String>
    [-State <String>]

Parameters

Output

PSCustomObject { id, source, target, state, file }.

---

Start-BcContainerAppDataUpgrade

Runs the data upgrade for a published AL app version in a Business Central container.

When a tenant already holds data written by an EARLIER version of an app, installing the new version is refused - BC requires the app's upgrade codeunits to migrate that data first. That is Start-NAVAppDataUpgrade, and it is the step 'Install-NAVApp' tells you about only after failing: "an earlier version was already installed. Run Start-NAVAppDataUpgrade".

Publish and sync the new version first (Publish-BcContainerApp -Sync, without -Install), then call this. It replaces the install for that version: a successful data upgrade leaves the app installed at the new version.

Syntax

Code
Start-BcContainerAppDataUpgrade
    -Name <String>
    -AppName <String>
    [-AppVersion <String>]
    [-ServerInstance <String>]
    [-Tenant <String>]
    [-DockerExecutable <String>]

Parameters

Examples

Example 1

Code
Start-BcContainerAppDataUpgrade -Name albmcp01480a -AppName '365 business Banking' -AppVersion 18.4.0.0

---

Sync-BcContainerApp

Synchronises a published AL app's schema in a Business Central container.

Syntax

Code
Sync-BcContainerApp
    -Name <String>
    -AppName <String>
    [-AppVersion <String>]
    [-Mode <String>]
    [-ServerInstance <String>]
    [-Tenant <String>]
    [-DockerExecutable <String>]

Parameters

---

Sync-BcTranslation

Synchronises an AL XLIFF target file from a generated base file (.g.xlf).

Merges the translation units of the generated base file into the target file, preserving existing translations by matching units using a prioritised, multi-pass strategy:

1. by id
2. by Xliff-Generator note + source
3. by Xliff-Generator note + Developer note
4. by Xliff-Generator note
5. by source + Developer note
6. by source New units are added (untranslated); units removed from the base are dropped. When -DetectSourceChanges is set (default), a translation whose source text changed is marked needs-adaptation. The result is written back to the target file (XLIFF 1.2).

Syntax

Code
Sync-BcTranslation
    -BaseFile <String>
    -TargetFile <String>
    [-DetectSourceChanges <Boolean>]

Parameters

Examples

Example 1

Code
Sync-BcTranslation -BaseFile .\App.g.xlf -TargetFile .\App.de-DE.xlf

---

Test-BcAppBreakingChange

Checks an AL app for breaking changes against the baseline declared in its AppSourceCop.json.

AppSource breaking-change validation. If the project has an AppSourceCop.json with a "version" token, this:

1. looks for the committed baseline app of that version in the repository (<publisher><name><version>.app);
2. if the baseline is NOT committed, writes a warning and PROCEEDS without checking (Checked = $false) - you can't compare against a baseline you don't have;
3. if it IS committed, compiles the app with the AppSourceCop analyzer against that baseline (the AL compiler emits AS-rule breaking-change diagnostics when the baseline app is present in the package cache and AppSourceCop.json carries the version) and reports them.

Symbols for the compile come from -PackageCachePath (default <ProjectFolder>/.alpackages); the baseline app is added to a temporary copy of that cache so the real .alpackages is untouched.

Syntax

Code
Test-BcAppBreakingChange
    -ProjectFolder <String>
    [-Version <String>]
    [-SearchRoot <String>]
    [-PackageCachePath <String[]>]
    [-Analyzer <String>]
    [-CompilerPath <String>]
    [-SkipCommittedCheck]

Parameters

Output

PSCustomObject: Checked, Version, BaselineCommitted, BaselineFile, Diagnostics, BreakingChanges, Success, Message.

---

Test-BcCodeCoverageThreshold

Gates a build on code-coverage thresholds -- overall and (optionally) per object.

Evaluates ALbuild coverage data (raw *.dat + workspace, or an existing coverage-summary.json) against a minimum overall line-coverage percentage and an optional per-object floor. Returns a verdict object ({ passed, lineCoverage, minLineCoverage, belowMinimum[], offenders[] }) and, with -ThrowOnFailure, throws so a pipeline step fails. Honest by construction: it uses the source-based denominator, so a suite that merely executes every covered line does not pass a real threshold.

Syntax

Code
Test-BcCodeCoverageThreshold
    -CoveragePath <String>
    [-WorkspaceRoot <String>]
    [-DenominatorMode <String>]
    -SummaryPath <String>
    -MinLineCoverage <Double>
    [-MinObjectLineCoverage <Double>]
    [-ThrowOnFailure]

Parameters

Output

PSCustomObject verdict.

---

Test-BcTranslation

Checks AL XLIFF translation files for missing and "needs-work" translations.

A CI gate for translations. For each XLIFF file it reports units with a missing translation (no/empty target, the configured missing placeholder, or a needs-translation/-adaptation state) and units that fail the technical needs-work rules (placeholder mismatch, option member count, consecutive spaces, source=target for same-language files). Use -FailOnIssue to fail the build when any issue is found.

Syntax

Code
Test-BcTranslation
    -Path <String[]>
    [-MissingPlaceholder <String>]
    [-SkipNeedsWork]
    [-FailOnIssue]

Parameters

Output

PSCustomObject per issue (File, UnitId, Type, Message).

Examples

Example 1

Code
Test-BcTranslation -Path ./app/Translations -FailOnIssue

---

Uninstall-BcContainerApp

Uninstalls an AL app in a Business Central container.

Syntax

Code
Uninstall-BcContainerApp
    -Name <String>
    -AppName <String>
    [-AppVersion <String>]
    [-ServerInstance <String>]
    [-Tenant <String>]
    [-Force]
    [-DockerExecutable <String>]

Parameters

---

Unpublish-BcContainerApp

Unpublishes an AL app from a Business Central container.

Syntax

Code
Unpublish-BcContainerApp
    -Name <String>
    -AppName <String>
    [-AppVersion <String>]
    [-ServerInstance <String>]
    [-DockerExecutable <String>]

Parameters

---

Update-BcAppManifest

Prepares an AL app manifest (app.json) for a target BC version: version features + preprocessor symbols.

Restores the pipeline's V1 "update manifest" behaviour for a compile against a specific BC version (a normal build against Latest, or a runtime package built for an older platform). Two adjustments, both keyed to -BcVersion:

• Version features (port of Apply-BcVersionFeatures): set 'application' and 'platform' to '<major>.0.0.0' and 'runtime' to the target's AL runtime version. The runtime is '(major - 11).0' for BC >= 12 (17->6.0, 22->11.0, 28->17.0, ...), with the BC 18.1+ -> 7.1 special case; this keeps working for future majors (V1 stopped at 26/27). Skipped with -SkipVersionFeatures (then only the preprocessor symbols are written).

• Preprocessor symbols: 'BC<min>'..'BC<target>', where 'min' is -MinMajor when given, otherwise the app's 'application' major read BEFORE the version-feature rewrite, plus any -PreprocessorSymbols. This lets version-conditional AL ('#if BC24 ... #endif') compile.

Any existing 'preprocessorSymbols' array is REPLACED, never read and never extended. The committed array belongs to the repository and may hold internal symbols (DEBUG, ONPREM) that must not reach a published app, so it is not treated as input - not even its BC entries. That also means the function cannot recover the original floor from it after it has stamped once: where a manifest may be stamped repeatedly, the caller remembers the baseline and passes -MinMajor.

Operates on a single app.json or every app.json under a folder (skipping .alpackages / output). Rewrites the file in place (build workspace); use before Invoke-BcCompiler.

Syntax

Code
Update-BcAppManifest
    -Path <String>
    -BcVersion <String>
    [-PreprocessorSymbols <String[]>]
    [-MinMajor <Int32>]
    [-SkipVersionFeatures]

Parameters

Output

PSCustomObject per app.json: AppJsonPath, MinMajor, TargetMajor, Runtime, Symbols.

Examples

Example 1

Code
Update-BcAppManifest -Path .\app -BcVersion '28.3.52162.52455'

---