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
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, IsInstalledUpgrade 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.
Related Tools
Business Central AL Event Subscriber Generator
Builds an AL subscriber codeunit for any published event, with the correct attribute syntax and a procedure stub to fill in.
Microsoft DynamicsBusiness Central Go-Live Readiness Checklist
A cutover checklist for Business Central implementations covering opening balances, setup, security, integrations, training and fallback.
Developer ToolsBusiness Central OAuth Token Request Generator
Builds the client credentials token request for Business Central online plus sample REST and OData calls using the returned token.
ERP Migration & SelectionNAV to Business Central Data Migration Mapping Worksheet
Track each NAV table you plan to migrate, the target in Business Central, the method, volume and status, and total the effort.
More Microsoft Dynamics tools
See all- Business Central API v2.0 URL Builder
- Business Central Configuration Package Worksheet
- Business Central Permission Set Design Worksheet
- Business Central Year-End Close Checklist
- Business Central Posting Groups Setup Worksheet
- Business Central Data Migration Field Mapping Worksheet
- Business Central Chart of Accounts Mapping Worksheet
- Business Central Implementation Statement of Work Template
- Business Central Functional Design Document Template
New to Microsoft Dynamics NAV and Business Central on-prem? Start with the Microsoft Dynamics NAV and Business Central on-prem guide and toolkit.
Keep exploring
Free tools
- Business Central On-Prem Private AI Layer Blueprint GeneratorDescribe your Business Central on-prem setup and get an architecture plan for a private AI assistant built on API v2.0 and a local model.
- Business Central On-Prem AI Assistant Sizing and Value CalculatorSize GPUs, index and monthly value for a private AI assistant on Business Central on-prem from user and question volumes.
- Business Central Configuration Package WorksheetPlan the tables, load sequence and expected error counts for Business Central RapidStart configuration packages before you import.
ERP fixes and how-tos
- Upgrade to Business Central 25: How to Update SaaS and On-PremisesHow to upgrade to Business Central 25 (2024 release wave 2): SaaS update from the admin center, on-premises upgrade steps, extension checks and a test plan.
- Adding a Private AI Layer to Business Central On-PremisesAdd AI to Business Central on-prem without cloud: API v2.0, custom API pages, SQL replica, retrieval, local LLM, BC permission sets, approved write-back.
- Upgrade Business Central 14 to 27: Path, Work and Release UpdatesHow to plan a Business Central 14 to 27 upgrade: stepping stones, C/AL to AL extension work, release waves, process-only reports, Format time and MB-800.
AI on your ERP
- AI for Dynamics 365 Business Central in Discrete ManufacturingGrounded AI for Dynamics 365 Business Central discrete manufacturers: production orders, planning worksheets, routings and costing, on a private LLM.
- AI for Business Central manufacturing operations, beyond CopilotAI for Business Central manufacturing beyond Copilot: grounded answers on production orders, routings, and capacity via APIs v2.0, on-prem capable.
Integrations
- How to add document OCR to Microsoft Dynamics 365 Business CentralCapture vendor invoices, packing slips and certificates into Business Central with OCR, confidence thresholds, incoming documents and human review.
- How to add WhatsApp to Microsoft Dynamics 365 Business CentralHow to connect WhatsApp to Dynamics 365 Business Central: API v2.0 or custom API pages, webhooks, template messages, and two-way replies that post back safely.
Software
- Microsoft Dynamics 365 Business CentralDynamics 365 Business Central explained for manufacturers: modules, APIs, AL extensions, deployment, strengths, limits and alternatives for small and mid-size firms.
- Microsoft Dynamics 365 Finance and Supply ChainDynamics 365 Finance and Supply Chain Management explained for manufacturers: modules, data entities, OData, deployment, strengths, limits and alternatives.