Copy page

PowerShell Module

OnPrem module

Module: businessdev.ALbuild.OnPrem  •  Tier: Licensed  •  Cmdlets: 8

The OnPrem module publishes, installs, synchronizes and upgrades apps on Business Central On-Premises environments, and publishes Per-Tenant Extensions (PTE) and Dev extensions. This is a licensed feature.

Cmdlets in this module

---

Install-BcOnPremApp

Installs a published AL app on an on-premises Business Central server instance (licensed).

Syntax

Code
Install-BcOnPremApp
    -ServerInstance <String>
    -AppName <String>
    [-AppVersion <String>]
    [-Tenant <String>]

Parameters

---

New-BcApiAuthContext

Acquires an OAuth2 access token for the Business Central API.

Acquires a bearer token for the Business Central REST / automation API from Azure AD using one of three flows, selected by the parameters you pass:

• ClientSecret - service-to-service (client_credentials) with an app-registration secret.
• Certificate - service-to-service (client_credentials) with a signed client_assertion JWT. The signing certificate lives in Azure Key Vault and its private key never leaves the vault (a service principal reads the public certificate and performs the RS256 signature via the Key Vault key 'sign' operation).
• RefreshToken - exchanges an OAuth2 refresh token (ALbuild V1 parity).

Returns an auth context whose AccessToken is passed to Publish-BcPerTenantExtension (or any other Business Central API cmdlet).

Syntax

Code
New-BcApiAuthContext
    [-TenantId <String>]
    -ClientId <String>
    -ClientSecret <Object>
    -RefreshToken <Object>
    -KeyVaultUrl <String>
    -CertificateName <String>
    [-KeyVaultTenantId <String>]
    -KeyVaultClientId <String>
    -KeyVaultClientSecret <Object>
    [-Scope <String>]

Parameters

Output

PSCustomObject with AccessToken, TokenType, ExpiresOn, TenantId, ClientId, Scope.

Examples

Example 1

Code
$ctx = New-BcApiAuthContext -TenantId $t -ClientId $c -ClientSecret $s
Publish-BcPerTenantExtension -TenantId $t -Environment 'Production' -AccessToken $ctx.AccessToken -AppFile .\out\My.app

Example 2

Code
$ctx = New-BcApiAuthContext -TenantId $t -ClientId $appRegId -KeyVaultUrl $kv -CertificateName 'bc-deploy' `
    -KeyVaultClientId $sp -KeyVaultClientSecret $spSecret

---

Publish-BcDevExtension

Publishes an AL app to a Business Central server's development endpoint (licensed).

Uploads the .app to the BC development service endpoint (the same endpoint VS Code uses for 'Publish'), which publishes, synchronises and installs the app in one call. Requires a valid ALbuild license.

Syntax

Code
Publish-BcDevExtension
    -DevServerUrl <String>
    -ServerInstance <String>
    -AppFile <String>
    -Credential <PSCredential>
    [-SchemaUpdateMode <String>]
    [-DependencyPublishingOption <String>]

Parameters

---

Publish-BcOnPremApp

Publishes an AL app to an on-premises Business Central server instance (licensed).

Publishes the .app to the given server instance using the Business Central management cmdlets, optionally synchronising and installing it. Run on a host where the BC management module is available (the BC server or a deployment agent). Requires a valid ALbuild license.

Syntax

Code
Publish-BcOnPremApp
    -ServerInstance <String>
    -AppFile <String>
    [-SkipVerification]
    [-Sync]
    [-Install]
    [-SyncMode <String>]
    [-Scope <String>]
    [-Tenant <String>]
    [-Development]
    [-Credential <PSCredential>]
    [-DevServerUrl <String>]

Parameters

---

Publish-BcOnPremContainerApp

Publishes an AL app to a Business Central server instance running inside a Docker container (licensed).

The on-prem counterpart to Publish-BcOnPremApp for deployments where the target BC server runs inside a Docker container on the deployment host (the ALbuild V1 "Release On-Prem" scenario with a container name supplied). The .app is copied into the container and published, synchronised and installed with the in-container BC management cmdlets. Requires Windows + Docker on the agent and a valid ALbuild license.

Use Publish-BcOnPremApp when the BC server is installed directly on the host; use this cmdlet when it runs in a container.

Syntax

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

Parameters

Examples

Example 1

Code
Publish-BcOnPremContainerApp -ContainerName 'bcprod' -AppFile .\out\My.app -Sync -Install

Example 2

Code
Publish-BcOnPremContainerApp -ContainerName 'bc-test' -AppFile .\out\My.app -Development -Credential $cred

---

Publish-BcPerTenantExtension

Deploys a per-tenant extension to a Business Central environment via the automation API (licensed).

Uploads and schedules one or more per-tenant extensions using the Business Central automation API extensionUpload entity: create an upload record, PATCH the .app binary into it, then trigger the upload action. A bearer access token for the environment is required (acquire one with New-BcApiAuthContext, which supports S2S client-secret, certificate and refresh-token authentication).

The target environment can be given either as a ready automation API base URL (-AutomationBaseUrl) or, more conveniently, as -TenantId + -Environment (the URL is then built for you). When -CompanyId is omitted the first company in the environment is used. One or more .app files (or a folder of them) can be published in a single call.

Syntax

Code
Publish-BcPerTenantExtension
    -TenantId <String>
    -Environment <String>
    -AutomationBaseUrl <String>
    [-CompanyId <String>]
    -AppFile <String[]>
    -AccessToken <String>
    [-SchemaSyncMode <String>]
    [-Schedule <String>]
    [-IncludeTestApp]
    [-NoWait]
    [-TimeoutMinutes <Int32>]

Parameters

Examples

Example 1

Code
$ctx = New-BcApiAuthContext -TenantId $t -ClientId $c -ClientSecret $s
Publish-BcPerTenantExtension -TenantId $t -Environment 'Production' -AccessToken $ctx.AccessToken -AppFile .\out

Example 2

Code
Publish-BcPerTenantExtension -AutomationBaseUrl $url -CompanyId $id -AppFile .\out\My.app -AccessToken $token

---

Start-BcOnPremUpgrade

Runs the data-upgrade for an AL app on an on-premises Business Central server instance (licensed).

Syntax

Code
Start-BcOnPremUpgrade
    -ServerInstance <String>
    -AppName <String>
    [-AppVersion <String>]
    [-Tenant <String>]

Parameters

---

Sync-BcOnPremApp

Synchronises an AL app's schema on an on-premises Business Central server instance (licensed).

Syntax

Code
Sync-BcOnPremApp
    -ServerInstance <String>
    -AppName <String>
    [-AppVersion <String>]
    [-Mode <String>]
    [-Tenant <String>]

Parameters

---