@alcops/core

Automatically detect the Target Framework Moniker (TFM) for Business Central and download the matching code analyzer files. Build AL extensions with the right analyzers, without manual version juggling. Designed for CI/CD pipelines.

Features

• Detect the TFM from four different sources:
  • BC artifact URL (e.g. a sandbox or OnPrem artifact)
  • VS Marketplace (the AL Language extension)
  • NuGet DevTools (Microsoft's AL development tools package)
  • Local compiler path (a directory containing the AL compiler DLLs)
• Download and extract ALCops analyzer DLLs for a detected TFM
• JSON output on stdout, logs on stderr (pipe-friendly)
• Zero configuration required
• Usable as a CLI or as a Node.js library

Installation

# Install globally
npm install -g @alcops/core

# Or run directly with npx
npx @alcops/core detect-tfm marketplace

Requirements

• Node.js >= 20

CLI Usage

alcops <command> [args]

Commands:
  detect-tfm bc-artifact <url>         Detect TFM from a BC artifact URL
  detect-tfm marketplace [channel|version]     Detect TFM from VS Marketplace (default: current)
  detect-tfm nuget-devtools [version|channel]  Detect TFM from NuGet DevTools (default: latest)
  detect-tfm compiler-path <dir>       Detect TFM from a local compiler directory
  download --output <dir>               Download and extract ALCops analyzers

Download options:
  --output <dir>                       Required. Directory to extract analyzer DLLs into
  --detect-using <input>               TFM detection input (URL, path, channel, or version)
  --tfm <tfm>                          Explicit TFM (skips auto-detection)
  --version <ver>                      ALCops package version (default: latest)
  --detect-from <source>               Force detection source (bc-artifact, marketplace,
                                         nuget-devtools, compiler-path)

Global options:
  --verbose   Enable debug-level logging
  --help      Show this help message

Examples

Detect from the VS Marketplace (most common):

alcops detect-tfm marketplace

Detect from a specific NuGet DevTools version:

alcops detect-tfm nuget-devtools 26.0.12345

Detect from a BC artifact URL:

alcops detect-tfm bc-artifact "https://bcartifacts.azureedge.net/sandbox/26.0.12345.0/us"

Detect from a local compiler directory:

alcops detect-tfm compiler-path ./path/to/compiler

Download Command

The download command combines TFM detection with analyzer extraction in a single step.

Download analyzers with auto-detected TFM from the latest NuGet DevTools:

alcops download --detect-using latest --output ./analyzers

Download analyzers with auto-detected TFM from a BC artifact URL:

alcops download --detect-using "https://bcartifacts.azureedge.net/sandbox/26.0.12345.0/us" --output ./analyzers

Download analyzers with auto-detected TFM from a local compiler directory:

alcops download --detect-using ./path/to/compiler --output ./analyzers

Download analyzers with an explicit TFM (skips detection):

alcops download --tfm net8.0 --output ./analyzers

Download a specific ALCops version:

alcops download --detect-using latest --output ./analyzers --version 1.0.0

Force a detection source with --detect-from (overrides smart routing):

alcops download --detect-using 18.0.2293710 --detect-from marketplace --output ./analyzers

Enable verbose logging for debugging:

alcops download --detect-using latest --output ./analyzers --verbose

Download Output

{
  "version": "1.0.0",
  "tfm": "net8.0",
  "outputDir": "/absolute/path/to/analyzers",
  "files": [
    "/absolute/path/to/analyzers/ALCops.Analyzers.dll"
  ]
}

Output

All commands write JSON to stdout:

{
  "tfm": "net8.0",
  "source": "marketplace",
  "details": "AL Language extension v14.0.12345"
}

Logs go to stderr, so you can safely pipe the result:

TFM=$(alcops detect-tfm marketplace | jq -r '.tfm')
echo "Building with TFM: $TFM"

CI/CD Example (GitHub Actions)

- name: Detect TFM
  id: tfm
  run: |
    result=$(npx @alcops/core detect-tfm marketplace)
    echo "tfm=$(echo "$result" | jq -r '.tfm')" >> "$GITHUB_OUTPUT"

- name: Use TFM
  run: echo "Target framework is ${{ steps.tfm.outputs.tfm }}"

Or use the download command for a one-step solution:

- name: Download ALCops Analyzers
  run: npx @alcops/core download --detect-using latest --output ./analyzers --verbose

AL 18 / BC 29 notes

• The AL Language 18 VSIX ships its compiler binaries flat in extension/bin/ (no more Analyzers/, win32/, linux/ or darwin/ folders). Detection probes the flat layout first and falls back to the legacy path, so both AL 18+ and AL <= 17 work unchanged.
• Those binaries target net10.0 and are framework-dependent: compiling with the AL 18 toolset needs a .NET 10 runtime on the machine or agent.
• The Microsoft DevTools NuGet package ships both net8.0 and net10.0 assemblies. Detection prefers the newest TFM, so nuget-devtools reports net10.0.
• If your build runs the net8.0 toolset, point detection at it with --detect-from compiler-path or skip detection entirely with --tfm net8.0.

Programmatic API

The package exports all detection functions for use as a library:

import { detectFromMarketplace, createConsoleLogger } from '@alcops/core';

const logger = createConsoleLogger();
const result = await detectFromMarketplace('current', logger);
console.log(result.tfm); // e.g. "net8.0"

See the exported API surface for the full list of available functions and types.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT