How to develop 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.