2.1: Development Environment Setup: VS Code, AL: Go! Projects & Sandboxes

2.1: Development Environment Setup: VS Code, AL Language Extension & Sandboxes

Developing modern extensions for Microsoft Dynamics 365 Business Central requires configuring Visual Studio Code with the official AL Language extension, establishing connections to target development environments, and managing compiled symbol packages. The MB-820 exam rigorously tests your ability to set up development environments, select appropriate deployment topologies (Cloud Sandboxes vs. Docker Containers), configure authentication protocols, and troubleshoot symbol resolution failures.

---

1. The AL Development Architecture & Visual Studio Code Toolchain

Modern Business Central development is completely decoupled from the base application source code. Instead of modifying core objects directly (as in legacy C/AL Dynamics NAV), developers build modular, standalone extensions compiled into .app binary packages using Visual Studio Code and the AL Language extension.

  +-----------------------------------------------------------------------+
  |                     Visual Studio Code (IDE)                          |
  |  +--------------------+  +--------------------+  +-----------------+  |
  |  | AL Language Ext.   |  | Static Analyzers   |  | User Settings   |  |
  |  | (alc.exe Compiler) |  | (CodeCop, AppSrc)  |  | (settings.json) |  |
  |  +--------------------+  +--------------------+  +-----------------+  |
  |           |                        |                       |          |
  |           +------------------------+-----------------------+          |
  |                                    |                                  |
  |                     Abstract Syntax Tree (AST)                        |
  +-----------------------------------------------------------------------+
                                       |
                   +-------------------+-------------------+
                   |                                       |
                   v                                       v
     +---------------------------+           +---------------------------+
     |   Local Symbol Cache      |           |    AL Deployment Target   |
     |      (.alpackages)        | <=======> |   (Port 7049 / Dev API)   |
     | - Microsoft_System.app    |  Symbols  | - SaaS Cloud Sandbox      |
     | - Microsoft_BaseApp.app   |  & Deploy | - Local Docker Container  |
     +---------------------------+           +---------------------------+

Core Toolchain Components

1. Visual Studio Code: The cross-platform integrated development environment (IDE) that hosts AL development tools, configuration files, and extension workspaces.
2. AL Language Extension (ms-dynamics-smb.al): The official extension providing:
   • The AL compiler (alc.exe) for generating .app files.
   • Language Server Protocol (LSP) for IntelliSense, code navigation, syntax highlighting, and hover documentation.
   • Integrated debugging engine for attaching to active client sessions and stepping through AL code.
   • Built-in static code analyzers (CodeCop, AppSourceCop, PerTenantExtensionCop, UICop).
