Business Central

How to develop Business Central SaaS Extension from Scratch (Repo-backed, Azure DevOps)

Premanath Kumarage · Author
4 min read
A staircase of clouds rising into a blue sky

Business Central SaaS Extension from Scratch (Repo-backed, Azure DevOps)

Business Central SaaS Extension from Scratch (Repo-backed, Azure DevOps)

Prerequisites (must be done once per laptop)

  1. Install Visual Studio Code.
  2. Install Git for Windows.
  3. In VS Code → Extensions, install:
    • AL Language (Microsoft)
    • Azure Repos (Microsoft) (optional but helpful)
  4. Make sure you can sign in to:
    • Azure DevOps
    • Business Central SaaS tenant (Microsoft Entra ID / Azure AD)

Part A — Create the Azure DevOps Repo (Empty)

Step A1 — Create a new project (only if needed)

If you already have a DevOps Project, skip this.

  1. Azure DevOps → New Project
  2. Name: e.g. bc-bcextension-01
  3. Visibility: Private
  4. Create

Step A2 — Create an empty Git repository

  1. Go to Repos → Files
  2. Select New repository
  3. Type: Git
  4. Name: e.g. bc-bcextension-01
  5. ✅ Do NOT initialize with README
  6. ✅ Do NOT add .gitignore
  7. Create

✅ Result: Repo page shows: “repo is empty”.

Part B — Clone Repo to Your PC

Step B1 — Create a local working folder

Example:

  • Create folder: C:\BC\

Step B2 — Clone the empty repo

Choose either method:

Option 1 (simple): Clone in VS Code

  1. In Azure DevOps repo page → click Clone in VS Code
  2. Pick local folder:
    • C:\BC\bc-bcextension-01
  3. VS Code opens the repo

Option 2: Clone using Git command line

  1. Copy HTTPS clone URL from Azure DevOps
  2. Run in terminal:
  3. cd C:\BC
  4. git clone <paste-clone-url> bc-bcextension-01
  5. Open VS Code → File → Open Folder → C:\BC\bc-bcextension-01

✅ Result: Local folder contains a .git folder and nothing else.

Part C — Add .gitignore (Before generating AL project)

Step C1 — Create .gitignore at repo root

Create file here:

  • ✅ C:\BC\bc-bcextension-01\.gitignore

Paste this content:

# Business Central / AL generated artifacts

.alpackages/

.alcache/

.snapshots/

*.app

# VS Code (keep only shared config)

.vscode/*

!.vscode/launch.json

!.vscode/settings.json

# OS files

.DS_Store

Thumbs.db

Step C2 — Commit and push .gitignore

In VS Code Source Control:

  1. Stage .gitignore
  2. Commit message: Add gitignore
  3. Push / Sync

✅ Repo now has 1 commit.

Part D — Create the AL Project (Scaffold) in the Repo

Key rule (IMPORTANT)

✅ The folder you select for AL: Go! must NOT exist yet.

We will generate the AL project into a new folder called src.

Step D1 — Run AL: Go!

  1. Open VS Code with repo root:
    • C:\BC\bc-bcextension-01
  2. Press: Ctrl + Shift + P
  3. Run: AL: Go!
  4. When it asks for a folder location:
    • Enter/select:
    • C:\BC\bc-bcextension-01\src
    • Do NOT create src manually. Let AL create it.

✅ Result: VS Code creates src folder and generates project files inside.

Part E — Configure the BC SaaS Connection (launch.json)

Step E1 — Open the generated launch.json

File path:

  • C:\BC\bc-bcextension-01\src\.vscode\launch.json

Replace content with your SaaS sandbox config (example):

{

"version": "0.2.0",

"configurations": [

{

"name": "BC SaaS Sandbox",

"type": "al",

"request": "launch",

"server": "https://businesscentral.dynamics.com",

"tenant": "7f9c2a8e-4b6d-4c3a-9e51-0d2a9b8c6f41",

"environmentName": "Sandbox",

"authentication": "MicrosoftEntraID",

"startupObjectType": "Page",

"startupObjectId": 22,

"breakOnError": "All",

"launchBrowser": true

}

]

}

Note: "tenant": "7f9c2a8e-4b6d-4c3a-9e51-0d2a9b8c6f41" provided here is only for illustration; a valid tenant id must be provided here.

✅ This ensures it uses SaaS + Entra ID, not On-Prem.

Part F — Set app.json Correctly (Runtime, IDs, name)

Step F1 — Edit app.json

File path:

  • C:\BC\bc-bcextension-01\src\app.json

Set these fields clearly:

  • name = your extension name
  • publisher = your company/publisher
  • idRanges = your object range
  • runtime must match your target version

Example:

{

"id": "YOUR-GUID-HERE",

"name": "BCExtension-01",

"publisher": "MicroCloud 360",

"version": "1.0.0.0",

"brief": "Business Central Extension 01",

"description": "Business Central SaaS Extension",

"dependencies": [],

"idRanges": [

{ "from": 50100, "to": 50149 }

],

"runtime": "17.0",

"features": [ "NoImplicitWith" ]

}

✅ (Use a new GUID for each app—AL usually generates it for you.)

Part G — Download Symbols (Required before coding properly)

Step G1 — Download Symbols

  1. Open the AL project folder:
    • In VS Code, ensure you are working inside src
  2. Ctrl + Shift + P
  3. Run: AL: Download Symbols

✅ Result:

  • .alpackages gets populated
  • Errors like “cannot find Customer List” disappear

Part H — Build + Publish to BC SaaS Sandbox

Step H1 — Publish from VS Code

  1. Ctrl + Shift + P
  2. Run: AL: Publish

You will be asked to login (browser sign-in) the first time.

✅ Result:

  • Extension is deployed to your Sandbox environment.

Part I — Verify in Business Central

Step I1 — Confirm extension is installed

In BC:

  1. Search: Extension Management
  2. Find your extension under:
    • Installed / Published list (depends on role/permissions)
  3. Confirm version number matches your app.json

Step I2 — If fields/pages not visible

If you added fields to a page extension:

  1. Open the page
  2. ⚙️ Settings → Personalize
  3. Add fields to columns / layout if needed
  4. If still hidden:
    • ⚙️ Settings → Reset personalization

Part J — Commit Code to Repo (Proper workflow)

Step J1 — Commit generated project + config

In VS Code Source Control:

  1. Stage changes (app.json, launch.json, AL files, etc.)
  2. Commit message: Initial AL project scaffold
  3. Push

✅ Now your repo contains the full AL project.

Part K — Work from Another Laptop (Proves repo-backed setup)

On a second laptop:

  1. Install prerequisites (VS Code, Git, AL extension)
  2. Clone repo to local folder
  3. Open repo root in VS Code
  4. Open src
  5. AL: Download Symbols
  6. AL: Publish

✅ Same project works anywhere.

Written by

Premanath Kumarage

Author

All insights →

Start here

Every piece here started as a client problem. Tell us yours.

A working session, not a sales call. Bring the process your current system fights you on, and we will tell you plainly what it would take to fix it.

Newsletter

One email a month. No filler.

Stay ahead with Microsoft Business Applications.
Insights, implementation advice and practical ideas to help your business get more from Microsoft technology.

By subscribing, you acknowledge MicroCloud 360’s Privacy Policy.