Study guide
2.2: AL Configuration Files: app.json & launch.json Parameters
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.2: AL Configuration Files: app.json & launch.json Parameters
Key Takeaways Explain This Topic AI
app.json serves as the extension manifest, defining unique GUID identity, name, publisher, semantic version, runtime level, target platform (Cloud vs OnPrem), and object ID ranges.
The idRanges property restricts which object IDs can be authored within the extension; declaring an object outside these intervals is a fatal compilation error.
The resourceExposurePolicy in app.json governs intellectual property protection through three critical boolean flags: allowDebugging, allowDownloadingSource, and includeSourceInSymbolFile.
launch.json specifies environment connectivity, deployment targets, and schemaUpdateMode (Synchronize for safe non-destructive migration vs Recreate for rapid Docker resetting).
ruleset.json customizes compiler code analysis rules across CodeCop, AppSourceCop, UICop, and PerTenantExtensionCop, allowing teams to elevate specific warnings to fatal compilation errors.
Last updated: August 2026
2.2: AL Configuration Files: app.json & launch.json Parameters
Every AL extension project relies on declarative JSON configuration files to govern compilation, deployment, debugging, intellectual property protection, and static code analysis. For the MB-820 certification, developers must possess an exhaustive understanding of app.json , launch.json , and ruleset.json , including all key properties, validation rules, security flags, and behavioral differences across cloud and on-premises environments.
1. The Extension Manifest: app.json Anatomy & Parameters
The app.json file resides at the root of every AL project and acts as the extension's manifest . It defines the extension's unique identity, minimum platform dependencies, target deployment environment, object ID allocation, intellectual property exposure policies, and localization capabilities. {
- "id": "7a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
- "name": "Contoso Warehouse Advanced",
- "publisher": "Contoso Logistics Inc.",
- "version": "2.4.100.0",
- "brief": "Advanced warehouse bin tracking and scanning",
- "description": "Comprehensive warehouse tracking extension with 2D barcode scanning and zone optimization.",
- "privacyStatement": "https://www.contoso.com/privacy",
- "EULA": "https://www.contoso.com/eula",
- "help": "https://www.contoso.com/help/warehouse",
- "url": "https://www.contoso.com",
- "contextSensitiveHelpUrl": "https://www.contoso.com/help/warehouse/{0}",
- "showMyCode": false,
- "runtime": "13.0",
- "target": "Cloud",
- "platform": "24.0.0.0",
- "application": "24.0.0.0",
- "idRanges": [
- {
- "from": 50100,
- "to": 50149
- }
- ],
- "resourceExposurePolicy": {
- "allowDebugging": true,
- "allowDownloadingSource": false,
- "includeSourceInSymbolFile": false
- },
- "features": [
- "TranslationFile",
- "GenerateCaptions",
- "NoImplicitWith"
- ],
- "dependencies": [
- {
- "id": "e8a1d2c3-b4a5-6789-0123-456789abcdef",
- "name": "Contoso Core Framework",
- "publisher": "Contoso Logistics Inc.",
- "version": "1.2.0.0"
- }
- ],
- "internalsVisibleTo": [
- {
- "id": "99b1c2d3-e4f5-6789-0123-abcdef012345",
- "name": "Contoso Warehouse Test Suite",
- "publisher": "Contoso Logistics Inc."
- }
- ],
- "supportedCountries": [ "US", "CA", "GB" ]
- }
- Comprehensive Property Reference for app.json
Property Type Mandatory? Description & Exam Critical Details
id GUID Yes The immutable globally unique identifier of the extension. Never change the id across versions, as doing so treats the update as an entirely new extension, causing data loss.
name string Yes The unique display name of the extension.
publisher string Yes The authoring company name. The combination of id , name , and publisher defines the extension identity.
version string Yes Semantic version formatted as Major.Minor.Build.Revision (e.g., 2.4.100.0 ). Deploying an update requires incrementing this version.
runtime string Optional AL runtime language version (e.g., 11.0 for BC 22, 12.0 for BC 23, 13.0 for BC 24, 14.0 for BC 25). Controls available language syntax and compiler rules.
target enum Optional (defaults to Cloud ) "Cloud" (default) or "OnPrem" . "Cloud" enforces SaaS sandboxing rules (no .NET Interop, no direct file system access). "OnPrem" unlocks .NET interop and local OS calls.
idRanges array Yes (or idRange ) Array of integer range blocks ( from / to ) defining permissible object IDs. Creating an object outside these ranges raises a compilation error. Use either idRange or idRanges ; overlapping ranges are rejected.
resourceExposurePolicy object Recommended Replaces legacy showMyCode . Governs intellectual property protection via debugging, source downloading, and symbol generation flags.
features array Optional Compiler feature toggles. The supported values are "TranslationFile" (generates .xlf files), "GenerateCaptions" , "GenerateLockedTranslations" , and "NoImplicitWith" (turns off implicit with ). Mandatory AppSource affixes are configured in AppSourceCop.json ( mandatoryAffixes ), not here.
dependencies array Optional Array of upstream extensions required for compilation and execution.
internalsVisibleTo array Optional Grants specific friend extensions (e.g., automated test apps) access to internal procedures and tables marked Access = Internal .
Intellectual Property Protection: resourceExposurePolicy
In legacy AL, intellectual property was controlled via the coarse boolean "showMyCode": true/false . Modern AL replaces this with the granular resourceExposurePolicy object: "resourceExposurePolicy": {
- "allowDebugging": true,
- "allowDownloadingSource": false,
- "includeSourceInSymbolFile": false
- }
allowDebugging ( boolean ) :
true : Allows external developers and administrators to attach the VS Code debugger to step into this extension's code during troubleshooting.
false : Prevents debuggers from entering the extension's AL execution paths.
allowDownloadingSource ( boolean ) :
true : Enables administrators to download the full .app package containing raw source code from the Business Central web client Extension Management page.
false : Blocks raw source code package extraction.
includeSourceInSymbolFile ( boolean ) :
true : Embeds the original AL source code into generated symbol packages so dependent developers can use Go to Definition ( F12 ) to view complete method implementations.
false : Emits only public method signatures, variable declarations, and object definitions, hiding internal proprietary algorithms.
2. Environment Connection & Debugger Profiles: launch.json
The launch.json file resides inside the .vscode folder. It configures deployment targets, server connection parameters, credentials, browser launching behaviors, and database schema synchronization modes. {
- "version": "0.2.0",
- "configurations": [
- {
- "name": "Cloud Sandbox (SaaS)",
- "type": "al",
- "request": "launch",
- "environmentType": "Sandbox",
- "environmentName": "DevSandboxUS",
- "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db47",
- "authentication": "AAD",
- "schemaUpdateMode": "Synchronize",
- "startupObjectId": 21,
- "startupObjectType": "Page",
- "breakOnError": true,
- "breakOnRecordWrite": false,
- "launchBrowser": true,
- "enableLongRunningSqlStatements": true,
- "enableSqlInformationDebugger": true
- },
- {
- "name": "Local Docker Container",
- "type": "al",
- "request": "launch",
- "environmentType": "OnPrem",
- "server": "http://bc24dev",
- "serverInstance": "BC",
- "port": 7049,
- "authentication": "UserPassword",
- "schemaUpdateMode": "Recreate",
- "startupObjectId": 22,
- "startupObjectType": "Page",
- "breakOnError": true,
- "launchBrowser": true
- }
- ]
- }
- Schema Synchronization Modes ( schemaUpdateMode )
Understanding schemaUpdateMode is one of the most frequently tested concepts on the MB-820 exam:
Mode Behavior Data Impact Target Compatibility
Synchronize Non-destructive. Validates all table and field schema changes against existing database data. Fails if a change would cause data loss (e.g., shortening a Code[50] to Code[20] or dropping a field with data). Preserves Data (Safe) SaaS Cloud Sandboxes , Docker, On-Premises
Recreate Destructive. Drops all physical database tables associated with the extension and recreates them from scratch. All data in extension tables is wiped. Destroys All Extension Data Docker Containers & On-Premises ONLY (Strictly blocked on SaaS)
ForceSync Forced synchronization. Applies schema changes even if data loss occurs on altered columns, without dropping entire unaffected tables. Potential Partial Data Loss On-Premises & Docker ONLY (Blocked on SaaS)
Important
Attempting to publish an extension to a SaaS Cloud Sandbox with "schemaUpdateMode": "Recreate" or "ForceSync" will fail immediately with a platform deployment error. SaaS environments permit only "Synchronize" .
3. Static Code Analysis Governance: ruleset.json
Business Central includes four built-in static code analyzers to ensure code quality, platform safety, and AppSource certification compliance: +-----------------------------------------------------------------------+
- | AL Static Code Analyzers |
- +-----------------------------------------------------------------------+
- | | | |
- v v v v
- +------------+ +---------------+ +----------------+ +------------+
- | CodeCop | | AppSourceCop | | PerTenantExtCop| | UICop |
- | (Syntax & | | (Affixes & | | (PTE Cloud | | (Web UI & |
- | Patterns)| | Signatures) | | Restrictions)| | Actions) |
- +------------+ +---------------+ +----------------+ +------------+
- | | | |
- +------------------+----------+----------+------------------+
- |
- v
- +---------------------------+
- | ruleset.json |
- | - Promote Warning->Error |
- | - Suppress Legacy Rules |
- +---------------------------+
CodeCop : Validates language syntax, naming conventions, formatting, and performance best practices (e.g., missing keys on SetCurrentKey ).
AppSourceCop : Enforces strict AppSource certification requirements: mandatory 3-character publisher affixes, backward compatibility of public procedures/fields, and proper ObsoleteState lifecycle management.
PerTenantExtensionCop : Checks Per-Tenant Extensions (PTE) for cloud compliance (e.g., forbidding direct file access or hardcoded company credentials).
UICop : Validates user interface elements, ensuring pages include tooltips, captions, application areas, and responsive layouts.
Custom Ruleset Configuration
Teams configure custom ruleset files (referenced via "al.ruleSetPath": "./ruleset.json" in settings) to customize rule severity: {
- "name": "Contoso Enterprise Ruleset",
- "description": "Enforces zero-warning policy on AppSourceCop affixes while disabling legacy casing warnings.",
- "rules": [
- {
- "id": "AS0011",
- "action": "Error",
"justification": "All public objects and fields must have an approved 3-character publisher affix to prevent collision."
- },
- {
- "id": "AA0008",
- "action": "None",
- "justification": "Suppress the parenthesis-on-parameterless-calls check for legacy migration codeunits."
- },
- {
- "id": "AW0006",
- "action": "Warning",
"justification": "Warn when pages or reports omit UsageCategory/ApplicationArea and are therefore not searchable."
- }
- ]
- }
Rule Action Levels:
Error : Fails the build immediately. The extension will not compile into a .app package.
Warning : Emits a compiler warning in the Problems pane but allows compilation to proceed.
Info : Emits an informational notification.
Hidden : Keeps the diagnostic active in the IDE for background tools without visual squiggles.
None : Completely disables and suppresses the rule.