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

Microsoft Dynamics 365 Business Central Developer MB-820

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Business Central Architecture & Platform Foundation

1.1 Business Central Architecture & Extensions Model 1.2 Customization Lifecycle: Cloud (SaaS) vs. On-Premises 1.3 Base Application, System Application & AppSource

2 Chapter 2: Development Environment & Configuration

2.1: Development Environment Setup: VS Code, AL: Go! Projects & Sandboxes 2.2: AL Configuration Files: app.json & launch.json Parameters 2.3: Multi-Root Workspaces & Project Dependencies

3 Chapter 3: Extension Lifecycle: Debugging, Deployment, Multilanguage & Maintenance

3.1 Debugging & Snapshot Debugging in Visual Studio Code 3.2 Extension Deployment & Schema Synchronization Modes 3.3 Multilanguage Development with XLIFF & Translation Files 3.4 Extension Maintenance, Deprecation & Breaking Changes

4 Chapter 4: Tables, Table Extensions & Data Modeling

4.1: Building Tables, Fields, Keys & Data Types 4.2: Table Extensions & Table Modifications 4.3: FlowFields, FlowFilters & Table Relations 4.4: Enums, Enum Extensions & Extensible Types

5 Chapter 5: Pages, Page Extensions & Role Centers

5.1: Page Types, Anatomy & Control Structure 5.2: Building Card, List & Document Pages 5.3: Page Extensions & Page Customizations 5.4: Role Centers, Headlines & Cue Data Modeling

6 Chapter 6: Reports & Document Generation

6.1 Report Architecture, DataItems & Dataset Design 6.2 Report Layouts: RDLC, Word, Excel & Multilanguage 6.3 Document Reports & Request Page Programming 6.4 Processing-Only Reports & Report Substitutions

7 Chapter 7: XMLports & Data Exchange

7.1 XMLport Architecture, Formats & Properties 7.2 XMLport Node Hierarchy, Triggers & Stream Manipulation

8 Chapter 8: Codeunits, Events, Triggers & Interfaces

8.1 Codeunit Types, Execution & SingleInstance Codeunits 8.2 Events, Publishers, Subscribers & Event Isolation 8.3 Interfaces, Polymorphism & Dynamic Codeunit Invocation 8.4 Installation & Upgrade Codeunits, Data Transfer & Archive

9 Chapter 9: Entitlements, Permissions & Queries

9.1 Permission Sets & Permission Set Extensions 9.2 Inherent Permissions, Inherent Entitlements & Security Scoping 9.3 Query Objects: Joins, Aggregation & Query as Report Data Source

10 Chapter 10: UI Customization, User Assistance & Onboarding

10.1 Profile Objects & Custom Page Views in AL 10.2 User Assistance: ToolTips, Teaching Tips & In-App Tours 10.3 Assisted Setup, Guided Experience & Onboarding Checklists

11 Chapter 11: Business Central Design Patterns & Data Process Model

11.1 Functional Table Types: Master Data, Supplemental & Setup Patterns 11.2 Document Standards: Header, Line, History & Journal Architectures 11.3 Data Process Model & Posting Routine Architecture

12 Chapter 12: AL Language Fundamentals, Data Types & Variables

12.1 AL Syntax, Variable Scope, Primitive & Complex Data Types 12.2 Expressions, Control Flow Statements & Built-in Functions 12.3 Access Modifiers (Public, Internal, Local) & Code Scoping

13 Chapter 13: Data Manipulation, Streams & Error Handling

13.1 Record Operations: Get, FindSet, ModifyAll & Filter Functions 13.2 Streams, File Management & TempBlob 13.3 Error Handling: ErrorInfo, TryFunctions & Collectible Errors

14 Chapter 14: Testing, Test Toolkit & Automation

14.1 Testing Architecture & the Test Toolkit 14.2 Authoring Test Codeunits & UI Handler Functions

15 Chapter 15: Telemetry, Performance Optimization & Analyzers

15.1 Telemetry Configuration & Azure Application Insights 15.2 Custom Telemetry Signals with Session.LogMessage & KQL 15.3 Performance Profiler, SetLoadFields & Query Optimization 15.4 AL Analyzers: CodeCop, AppSourceCop, UICop & PTECop

16 Chapter 16: REST Web Services & JSON in AL

16.1 HttpClient, HttpRequestMessage & REST API Consumption 16.2 JSON Processing: JsonObject, JsonArray, JsonValue & JsonToken

17 Chapter 17: API Pages, OData, Read Scale-Out & OAuth

17.1 API Pages (PageType=API), OData Web Services & REST Endpoints 17.2 Bound and Unbound OData Actions with [ServiceEnabled] 17.3 Read Scale-Out Architecture & DataAccessIntent Configuration 17.4 Microsoft Entra ID App Registrations & OAuth 2.0 Integration

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

Key Takeaways Explain This Topic AI

The AL: Go! command (Alt+A, Alt+L) scaffolds a new extension project containing app.json, .vscode/launch.json, rad.json, and a HelloWorld.al sample that deploys with Ctrl+F5.

Cloud Sandboxes provide managed SaaS environments authenticated via Microsoft Entra ID DeviceCode flow, while Docker containers managed via BcContainerHelper provide full administrative control, direct SQL access, and instant schema recreation.

The AL: Download Symbols command retrieves compiled metadata packages (.alpackages) for System, Base Application, and dependent extensions required for IntelliSense, type checking, and compilation.

Modern authentication for SaaS environments uses Microsoft Entra ID OAuth2 DeviceCode flow, whereas Docker and on-premises environments support UserPassword and Windows NTLM/Kerberos.

