Microsoft DynamicsFree generatorPDF, Excel, Word exportMicrosoft Dynamics 365 Business Central

Business Central On-Premises Extension Deployment PowerShell Generator

Deploying an extension to an on-premises Business Central server is a short but order-sensitive sequence: publish, sync, then install or upgrade. This generator writes the sequence with your server instance, tenant and app details filled in.

Fill in

Server instance

Tenant

App file path

App name

Publisher

App version

Sync mode

Generated code

Download:

Install a new extension

# Run in the Business Central Administration Shell as an administrator
Import-Module "C:\Program Files\Microsoft Dynamics 365 Business Central\Service\Microsoft.Dynamics.Nav.Apps.Management.psd1"

Publish-NAVApp -ServerInstance "BC" -Path "C:\apps\Netray_Sample_1.0.0.0.app" -SkipVerification

Sync-NAVApp -ServerInstance "BC" -Tenant "default" -Name "Sample Extension" -Publisher "Contoso Partner" -Version "1.0.0.0" -Mode Add

Install-NAVApp -ServerInstance "BC" -Tenant "default" -Name "Sample Extension" -Publisher "Contoso Partner" -Version "1.0.0.0"

Get-NAVAppInfo -ServerInstance "BC" -Tenant "default" -TenantSpecificProperties | Where-Object { $_.Name -eq "Sample Extension" } | Format-Table Name, Version, IsInstalled

Upgrade to a new version

# Publish the new version first, then sync and run the data upgrade
Publish-NAVApp -ServerInstance "BC" -Path "C:\apps\Netray_Sample_1.0.0.0.app" -SkipVerification

Sync-NAVApp -ServerInstance "BC" -Tenant "default" -Name "Sample Extension" -Publisher "Contoso Partner" -Version "1.0.0.0"

Start-NAVAppDataUpgrade -ServerInstance "BC" -Tenant "default" -Name "Sample Extension" -Publisher "Contoso Partner" -Version "1.0.0.0"

Uninstall and unpublish

Uninstall-NAVApp -ServerInstance "BC" -Tenant "default" -Name "Sample Extension" -Publisher "Contoso Partner" -Version "1.0.0.0"

Unpublish-NAVApp -ServerInstance "BC" -Name "Sample Extension" -Publisher "Contoso Partner" -Version "1.0.0.0"

Run on the server hosting the service tier, in the Administration Shell. The module path depends on the installed version. Use -SkipVerification only for unsigned test apps, production apps should be signed. Test the upgrade branch on a copy of the database first and verify the cmdlet parameters with Get-Help for your Business Central version.

Upgrade rehearsal notes

Optionally ask for a second set of eyes on your upgrade and rollback plan.

Optional. The tool and every export work without this. No spam.

How to use the script

Enter your server instance name, tenant, the path to the compiled .app file and the app's name, publisher and version exactly as shown in app.json. Copy the first block for a new installation or the second block for a version upgrade. Run it in the Business Central Administration Shell on the server. The final Get-NAVAppInfo line confirms the version is installed.

Back up the tenant database before upgrades
Use the same name and publisher as app.json
Do not skip the sync step

What each cmdlet does

Publish-NAVApp loads the package into the server's app table. Sync-NAVApp applies table schema changes from the app to the SQL database for a tenant. Install-NAVApp makes the app active for that tenant. For upgrades, Start-NAVAppDataUpgrade runs the upgrade codeunits that move data from the old version's structure to the new one. Uninstall and unpublish remove the app and optionally its data.

Sync modes

The Add mode is the safe default and only allows non-destructive schema changes. Clean removes data in fields or tables that no longer exist and should be used knowingly. ForceSync allows destructive changes when you accept data loss. Development is used when deploying from Visual Studio Code in a sandbox. Choose the lowest-risk mode that works for the change.

Common mistakes

Forgetting the tenant parameter on a multi-tenant server leads to confusing results. Publishing a lower version than the one installed causes an error. Developers also try to install an app whose dependencies are not yet published, so publish Microsoft base apps and other dependencies first. Last, running the script in a normal PowerShell window without the module loaded results in cmdlet not found errors.

Frequently Asked Questions

Do I need Sync-NAVApp for every upgrade?

Yes. Sync applies the new schema to the tenant database. Without it the data upgrade step cannot move data because the new tables and fields do not exist yet. The order is publish, sync, then data upgrade.

Is this the same for Business Central online?

No. Online environments are managed through the Business Central admin center and the extension management page, and per-tenant extensions are uploaded from there. These cmdlets apply to on-premises service tiers.

What does -SkipVerification do?

It allows an unsigned package to be published. That is fine for development and test servers, but production extensions should be signed with a code signing certificate so the server can verify their origin.

Why are the cmdlets still named NAV?

Microsoft kept the NAV naming in the management module for compatibility. The cmdlets work with Business Central service tiers, so scripts from older NAV 2018 era deployments are often reusable with small changes.

For upgrade or migration projects we can help document and rehearse the deployment steps, and add an AI assistant that answers questions from your logs on-premises.

Talk to an Expert Explore More Free Tools

Related Tools

Developer Tools

More Microsoft Dynamics tools

See all

Back to All Tools