2.2: AL Configuration Files: app.json & launch.json Parameters

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

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
}

1. 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.
2. 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.
3. 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:

[!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   |
                        +---------------------------+

1. CodeCop: Validates language syntax, naming conventions, formatting, and performance best practices (e.g., missing keys on SetCurrentKey).
2. AppSourceCop: Enforces strict AppSource certification requirements: mandatory 3-character publisher affixes, backward compatibility of public procedures/fields, and proper ObsoleteState lifecycle management.
3. PerTenantExtensionCop: Checks Per-Tenant Extensions (PTE) for cloud compliance (e.g., forbidding direct file access or hardcoded company credentials).
4. 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.