3. AL Extension Installation Methods:
   • Visual Studio Code Marketplace: The standard distribution channel for cloud sandbox development. Installing from the marketplace ensures automatic updates to the latest production language server.
   • Direct VSIX File Installation: When developing against local Docker containers or on-premises servers running specific cumulative updates (CUs) or legacy runtimes, developers must install the exact matching ALLanguage.vsix file extracted directly from the container or installation media (http://<container-name>:8080/ALLanguage.vsix) to prevent compiler/runtime mismatches.

Key VS Code Settings for AL

Developers configure development behaviors in .vscode/settings.json at the user, workspace, or folder level:

---

2. Development Target Environments: Cloud Sandboxes vs. Docker Containers

Choosing the right development topology is a critical architectural decision in Business Central projects. The MB-820 exam tests scenarios where developers must decide between a Cloud Sandbox (SaaS) and a Local Docker Container (via BcContainerHelper).

SaaS Cloud Sandboxes

Cloud sandboxes are provisioned through the Business Central Admin Center. Each production environment can have up to three active sandboxes at no additional licensing cost (with additional capacity purchasable).

• Production Snapshot: Administrators can copy production company data into a sandbox environment to test customizations against real-world customer data.
• Automated Updates: Sandboxes automatically receive major (Wave 1 / Wave 2) and minor monthly updates before production, enabling proactive regression testing.
• Constraints: Developers cannot run destructive table schema synchronization (Recreate), cannot use .NET Interoperability (target: "OnPrem"), and cannot access the underlying SQL database directly.

Local Docker Containers via BcContainerHelper

For rapid development, continuous integration (CI/CD), and heavy schema refactoring, local Docker containers orchestrated via the BcContainerHelper PowerShell module are the industry standard.

# Installing the modern container helper module
Install-Module -Name BcContainerHelper -Scope CurrentUser -Force

# Provisioning a local development container targeting 2024 Wave 1
$artifactUrl = Get-BCArtifactUrl -version "24.0" -country "us" -select "Latest"
$credential = New-Object System.Management.Automation.PSCredential("admin", (ConvertTo-SecureString "P@ssword123!" -AsPlainText -Force))

New-BcContainer `
    -containerName "BC24Dev" `
    -artifactUrl $artifactUrl `
    -credential $credential `
    -auth "UserPassword" `
    -updateHosts `
    -includeTestToolkit `
    -enableSymbolLoading `
    -doNotExportObjectsToText

Key New-BcContainer Parameters for the MB-820 Exam:

• -artifactUrl: Specifies the exact platform and application build version artifact downloaded from Microsoft Container Registry (MCR).
• -auth: Defines the authentication protocol (UserPassword vs Windows).
• -includeTestToolkit: Pre-installs Microsoft Test Runner, Test Libraries (Any, Library - Assert), and CAL Test Runner required for automated testing.
• -enableSymbolLoading: Configures the Business Central Server instance (NST) to generate and publish symbols for all base and system extensions, allowing VS Code to download them.
• -updateHosts: Automatically updates the host hosts file to resolve the container name to its internal IP address.

---

3. Symbol Management & Symbol Download Mechanics

In AL, compilation relies entirely on symbols. Symbols are compiled metadata packages (.app files containing object signatures, variables, triggers, procedures, and XML documentation) that represent the platform and dependent applications.

  +------------------------------------------------------------------+
  |                   AL Project / .alpackages Folder                |
  +------------------------------------------------------------------+
                                   |
         +-------------------------+-------------------------+
         |                         |                         |
         v                         v                         v
  +--------------------+    +--------------------+    +--------------------+
  |  Microsoft_System  |    | Microsoft_BaseApp  |    |  Dependent Apps    |
  |  (Core Platform)   |    | (Standard Business |    |  (Custom ISV /     |
  | - Tables (2000000) |    |  Tables, Pages,    |    |   Core Libraries)  |
  | - Codeunits (1..)  |    |  Codeunits, Posts) |    | - Tables, Events   |
  +--------------------+    +--------------------+    +--------------------+

The Three Standard Symbol Packages

1. Platform / System symbols (Microsoft_System.app): The package referenced by the "platform" property in app.json. It contains the platform-level objects — system tables in the 2000000000 range, Codeunit 1-era system methods, and the built-in AL data types. 1b. System Application (Microsoft_System Application.app): A separate application package containing the modular technical services — cryptography, email, Azure AD authentication, JSON/XML/Base64 helpers, telemetry, and the Guided Experience. It is open source on GitHub (microsoft/BCApps).
2. Base Application (Microsoft_Base Application.app): Contains the core business functionality: Sales, Purchasing, General Ledger, Inventory, Fixed Assets, and Manufacturing.
3. Application (Microsoft_Application.app): A lightweight composite package that bundles the System and Base Application dependencies into a single reference for standard cloud extensions.

Downloading Symbols in VS Code

To retrieve symbols from the target server into the project's .alpackages folder:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
2. Execute AL: Download Symbols.
3. VS Code queries the endpoint defined in launch.json via TCP port 7049 (Development Service port) or the SaaS developer endpoint.
4. Downloaded .app files are written to the directory specified by al.packageCachePath.

Symbol Diagnostics & Troubleshooting Guide

---

4. Authentication Protocols & Identity Flows

When Visual Studio Code connects to Business Central to download symbols or publish an extension, it authenticates according to the authentication setting in launch.json.

  SaaS Cloud Sandbox Authentication (OAuth2 DeviceCode Flow):
  
  [ VS Code (Developer) ]  ---- 1. Request Symbols / Publish ---->  [ BC Cloud Sandbox ]
           |                                                              |
           |<--- 2. Returns Device Code & URL (devicelogin) --------------+
           |
  [ Developer Browser ]   ---- 3. Signs in via Microsoft Entra ID ---->   [ Microsoft Entra ID ]
           |
           +------------------ 4. Issues OAuth2 Access Token ---------->  [ BC Developer Service ]
                                                                          [ Session Established ]

Authentication Modes Comparison

1. Microsoft Entra ID (DeviceCode Flow):
   • Mandatory for Microsoft Dynamics 365 Business Central SaaS Cloud Sandboxes.
   • Flow: VS Code generates a unique alphanumeric code and prompts the developer to navigate to https://microsoft.com/devicelogin. The developer enters the code in a browser and authenticates with their Microsoft 365 / Entra ID corporate credentials.
   • Tokens are cached locally in the developer's secure OS credential store until expiration.
2. UserPassword (NavUserPassword):
   • Standard for local Docker development containers and test VMs.
   • Uses basic username and password stored in the container's SQL database, transmitted over encrypted TLS.
3. Windows (NTLM / Kerberos):
   • Used in on-premises enterprise environments where developer workstations and Business Central NST servers reside within the same Active Directory domain.

5. Creating and Modifying an Extension Project in Visual Studio Code

Every Business Central extension starts as an AL project scaffolded by the AL Language extension. The MB-820 blueprint explicitly tests "create or modify a Business Central extension in Visual Studio Code", so you must know the scaffolding command, the files it generates, and the publish shortcuts by name.

Scaffolding a New Project with AL: Go!

1. Open an empty folder in Visual Studio Code (or use the Create AL Project button that appears in the Explorer side bar when no folder is open).
2. Press Alt+A followed immediately by Alt+L, or open the Command Palette with Ctrl+Shift+P and run AL: Go!.
3. Choose the target platform version, then pick the server type — Microsoft cloud sandbox, Your own server, or a Docker container.
4. Sign in when prompted. For a cloud sandbox this triggers the Microsoft Entra ID DeviceCode flow described earlier.

AL: Go! generates a complete, compilable project:

Building, Publishing and Iterating

Exam Watchout — Modifying vs. Creating: "Modifying" a Business Central extension never means editing Microsoft source. It means adding tableextension, pageextension, reportextension, enumextension, or permissionsetextension objects to your project and republishing. Use the t-prefixed snippets (ttable, tpage, tcodeunit, ttableext, tpageext) to scaffold each object, and keep every new object inside the idRanges declared in app.json.

Version note: From runtime 15.0 the Alt+A, Alt+P shortcut scaffolds a Copilot (or Copilot test) project template instead of the plain Hello World sample. From runtime 16.0 an in-progress publish can be cancelled from the dialog in the lower-right corner of Visual Studio Code.