ALCops for Azure DevOps

Azure DevOps pipeline task for downloading ALCops code analyzers for AL Language of Microsoft Dynamics 365 Business Central.

Quick Start

steps:
  - task: ALCopsDownloadAnalyzers@1
    displayName: ALCops - Download Analyzers
    inputs:
      tfm: "net8.0" # Or use the detectUsing parameter instead of static value
      outputPath: "$(Build.SourcesDirectory)/.alcops"

Usage Examples

Auto-detect from BC Artifact URL

Pass a BC artifact URL and the TFM is detected automatically:

steps:
  - task: ALCopsDownloadAnalyzers@1
    displayName: ALCops - Download Analyzers
    inputs:
      detectUsing: "$(bcArtifactUrl)"

Auto-detect from NuGet DevTools version

steps:
  - task: ALCopsDownloadAnalyzers@1
    name: alcops
    inputs:
      detectUsing: "latest" # Latest or preview for beta/prelease releases
      detectFrom: "nuget-devtools" # Optional: Defaults to BC DevTools from NuGet, set to 'marketplace' for AL Language extension from VS Code Marketplace

Auto-detect from VS Marketplace version

Force a specific detection source with detectFrom:

steps:
  - task: ALCopsDownloadAnalyzers@1
    name: alcops
    inputs:
      detectUsing: "current"
      detectFrom: "marketplace"

Note: Both VSIX layouts of the AL Language extension are supported from @alcops/core 0.2.0: the flat extension/bin/ layout used by AL 18+ (BC 29) and the legacy extension/bin/Analyzers/ layout. Compiling with AL 18 additionally requires a .NET 10 runtime on the agent, since its binaries are framework-dependent net10.0. Installing that runtime is outside the scope of this task.

Auto-detect from Compiler Path

steps:
  - task: ALCopsDownloadAnalyzers@1
    name: alcops
    inputs:
      detectUsing: "$(Agent.ToolsDirectory)/bc-devtools/bin"

Specific ALCops version

steps:
  - task: ALCopsDownloadAnalyzers@1
    name: alcops
    inputs:
      tfm: "net8.0"
      version: "1.2.3"

Using Outputs

steps:
  - task: ALCopsDownloadAnalyzers@1
    name: alcops
    inputs:
      detectUsing: "latest"

  - script: echo "Downloaded $(alcops.version) with TFM $(alcops.tfm)"

  - script: |
      alc.exe /project:"$(Build.SourcesDirectory)" \
        /analyzer:"$(alcops.files)"

Task Reference

ALCopsDownloadAnalyzers

Download ALCops code analyzers with automatic TFM detection.

Inputs

Input	Default	Description
detectUsing	—	Input for TFM detection: BC artifact URL, local compiler path, NuGet DevTools version/channel, or VS Marketplace version. Smart routing determines the source.
detectFrom	(auto)	Force a detection source: bc-artifact, marketplace, nuget-devtools, compiler-path
tfm	—	Explicit target framework: net8.0, netstandard2.1, net10.0. Skips detection.
version	latest	ALCops version: latest, prerelease, or specific (e.g., 1.2.3)
outputPath	$(Build.SourcesDirectory)/.alcops	Where to place extracted analyzer DLLs

Note: Either detectUsing or tfm must be provided.

Outputs

Variable	Description
version	Downloaded ALCops version
tfm	Detected or specified target framework moniker
outputDir	Full path to extracted analyzer DLLs directory
files	Semicolon-separated list of analyzer DLL paths

Versioning

The @1 in ALCopsDownloadAnalyzers@1 is the task major version, and the pipeline log header shows the task's own version (Version: 1.x.y). That is intentionally independent of the extension version on the Marketplace (2.x.y): every release stamps the task Minor and Patch, while Major stays at 1 because it is the number your YAML pins. It only changes on a breaking task contract change, which would mean updating your pipelines to @2. So a Version: 1.x.y header on a 2.x extension is expected, not a mismatch.

Troubleshooting

"A supported task execution handler was not found ... not compatible with your current operating system"

Despite mentioning the operating system, this Azure DevOps error is not about your OS. It means your build agent is too old to recognize any of the task's Node execution handlers. The tasks ship Node24, Node20_1, and Node20 handlers and require an agent of at least v3.224.1 (the release that introduced the Node 20 handler).

Fix it with any of the following:

• Upgrade the agent. For self-hosted agents, update to the latest 3.x or 4.x agent. Microsoft-hosted agents are always current. Self-hosted agents auto-update within a major version but not across majors (v2→v3, v3→v4 require a manual upgrade).

• Install a newer Node runner on the agent by adding the NodeTaskRunnerInstaller@0 task before the ALCops task:

  - task: NodeTaskRunnerInstaller@0
    inputs:
      runnerVersion: 20

• On-premises Azure DevOps Server: ensure the server (and its bundled agent) is recent enough. Servers older than the agent v3.224.1 baseline cannot run these tasks; upgrade the server or use the NodeTaskRunnerInstaller@0 workaround above.

Development

Prerequisites

• Node.js >= 20
• npm

Commands

cd azure-devops-extension
npm ci                     # Install dependencies
npm run lint               # Lint (eslint shared/ tasks/*/src/)
npm test                   # Run tests (vitest)
npm run build              # TypeScript compilation (tsc -p tsconfig.json)
npm run bundle             # esbuild bundling (5 task bundles)
npm run package            # Bundle + create .vsix extension package

Architecture

The extension contains 5 tasks under tasks/. Only ALCopsDownloadAnalyzers is actively maintained; the legacy tasks remain for backward compatibility.

tasks/
  download/                   # ALCopsDownloadAnalyzers — single-step detect + download
  install-analyzers/          # ALCopsInstallAnalyzers — deprecated
  detect-tfm-bc-artifact/     # ALCopsDetectTfmFromBCArtifact — deprecated
  detect-tfm-nuget-devtools/  # ALCopsDetectTfmFromNuGetDevTools — deprecated
  detect-tfm-marketplace/     # ALCopsDetectTfmFromMarketplace — deprecated
shared/                       # Shared modules (logger, input logging)

Each task is bundled into a single file via esbuild (tasks/{name}/dist/index.js), including all dependencies. All core logic lives in the @alcops/core package.

Links

• ALCops Website
• GitHub Repository
• Report Issues
• Discussions