15.4 AL Analyzers: CodeCop, AppSourceCop, UICop & PTECop

15.4 AL Analyzers: CodeCop, AppSourceCop, UICop & PTECop

Static code analysis is an essential phase of the Business Central software development lifecycle. Built upon the .NET Roslyn compiler framework, AL static code analyzers continuously evaluate source code to enforce coding best practices, verify UI design guidelines, detect breaking schema changes, and ensure compliance with Microsoft AppSource marketplace certification requirements.

1. The Four Official AL Static Code Analyzers

Microsoft provides four specialized code analyzers bundled directly inside the AL Language extension for Visual Studio Code and the AL compiler (alc.exe).

+-----------------------------------------------------------------------+
|                      AL SOURCE CODE COMPILATION                       |
|                         (.al Object Files)                            |
+-----------------------------------┬-----------------------------------+
                                    │ (Roslyn Static Analysis Pipeline)
                                    ▼
+-----------------------------------------------------------------------+
|                   THE 4 OFFICIAL AL CODE ANALYZERS                    |
|                                                                       |
|   1. CodeCop (${CodeCop})                                             |
|      - General AL code quality, syntax formatting, unused variables.  |
|                                                                       |
|   2. AppSourceCop (${AppSourceCop})                                   |
|      - AppSource certification, prefix/suffix, breaking changes.      |
|                                                                       |
|   3. UICop (${UICop})                                                 |
|      - Web Client UI standards, mandatory ToolTips, Promoted Actions. |
|                                                                       |
|   4. PerTenantExtensionCop (${PerTenantExtensionCop})                 |
|      - Per-tenant safety, target on-prem blocks, schema validation.   |
+-----------------------------------┬-----------------------------------+
                                    │ (Filtered by ruleset.json)
                                    ▼
+-----------------------------------------------------------------------+
|                 COMPILER DIAGNOSTICS & BUILD GATES                    |
|   - VS Code Problems Panel (Real-Time Squiggles & Tooltips)           |
|   - CI/CD Azure DevOps / GitHub Actions Automated Build Pipeline      |
|   - Microsoft Partner Center AppSource Technical Ingestion Gate       |
+-----------------------------------------------------------------------+

1. CodeCop (${CodeCop})

• Primary Purpose: General AL code quality, styling conventions, and language best practices.
• Key Diagnostics:
  • AA0005: Only use BEGIN..END to enclose compound statements.
  • AA0008: Flags function calls that omit required parentheses (e.g., Customer.FindSet instead of Customer.FindSet()).
  • AA0137: Flags declared local or global variables that are never used in code.
  • AA0205: Variables must be initialized before usage.
  • AA0207: The EventSubscriber method must be local. (Variable shadowing is covered by AA0198.)

2. AppSourceCop (${AppSourceCop})

• Primary Purpose: Enforces technical rules required for publishing solutions to Microsoft AppSource, maintaining public API stability, and preventing breaking schema changes.
• Key Diagnostics:
  • AS0011: An affix is required — enforces the registered 3-to-4 character prefix or suffix on object names, table fields, page actions, and enum values. (AS0079 extends this to procedures on extension objects; AS0013 is a different rule — The field identifier must be within the allowed range.)
  • AS0001: Tables and table extensions that have been published must not be deleted. (Pages are covered by AS0029, table renames by AS0006.)
  • AS0002: Fields must not be deleted. (Length reductions are AS0080; length increases are AS0086.)
  • AS0004: Fields must not change type, since dependent extensions may break. (Primary-key field changes are AS0009.)
  • AS0018: A procedure belonging to the public API cannot be removed. (Signature changes are AS0024; return-type changes are AS0023.)

3. UICop (${UICop})

• Primary Purpose: Validates user experience and user interface standards for the modern Business Central Web Client.
• Key Diagnostics:
  • AW0005: Actions should use the Image property. (Missing ToolTips are a CodeCop concern — AA0218 / AA0220.)
  • AW0006: Pages and reports should use the UsageCategory and ApplicationArea properties to be searchable.
  • AW0013: Groups containing promoted actions should not be hidden. (AW0014 does the same for groups containing actionref targets.)
  • AW0010: A Repeater control used on a List page must be defined at the beginning of the area(Content) section.

4. PerTenantExtensionCop (${PerTenantExtensionCop})

• Primary Purpose: Validates extensions intended exclusively for deployment as Per-Tenant Extensions (PTE) in a specific customer tenant.
• Key Diagnostics:
  • PTE0001: Object ID must be in free range. (The "target": "OnPrem" restriction for SaaS is PTE0005.)
  • PTE0002: Field ID must be in free range.
  • PTE0004: Table definitions must have a matching permission set.

2. Comprehensive Analyzer Comparison Matrix

3. Enabling Analyzers in Visual Studio Code

Analyzers are enabled and configured in the project's .vscode/settings.json file. Developers can activate individual analyzers or run all four concurrently:

{
  "al.enableCodeAnalysis": true,
  "al.codeAnalyzers": [
    "${CodeCop}",
    "${AppSourceCop}",
    "${UICop}",
    "${PerTenantExtensionCop}"
  ],
  "al.backgroundCodeAnalysis": "Project",
  "al.ruleSetPath": "./ruleset.json",
  "al.enableCodeActions": true
}

Baseline Package Configuration for AppSourceCop

To detect breaking changes between versions, AppSourceCop must compare the active workspace code against the previously published .app baseline package. This is configured in settings.json:

{
  "al.assemblyProbingPaths": [
    "./.netpackages"
  ],
  "AppSourceCop.baselinePackage": "./baselines/Contoso.Logistics_23.0.0.0.app"
}

4. Managing Rules with ruleset.json

Projects can customize analyzer diagnostic behaviors using a ruleset.json file. A ruleset allows teams to elevate specific warnings to fatal compilation errors, downgrade errors to informational notices, or suppress false positives.

{
  "name": "Contoso Enterprise Ruleset",
  "description": "Enforces strict AppSource compliance while suppressing local casing warnings.",
  "includedRuleSets": [
    {
      "action": "Default",
      "path": "./company.ruleset.json"
    }
  ],
  "rules": [
    {
      "id": "AA0137",
      "action": "Error",
      "justification": "Unused variables must be treated as fatal compilation errors to maintain clean code."
    },
    {
      "id": "AA0218",
      "action": "Error",
      "justification": "All page fields and actions must have ToolTips for user onboarding."
    },
    {
      "id": "AA0072",
      "action": "Hidden",
      "justification": "Type-suffix naming is suppressed during the initial migration phase."
    },
    {
      "id": "AS0011",
      "action": "Error",
      "justification": "Strict enforcement of registered publisher prefix 'CONT_'."
    }
  ]
}

Supported Rule Actions

• Error: Elevates the diagnostic to a fatal compilation error, blocking the .app build.
• Warning: Emits a warning diagnostic in the VS Code Problems panel and build logs.
• Info: Displays an informational tip in the IDE without failing strict warning-free builds.
• Hidden: Diagnostic is calculated internally by the language server but hidden from the user interface.
• None: Completely disables the analyzer rule calculation.