Step-by-Step Guide: Deploying .app Extensions in Dynamics 365 Business Central

To deploy Business Central extension code means to compile an AL-language project into a .app package file, publish it to a Business Central environment, and install it for the target tenant or company. This process replaces the legacy C/SIDE customization approach and is now the only Microsoft-supported method for extending Business Central functionality without modifying the base application.

When you deploy Business Central extension packages, your customizations are isolated in a separate layer from Microsoft's core code. This means Microsoft updates and hotfixes can be applied without overwriting your modifications — a critical improvement over older CAL-based customizations that frequently broke during upgrades.

Every extension is identified by its app.json manifest file, which defines the extension ID, version, publisher name, and dependency list. Two extensions with the same ID but different versions are treated as upgrade candidates, allowing you to push incremental changes to production environments without full reinstalls.

Before building a Business Central extension, you need Visual Studio Code with the AL Language extension published by Microsoft. This extension provides IntelliSense, syntax highlighting, and the AL: Publish command that packages and deploys your code to a connected Business Central environment. You also need a valid Business Central development or sandbox license and Docker (optional, for local container-based development).

The AL extension connects to Business Central environments through the launch.json configuration file, which specifies the server URL, authentication method, and tenant ID. For cloud environments (SaaS), you authenticate via Azure AD. For on-premises environments, you authenticate with Windows credentials or NavUserPassword authentication.

Additionally, your development machine must have the Business Central symbols downloaded — these are the metadata packages that describe all objects in the base application and any dependencies. Symbols are downloaded automatically when you run the "Download Symbols" command from VS Code, provided your license has sufficient permissions.

A well-structured AL project to deploy Business Central extension packages follows a consistent folder layout: a root-level app.json, a launch.json for environment connections, and separate folders for each object type — Tables, Pages, Reports, Codeunits, and Enumerations. Keeping objects organized by type makes the project easier to navigate and speeds up symbol resolution during compilation.

The app.json file is the most critical file in your extension project. It must define a unique ID (GUID), a consistent publisher name, and accurate dependency declarations for any base application objects or third-party extensions your code relies on. Version numbers follow semantic versioning (Major.Minor.Build.Revision), and each published extension must have a version number higher than the previously installed one to qualify as an upgrade.

Before you deploy Business Central extension files to production, always test in a sandbox environment first. Use the "AL: Publish" command in VS Code to push to the sandbox, verify functionality, run the built-in test runner, then package the final .app file for production deployment via the Business Central Administration Center or PowerShell scripts.

The Business Central Administration Center at businesscentral.dynamics.com provides a web-based interface for managing extensions across all your Business Central environments. Administrators can install extensions from AppSource, upload .app files directly, and view the extension health status for each tenant from a single dashboard.

To upload a per-tenant extension via the Admin Center, navigate to your environment, select "Extensions," and click "Upload Extension." Select the .app file generated by your AL build process and choose whether to deploy immediately or schedule deployment. The Admin Center validates the extension against the current Business Central version before installing, catching dependency mismatches before they affect users.

For organizations managing multiple Business Central tenants — common in ISV scenarios or multi-subsidiary deployments — PowerShell cmdlets from the Microsoft.Dynamics.Nav.Apps module provide scripted deployment workflows. This enables CI/CD pipelines in Azure DevOps to automatically build, test, and deploy Business Central extension packages as part of a structured release process. AlphaVima configures these pipelines for clients who require controlled, automated releases. For full reference documentation, see the Microsoft documentation on creating Business Central extensions.

The most common error when you deploy Business Central extension files is a dependency version mismatch. This occurs when your extension declares a dependency on a specific version of the base application or another extension that is not installed in the target environment. The fix is to align the dependency ranges in your app.json with the versions present in the target tenant — use minimum version declarations rather than exact matches where possible.

The second frequent issue is symbol mismatch after a Business Central update. When Microsoft releases a new platform version, some base application objects may change their signatures. If your extension references an object that was modified or removed, compilation fails. Regularly regenerating symbols and testing against the latest sandbox version catches these issues before they reach production.

The third common problem is permission conflicts during installation. If your extension creates new tables or modifies page permissions, the installing user must have the SUPER profile or a custom permission set that includes extension management rights. Our team at AlphaVima troubleshoots these errors regularly — visit our Power Platform development page and Copilot Studio services page for the full range of our Microsoft expertise.

Per-tenant extensions (PTEs) are custom .app files deployed to a single Business Central tenant — they are not available in Microsoft AppSource and do not go through Microsoft's certification process. PTEs are the standard approach for client-specific customizations built by partners like AlphaVima: bespoke workflows, custom integrations, industry-specific fields, and company-specific reporting layouts.

AppSource extensions, by contrast, are published through Microsoft's commercial marketplace and must pass a rigorous technical validation process. They are installable by any Business Central tenant worldwide and are managed by Microsoft through the AppSource catalog. ISVs building products for multiple customers must publish via AppSource if they want broad market distribution.

From a technical perspective, the AL development process is identical for PTEs and AppSource apps. The key differences are in the app.json configuration (AppSource apps require a specific publisher verification), the submission process (AppSource requires Partner Center enrollment), and the ongoing maintenance obligations (AppSource apps must stay compatible with every new Business Central release). AlphaVima builds both PTEs for clients and supports ISVs navigating the AppSource submission process.

Upgrading a deployed Business Central extension involves three steps: bumping the version number in app.json, writing upgrade codeunits if data migrations are needed, and publishing the new .app file to the target environment. The Business Central runtime detects that the new extension has a higher version number than the installed one and triggers the upgrade sequence automatically.

Upgrade codeunits (with SubType = Upgrade) contain the OnUpgradePerDatabase and OnUpgradePerCompany triggers that run data transformation logic — for example, migrating data from a renamed field to a new table structure. If your update only adds new fields or pages without changing existing data structures, no upgrade codeunit is required and the extension upgrades seamlessly.

For cloud (SaaS) environments, Microsoft applies Business Central updates automatically on a monthly schedule. Before each update, Microsoft runs automated compatibility tests against all installed per-tenant extensions using the new platform version. If your extension fails compatibility, Microsoft notifies the tenant administrator and delays the update until the extension is fixed or removed. Maintaining compatibility with upcoming versions is a key part of AlphaVima's managed support services.

AlphaVima Technologies is a Microsoft-certified Business Central partner based in Toronto, helping Canadian businesses design, build, and deploy Business Central extension projects from initial scoping through production go-live. Our AL developers bring experience across finance, distribution, manufacturing, and nonprofit sectors, building extensions that integrate with Dynamics 365 Sales, Power Platform, and Azure services.

Our Business Central extension engagements follow a structured delivery methodology: requirements workshop, architecture design, iterative development sprints with client demos, sandbox user acceptance testing, and production deployment with cutover support. Every extension we deliver includes documentation, test coverage, and a maintenance plan that addresses Business Central update compatibility proactively.

Whether you need a simple page customization, a complex integration with a third-party logistics system, or a full industry accelerator built on Business Central, AlphaVima has the technical depth to deliver. Explore our nonprofit CRM solutions to see how we customize Business Central for the nonprofit sector across Canada.