Symbol download errors typically result from mismatched runtime versions in app.json, unauthenticated Entra ID sessions, blocked developer service ports (7049), or missing upstream dependencies.

Last updated: August 2026

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

Visual Studio Code : The cross-platform integrated development environment (IDE) that hosts AL development tools, configuration files, and extension workspaces.

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 ).

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:

Setting Key Type Description & Exam Impact

al.enableCodeActions boolean Enables quick fixes and refactoring suggestions (e.g., adding missing tooltips or captions).

al.incrementalBuild boolean Recompiles only modified AL objects rather than the entire project, dramatically reducing build times.

al.packageCachePath string Path to the directory where downloaded symbol packages ( .alpackages ) are cached. Defaults to ./.alpackages .

al.codeAnalyzers array Array of active analyzer assemblies (e.g., "${AppSourceCop}" , "${CodeCop}" ).

al.compilationOptions object Compiler flags, such as "generateReportLayout": true for automated RDL/Word layout generation.

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 ).

Architecture Dimension SaaS Cloud Sandbox Local Docker Container
Hosting Model Microsoft Cloud (Multi-tenant SaaS) Local Host / Azure VM (Windows Container)
Management Tool Business Central Admin Center PowerShell ( BcContainerHelper module)
Identity & Auth Microsoft Entra ID (DeviceCode Flow) UserPassword (NavUserPassword) or Windows (NTLM)
Database Access No direct SQL access (AL / API only) Full SQL Server SA access & SQL Server Management Studio
Schema Reset No ( schemaUpdateMode: "Recreate" forbidden) Yes ( schemaUpdateMode: "Recreate" fully supported)
Production Copy Direct 1-click snapshot from Production Requires BACPAC export or database backup restore
Target Setting "target": "Cloud" (Mandatory) "target": "Cloud" or "target": "OnPrem"
Test Automation / CI Slower; rate-limited by cloud quotas Ideal for fast, isolated, automated CI/CD pipelines
Service Tier Settings Fully managed by Microsoft Full control over CustomSettings.config
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

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 ).

Base Application ( Microsoft_Base Application.app ) : Contains the core business functionality: Sales, Purchasing, General Ledger, Inventory, Fixed Assets, and Manufacturing.

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:

Open the Command Palette ( Ctrl+Shift+P / Cmd+Shift+P ).

Execute AL: Download Symbols .

VS Code queries the endpoint defined in launch.json via TCP port 7049 (Development Service port) or the SaaS developer endpoint.

Downloaded .app files are written to the directory specified by al.packageCachePath .

Symbol Diagnostics & Troubleshooting Guide

Symptom / Error Root Cause Resolution

Could not download symbols. The request failed with status code 400 (Bad Request) / Mismatched Runtime The "runtime" specified in app.json is higher than the runtime version supported by the target Business Central server instance. Lower the "runtime" version in app.json to match the target environment (e.g., change "13.0" to "12.0" ).

Cannot connect to server on port 7049 The Development Service port (7049) is blocked by a firewall or DeveloperServicesEnabled is set to false on the NST. Enable Developer Services in CustomSettings.config ( <add key="DeveloperServicesEnabled" value="true" /> ) and open port 7049 in Windows Firewall.

Authentication failed / Unauthorized (401) Expired OAuth DeviceCode token, wrong Entra ID tenant ID, or invalid UserPassword credentials. Run AL: Clear Credentials Cache from the Command Palette and re-authenticate via the DeviceCode prompt.

Cannot resolve symbol reference for dependency X The extension declared in app.json dependencies is not installed/published on the target server. Publish the missing dependency extension to the sandbox/container before downloading symbols.

IntelliSense displays outdated objects after symbol update Visual Studio Code in-memory LSP cache is holding stale symbol metadata. Execute AL: Clear Object Cache from the Command Palette and restart the AL Language Server.

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

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.

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.

Windows (NTLM / Kerberos) :

Used in on-premises enterprise environments where developer workstations and Business Central NST servers reside within the same Active Directory domain.

Loading diagram... AL Development Environment Connectivity & Symbol Resolution Flow

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!

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).

Press Alt+A followed immediately by Alt+L , or open the Command Palette with Ctrl+Shift+P and run AL: Go! .

Choose the target platform version, then pick the server type — Microsoft cloud sandbox , Your own server , or a Docker container.

AL: Go! generates a complete, compilable project:

Generated artifact Purpose

app.json The extension manifest: id , name , publisher , version , platform , application , idRanges , runtime , target .

.vscode/launch.json The deployment/debug profile pointing at the chosen environment. You have no launch.json until AL: Go! has run.

rad.json Rapid Application Development state file. It is generated and maintained by the tooling — never edit it by hand.

HelloWorld.al A sample pageextension on the Customer List that shows a message in the OnOpenPage trigger.

.alpackages The local symbol cache populated by AL: Download Symbols .

Building, Publishing and Iterating

Action Shortcut Command Palette name Effect

Publish without debugging Ctrl+F5 AL: Publish without debugging Compiles, uploads, and installs the .app , then launches the client.

Publish with debugging F5 AL: Publish Same as above but attaches the AL debugger to the new session.

Compile only Ctrl+Shift+B Tasks: Run Build Task Produces the .app package in the project root without deploying.

Rapid Application Development — AL: Publish without debugging (RAD) Publishes only changed objects using rad.json , shortening the inner loop on large projects.

Reset authentication — AL: Clear credentials cache Clears cached OAuth tokens so you can target a different environment.

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.