import { Callout } from "zudoku/ui/Callout";

# Get started

This guide takes you from nothing to a compiled, tested Business Central app, locally, then in an Azure DevOps pipeline.

There are **two ways in**, and they share one engine (the `businessdev.ALbuild` module), so you can mix them freely:

- **The [`albuild` CLI](cli/index)**: the fastest, cross-platform on-ramp. It installs as a .NET global tool and *bootstraps everything else for you*: `albuild doctor` checks the host, `albuild module install` installs the PowerShell module, `albuild setup` / `init` scaffold your config. Best on macOS/Linux and for a guided start. Full guide: [CLI → Get started](cli/get-started).
- **The [PowerShell module](powershell-module/index) directly**: for full scripting control and the richest cmdlet surface.

This page uses the module for the worked example; the CLI equivalents are linked alongside.

---

## 1. Prerequisites

| Requirement | Needed for | Notes |
| --- | --- | --- |
| **PowerShell 5.1 or 7+** | Everything | The module is dual-target. PowerShell 7+ is recommended. |
| **.NET SDK 8+** (`dotnet`) | The CLI | Hosts both global tools: `albuild` itself and the Microsoft `al` compiler used for container-less builds. |
| **Windows + Docker** | Container operations | Business Central Docker images are Windows-only. Non-container operations (compile, feed resolution, signing, REST) run on any platform with PowerShell 7. |
| **Microsoft `al` dotnet tool** | Container-less compile | Installed on demand by [`Install-BcAlTool`](powershell-module/apps#install-bcaltool). |
| **Azure CLI** | Universal Packages | Only needed for Azure DevOps Universal-feed dependencies. |

---

## 2. Install ALbuild

Pick the on-ramp that fits how you work, both end up driving the same `businessdev.ALbuild` engine.

### Option A: the CLI (fastest, cross-platform)

Install the `albuild` global tool, then let it check the host and install the PowerShell module for you:

```bash
dotnet tool install --global businessdev.ALbuild.Cli   # provides the `albuild` command
albuild doctor                                         # PowerShell + module + Docker readiness
albuild module install                                 # installs the businessdev.ALbuild module
albuild module update                                  # (later) keep the module current
```

The CLI runs everything through the module. See [CLI → Get started](cli/get-started) for the full inner loop, and [CLI → Backends](cli/index#backends) for the macOS "compile local, run on a remote host" flow.

### Option B: the PowerShell module directly

The module is published to the PowerShell Gallery as a **single package** (`businessdev.ALbuild`) that contains all nine use-case areas.

```powershell
# install once: one package, all areas
Install-Module businessdev.ALbuild -Scope CurrentUser
Import-Module businessdev.ALbuild
```

Verify it loaded:

```powershell
Get-Command -Module businessdev.ALbuild | Measure-Object   # how many cmdlets are available
```

<Callout type="info" title="No BcContainerHelper">
ALbuild does not require, install or call BcContainerHelper. The entire container stack is built into the module.
</Callout>

---

## 3. Build an app locally

The snippet below resolves the latest BC sandbox artifact, creates a container, restores dependencies, compiles, publishes and runs the tests, entirely from PowerShell.

```powershell
Import-Module businessdev.ALbuild

# 1. Resolve the BC artifact and create a container
$artifact = Find-BcArtifactUrl -Type Sandbox -Country w1 -Select Latest
$cred     = Get-Credential
New-BcContainer -Name bld -ArtifactUrl $artifact -Credential $cred

# 2. Restore dependencies into .alpackages (NuGet / Universal / local).
#    Target application and platform are read from app.json unless you override them.
Resolve-BcDependencies -ProjectFolder ./app

# 3. Compile (container-less via the AL tool; -Engine Container compiles inside the container)
Invoke-BcCompiler -ProjectFolder ./app -Engine AlTool

# 4. Publish, sync and install into the container
Publish-BcContainerApp -Name bld -AppFile ./app/output/MyApp.app -Sync -Install

# 5. Run the tests. The test toolkit has to be in the container once, and the test
#    app itself has to be published before its codeunits can be discovered.
Install-BcContainerTestToolkit -Name bld
Invoke-BcCompiler -ProjectFolder ./test -Engine AlTool
Publish-BcContainerApp -Name bld -AppFile ./test/output/MyApp.Tests.app -Sync -Install
Invoke-BcContainerTest -Name bld -ProjectFolder ./test -Credential $cred -ResultPath TestResults.xml

# 6. Tear the container down
Remove-BcContainer -Name bld
```

Every cmdlet above is documented in the [PowerShell module reference](powershell-module/index).

<Callout type="info" title="The same loop, in the CLI">
The CLI wraps this whole flow in a handful of verbs, provision, restore, then build → publish → test in one command:

```bash
albuild init --country de --bc-version 28.2          # scaffold albuild.json
albuild feeds add https://pkgs.dev.azure.com/acme/_packaging/bc/nuget/v3/index.json
albuild container new --project ./app --workspace .  # provision the BC container
albuild run pipeline --workspace . --container bld   # build → publish → test
```

See [CLI → Get started](cli/get-started) and the [command reference](cli/commands) for coverage gating, the macOS remote-host flow and `--json` output for agents.
</Callout>

---

## 4. Configure your project (`albuild.json`)

Rather than repeat arguments on every command and pipeline step, commit an `albuild.json` at the root of your repository. ALbuild reads it automatically.

```jsonc
{
  "country": "de",
  "artifactType": "Sandbox",
  "select": "Latest",
  "feeds": [
    "https://pkgs.domain.com/nuget/index.json"
  ]
}
```

See [Project configuration](concepts/project-config) for every setting.

---

## 5. Build in Azure DevOps

1. Open the Azure DevOps Marketplace and install **[ALbuild for Azure DevOps](devops-extension/index)** into your organization.
2. Add the tasks to your pipeline. A minimal build pipeline:

```yaml
trigger: [ main, master ]
pool:
  name: Self Hosted          # a Windows agent with Docker

steps:
  - checkout: self
    persistCredentials: true

  - task: GetBcArtifact@0
    inputs: { type: 'Sandbox', select: 'Latest', country: 'w1' }

  - task: StampBuildVersion@0
    inputs:
      schema: 'major.minor.increment.0'
      onlyUpdateOnChangedSource: true
    env: { AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) }

  - task: CreateBcContainer@0
  - task: ResolveDependencies@0
    env: { AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) }
  - task: CompileApp@0
  - task: PublishApp@0
    inputs: { syncMode: 'Add', install: true }
  - task: RunBcTests@0
  - task: PublishTestResults@2
    inputs: { testResultsFormat: XUnit, testResultsFiles: TestResults.xml, failTaskOnFailedTests: true }
  - task: RemoveBcContainer@0
    condition: always()
```

Packaging is its own step: add [`CreateNuGetPackage@0`](devops-extension/build-tasks) after the
compile when you want a NuGet package, and `PublishPackage@0` to push it.

All build, compile, test, sign and NuGet-publish tasks are **free of license**. Only the deployment tasks (PTE, on-prem, dev extension, Marketplace, runtime packages) require a subscription. See [Licensing & tiers](concepts/licensing).

Ready-to-use templates ship in the [`templates/`](https://github.com/365businessdev/ALbuild/tree/main/templates) folder of the repository.

---

## 6. Reproduce the pipeline locally

You can run the *same* Azure DevOps YAML template on your machine, step by step:

```powershell
Invoke-ALbuildPipeline -Path templates/yaml/ci-pipeline.yml `
    -Parameters @{ country = 'de'; projectFolder = 'app' } `
    -RepositoryRoot 'D:\Code\DevOps\Customer\D365BC-Core'
```

See the [local pipeline runner](powershell-module/pipeline) for details.

---

## Next steps

- [CLI](cli/get-started): the cross-platform command-line and the macOS remote-host flow.
- [Probe](cli/probe): evaluate AL expressions and call procedures **without a container**, in under a second. The tightest feedback loop ALbuild offers, and the one built for AI agents.
- [Architecture & modules](concepts/architecture): how the pieces fit together.
- [Azure DevOps extension](devops-extension/index): every pipeline task.
- [VS Code extension](vscode-extension): the inner-loop tooling.
- [MCP server](mcp-server/get-started): wire up an AI assistant for the runtime inner loop.