3.2 Extension Deployment & Schema Synchronization Modes

3.2 Extension Deployment & Schema Synchronization Modes

Deploying extensions to Microsoft Dynamics 365 Business Central requires aligning compiled AL packages (.app files) with the target environment's application server and underlying relational database schema. Because Business Central applications manage mission-critical enterprise data, the AL platform enforces strict schema synchronization rules to prevent data corruption and unintentional data loss.

---

1. Extension Deployment Channels & Deployment Architecture

There are four distinct deployment channels for Business Central extensions, each designed for specific environments and operational tiers:

The PowerShell Deployment Pipeline (On-Premises & Docker)

For on-premises installations and automated CI/CD container environments, extension deployment follows a mandatory three-step PowerShell lifecycle:

# Step 1: Publish the extension package to the server instance
Publish-NAVApp -ServerInstance BC240 -Path "C:\Apps\ContosoCustomization_1.0.0.0.app" -SkipVerification

# Step 2: Synchronize the extension schema with the tenant database
Sync-NAVApp -ServerInstance BC240 -Tenant default -Name "Contoso Customization" -Version 1.0.0.0 -Mode Synchronize

# Step 3: Install the extension on the target tenant
Install-NAVApp -ServerInstance BC240 -Tenant default -Name "Contoso Customization" -Version 1.0.0.0

• Publish-NAVApp: Uploads the compiled .app binary into the Business Central Server's application metadata store. The extension becomes known to the server but is not yet active on any tenant.
• Sync-NAVApp: Reconciles table definitions in the extension with the physical SQL Server database schema for the specified tenant.
• Install-NAVApp: Activates the extension for users on the specified tenant, running install codeunits (Subtype = Install) and binding event subscribers.

---

2. Schema Synchronization Modes in Detail

When deploying extensions from Visual Studio Code or running Sync-NAVApp, the schemaUpdateMode property in launch.json dictates how the platform handles differences between the existing SQL database schema and the updated AL table definitions.

{
  "name": "Cloud Sandbox - ForceSync Development",
  "type": "al",
  "request": "launch",
  "environmentType": "Sandbox",
  "environmentName": "DevSandbox",
  "schemaUpdateMode": "ForceSync"
}

The Three Synchronization Modes

1. Synchronize (Default / Additive)

• Behavior: Strictly validates that all changes made to tables and table extensions are additive or backward-compatible.
• Allowed Modifications: Adding new tables, adding new fields to existing tables/table extensions, adding secondary keys, widening string/code fields (e.g., Text[50] to Text[100]), and changing field captions.
• Prohibited Modifications: Removing fields, decreasing field lengths, changing field data types, deleting tables, or removing primary key fields.
• Failure Handling: If any destructive change is detected, synchronization terminates with a runtime schema validation error, and deployment aborts with zero data loss.
• Production Availability: Yes. This is the only mode used during routine cloud production deployments.

2. Recreate (Drop and Rebuild — Sandbox Only)

• Behavior: Completely drops all physical SQL tables belonging to the extension and recreates fresh, empty tables matching the current AL source code.
• Data Impact: Total data destruction for all tables declared in the extension. Base application tables and tables from other extensions remain unaffected.
• Use Case: Rapid early-stage development when developers frequently redesign table structures, change primary keys, or refactor data models and do not require existing test data.
• Production Availability: Strictly Blocked. The Business Central SaaS platform rejects any deployment attempt with schemaUpdateMode = Recreate targeting production.

3. ForceSync (Destructive Schema Alignment)

• Behavior: Compares the new AL table definitions with the current database schema and forces the database to match the new definitions, even if destructive modifications exist.
• Data Impact: Deletes columns and permanently wipes data residing in removed fields, truncated fields (shortened strings), or modified data types. Intact fields retain their data.
• Use Case: Iterative development where a developer wants to delete or modify specific experimental fields without wiping the entire database table.
• Production Availability: Strictly Blocked in SaaS Production. Permitted only in Sandbox environments and on-premises development instances.

3. Safe vs. Destructive Schema Modifications

Understanding which modifications are classified as safe versus destructive is essential for passing the MB-820 exam and maintaining operational stability in enterprise environments.

---

4. Deploying Per-Tenant Extensions (PTE) in Production

When deploying a Per-Tenant Extension (.app) to a live production environment via the Extension Management page (Page 2500):

1. The administrator uploads the compiled .app package.
2. The administrator selects the deployment target version: Current version (deploys immediately to the active platform release) or Next minor / Next major version (schedules deployment during the next scheduled platform update).
3. The platform validates the extension using the PTE Analyzer and schema validator. If any breaking schema changes or missing dependencies are detected, the deployment task fails without altering the live tenant database.
4. An asynchronous background worker executes the installation, runs Install codeunits, and completes the activation without taking the system offline.

Exam Warning: If an extension containing destructive schema changes must be deployed to Production, developers cannot use ForceSync. Instead, they must follow the Deprecation Lifecycle: retain the obsolete fields marked with ObsoleteState = Removed, create new fields, transfer data via an Upgrade codeunit, and delete references gracefully.