app.json und launch.json, heruntergeladene Symbole, eine erste eigene App in der Sandbox und das Ganze als Repository auf GitHub. Rechne mit ein bis zwei Stunden.
1Was du brauchst
| Baustein | Wozu | Entsprechung in NAV 2017 |
|---|---|---|
| Visual Studio Code | Editor. Kostenlos, läuft auf Windows, macOS und Linux. | C/SIDE-Editor |
| Erweiterung „AL Language“ (Microsoft) | Compiler, IntelliSense, Debugger, Veröffentlichen in die Umgebung. | C/SIDE-Compiler und Debugger |
| Git | Versionsverwaltung auf deinem Rechner. | Version List, FOB-Ablage |
| GitHub-Konto | Zentrale Ablage, Pull Requests, automatische Builds. | Keine |
| Business-Central-Sandbox | Umgebung, in die du veröffentlichst und in der du testest. | Entwicklungsdatenbank |
| Browser (Edge oder Chrome) | Der Web-Client ist die einzige Oberfläche. | Windows-Client |
Du brauchst weder SQL Server noch eine lokale Business-Central-Installation noch eine Lizenzdatei, solange du gegen eine Online-Sandbox entwickelst.
2Visual Studio Code und die AL-Erweiterung
- VS Code von
code.visualstudio.comherunterladen und installieren. Die Optionen „Mit Code öffnen“ im Kontextmenü sind praktisch. - VS Code starten, links die Erweiterungsansicht öffnen (Strg+Umschalt+X).
- Nach AL Language suchen. Der Herausgeber muss Microsoft sein, die Kennung lautet
ms-dynamics-smb.al. Installieren.
Die Erweiterung aktualisiert sich automatisch und ist abwärtskompatibel: Mit der neuesten Erweiterung kannst du auch für ältere Business-Central-Versionen entwickeln. Welche Sprachmerkmale erlaubt sind, steuert die Eigenschaft runtime in der app.json (Abschnitt 6).
Die Befehlspalette
Fast alles in VS Code läuft über die Befehlspalette: Strg+Umschalt+P (oder F1), dann tippen. Alle AL-Befehle beginnen mit AL:. Die wichtigsten:
| Befehl | Wirkung |
|---|---|
AL: Go! | Neues Projekt mit Grundgerüst anlegen |
AL: Download Symbols | Symbole der Apps laden, von denen dein Projekt abhängt |
AL: Package | Kompilieren und .app-Datei erzeugen |
AL: Publish / AL: Publish without debugging | In die Umgebung aus launch.json veröffentlichen |
AL: Clear credentials cache | Gespeicherte Anmeldung verwerfen, z. B. nach Tenant-Wechsel |
AL: Generate permission set … | Berechtigungssatz für alle Objekte der App erzeugen (Seite 8) |
AL: Open Page Designer u. ä. | Weitere Helfer, je nach Version der Erweiterung |
Empfohlene Zusatzerweiterungen
| Erweiterung | Nutzen | Wann installieren |
|---|---|---|
| AL Object ID Ninja | Vergibt die nächste freie Objekt- und Feld-ID, auch im Team ohne Konflikte. | Sofort, spart täglich Zeit |
| CRS AL Language Extension (waldo) | Benennt Dateien nach einem Muster um, setzt Präfixe, bringt Code-Schnipsel mit. | Sofort |
| AZ AL Dev Tools / AL Code Outliner | Assistenten für neue Objekte, Gliederungsansicht, Code-Aktionen wie „alle Felder der Tabelle zur Seite hinzufügen“. | Sofort |
| NAB AL Tools | Pflege der XLIFF-Übersetzungsdateien. | Sobald du übersetzt (Seite 4) |
| GitLens | Zeigt pro Zeile, wer sie wann geändert hat. | Bei Teamarbeit |
| GitHub Pull Requests | Pull Requests direkt in VS Code bearbeiten. | Sobald du mit Pull Requests arbeitest |
3Git installieren und einrichten
- Git von
git-scm.cominstallieren. Die Standardoptionen passen. Als Standardeditor kannst du Visual Studio Code wählen. - Einmalig Name und E-Mail setzen. Öffne dazu in VS Code ein Terminal (Strg+ö auf deutscher Tastatur, sonst Menü Terminal → Neues Terminal):
git config --global user.name "Dein Name"
git config --global user.email "du@deinefirma.de"
git config --global init.defaultBranch main
Die E-Mail-Adresse sollte zu deinem GitHub-Konto passen, sonst werden Commits dort nicht deinem Profil zugeordnet. Mehr Git kommt auf Seite 10, hier genügen die Grundbefehle aus Abschnitt 12.
4Die Sandbox
Du hast zwei Möglichkeiten. Für den Einstieg ist die Online-Sandbox die klar einfachere.
| Online-Sandbox | Docker-Container lokal | |
|---|---|---|
| Einrichtung | Wenige Klicks im Admin Center | Docker, PowerShell-Modul, Download mehrerer Gigabyte |
| Voraussetzung | Ein Business-Central-Tenant und Administratorrechte darin | Windows mit Hyper-V, Docker Desktop im Windows-Container-Modus, eher 16 GB RAM oder mehr |
| Verhalten | Identisch zur Produktion, also mit allen Cloud-Einschränkungen | Auch On-Premises-Funktionen testbar |
| Daten | Demodaten oder Kopie der Produktion | Demodaten oder eigene Datenbanksicherung |
| Offline nutzbar | Nein | Ja |
| Beliebige Version | Aktuelle Version, zeitweise auch die Vorschau der nächsten | Jede veröffentlichte Version und Länderfassung |
| Typischer Einsatz | Kundenprojekte, Einstieg | Build-Pipelines, Tests gegen mehrere Versionen, AppSource-Entwicklung |
Variante A: Online-Sandbox anlegen
- Admin Center öffnen:
https://businesscentral.dynamics.com/<Tenant>/admin. Für<Tenant>setzt du die Tenant-ID (GUID) oder den Domänennamen ein, z. B.contoso.onmicrosoft.com. Du erreichst es auch im Web-Client über das Zahnrad → Admin Center. - Unter Umgebungen auf Neu klicken.
- Namen vergeben (z. B.
DEV), Typ Sandbox, Land DE (oder AT, CH), Version wählen und erstellen. Das dauert einige Minuten. - Alternativ: Eine bestehende Produktionsumgebung markieren und Kopieren wählen. Dann hast du echte Daten zum Testen.
Berechtigungen: Für das Admin Center brauchst du eine passende Administratorrolle im Tenant (z. B. Dynamics-365-Administrator) oder einen delegierten Partnerzugang. Zum Veröffentlichen aus VS Code braucht dein Benutzer in der Sandbox SUPER oder den Berechtigungssatz D365 EXTENSION MGT..
Kein eigener Tenant? Du kannst mit einem Geschäftskonto eine kostenlose Testversion von Business Central starten und darin eine Sandbox anlegen. Die genauen Bedingungen und Laufzeiten ändern sich, prüfe sie auf der Microsoft-Seite.
Variante B: Docker-Container (optional)
Das PowerShell-Modul BcContainerHelper nimmt dir fast alles ab. In einer PowerShell mit Administratorrechten:
# einmalig
Install-Module BcContainerHelper -Force
# aktuelle deutsche Sandbox-Version ermitteln
$artifactUrl = Get-BCArtifactUrl -type Sandbox -country de -select Latest
# Benutzer und Kennwort für den Container festlegen
$credential = Get-Credential
# Container erstellen
New-BcContainer `
-accept_eula `
-containerName bcdev `
-artifactUrl $artifactUrl `
-auth UserPassword `
-credential $credential `
-updateHosts
Am Ende gibt das Skript die Adresse des Web-Clients aus (hier http://bcdev/BC/). Mit -updateHosts ist der Container unter seinem Namen erreichbar. Die passende launch.json steht in Abschnitt 7.
5Das erste Projekt mit „AL: Go!“
Lege zuerst einen Ordner für das spätere Repository an, z. B. C:\Repos\abc-kundenapp. Die App selbst kommt in einen Unterordner app. Das wirkt jetzt umständlich, passt aber zur üblichen Struktur mit einer zweiten App für Tests und zu AL-Go (Seite 10).
- In VS Code Strg+Umschalt+P,
AL: Go!wählen. - Pfad angeben:
C:\Repos\abc-kundenapp\app. - Zielversion wählen. Nimm die Version deiner Sandbox, im Zweifel die neueste.
- Server wählen: Microsoft cloud sandbox oder Your own server (für Docker).
- VS Code fragt nach der Anmeldung und versucht, Symbole zu laden. Wenn das scheitert, ist das kein Problem, erst muss die
launch.jsonstimmen (Abschnitt 7).
Danach sieht der Ordner so aus:
abc-kundenapp/
└── app/
├── .vscode/
│ └── launch.json ← Wohin wird veröffentlicht?
├── .alpackages/ ← Symbole (noch leer)
├── app.json ← Steckbrief der App
└── HelloWorld.al ← Beispielobjekt
app.json enthält. Öffne also den Ordner app, nicht den Repository-Ordner darüber. Sobald du mehrere Apps hast, verwendest du eine Workspace-Datei (Abschnitt 13).
6Die app.json im Detail
Die app.json ersetzt alles, was früher implizit durch die Datenbank und die Lizenz bestimmt war. Ein bereinigtes Beispiel:
{
"id": "3f2c8a51-7d4e-4b6a-9c1f-2e5d8a7b6c40",
"name": "ABC Kundenapp",
"publisher": "Meine Firma GmbH",
"version": "1.0.0.0",
"brief": "Kundenspezifische Erweiterungen",
"description": "Zusatzfelder und Prüfungen für den Vertrieb.",
"privacyStatement": "",
"EULA": "",
"help": "",
"url": "",
"logo": "",
"dependencies": [],
"screenshots": [],
"platform": "1.0.0.0",
"application": "26.0.0.0",
"idRanges": [
{ "from": 50100, "to": 50149 }
],
"resourceExposurePolicy": {
"allowDebugging": true,
"allowDownloadingSource": true,
"includeSourceInSymbolFile": true
},
"runtime": "15.0",
"features": [ "TranslationFile" ],
"target": "Cloud"
}
| Eigenschaft | Bedeutung | Hinweis |
|---|---|---|
id | Eindeutige Kennung der App (GUID). Wird von AL: Go! erzeugt. | Nie mehr ändern, sobald die App irgendwo installiert ist. An der ID hängen die Daten der App. Eine neue ID bedeutet für das System eine andere App. |
name | Anzeigename in der Erweiterungsverwaltung. | Nachträgliches Ändern ist heikel, wenn andere Apps von deiner abhängen. |
publisher | Herausgeber. | Einheitlich für alle deine Apps halten. |
version | Vier Stellen: Haupt.Neben.Build.Revision. | Für jede Auslieferung in die Produktion erhöhen. Eine niedrigere Version als die installierte wird abgelehnt. |
dependencies | Andere Apps, deren Objekte du verwendest (außer der Base Application). | Siehe unten. |
platform | Mindestversion der Plattform. | Meist so lassen, wie AL: Go! es erzeugt. |
application | Mindestversion der Microsoft-Anwendung. Bindet Base Application, System Application und Business Foundation in einem Rutsch ein. | Darf nicht höher sein als die Version der Zielumgebung, sonst scheitert die Installation. |
idRanges | Erlaubte Objekt-IDs dieser App. Mehrere Bereiche möglich. | Der Compiler lehnt IDs außerhalb ab. Gib jeder App einen eigenen Teilbereich aus 50000–99999. |
runtime | Sprachstand von AL. | Muss zur ältesten Version passen, auf der die App laufen soll. Zuordnung siehe unten. |
target | Cloud oder OnPrem. | Bei Cloud bleiben, siehe Seite 1. |
features | Schaltet Zusatzfunktionen ein. | TranslationFile erzeugt beim Bauen die XLIFF-Datei (Seite 4). |
resourceExposurePolicy | Dürfen andere deinen Code debuggen und den Quelltext aus der installierten App herunterladen? | Für Kundenprojekte meist alles true. Für verkaufte Produkte bewusst entscheiden. |
logo, brief, description, url, help, EULA, privacyStatement | Beschreibende Angaben. | Für PTEs optional, für AppSource Pflicht. |
Runtime und Version
| Business Central | Anwendungsversion | Runtime |
|---|---|---|
| 2024 Wave 2 | 25 | 14.0 |
| 2025 Wave 1 | 26 | 15.0 |
| 2025 Wave 2 | 27 | 16.0 |
Mit jeder Hauptversion steigt beides um eins. Trage die Werte nicht von Hand aus dieser Tabelle ein, sondern übernimm, was AL: Go! für deine Zielversion erzeugt.
Abhängigkeiten
Willst du Objekte einer anderen App verwenden, etwa einer Branchenlösung oder einer eigenen Basis-App, trägst du sie ein:
"dependencies": [
{
"id": "11111111-2222-3333-4444-555555555555",
"name": "Branchenlösung XY",
"publisher": "Anbieter AG",
"version": "5.2.0.0"
}
]
Die Werte findest du in der Erweiterungsverwaltung der Sandbox. Nach dem Eintrag musst du die Symbole erneut herunterladen. Die angegebene Version ist eine Mindestversion.
Nummernbereich sinnvoll aufteilen
Anders als in NAV 2017 hat jeder Objekttyp seinen eigenen Zählraum, Tabelle 50100 und Codeunit 50100 stören sich nicht. Feldnummern in Table Extensions müssen ebenfalls im Bereich liegen. Ein einfaches Schema für einen Kunden:
| App | Bereich |
|---|---|
| Kundenapp Vertrieb | 50100–50199 |
| Kundenapp Schnittstellen | 50200–50299 |
| Test-App | 50900–50999 |
7Die launch.json im Detail
Die launch.json im Ordner .vscode beschreibt, wohin VS Code veröffentlicht und woher es Symbole lädt. Du kannst mehrere Konfigurationen anlegen und beim Start auswählen.
Online-Sandbox
{
"version": "0.2.0",
"configurations": [
{
"name": "Sandbox DEV",
"type": "al",
"request": "launch",
"environmentType": "Sandbox",
"environmentName": "DEV",
"tenant": "contoso.onmicrosoft.com",
"startupObjectType": "Page",
"startupObjectId": 21,
"launchBrowser": true,
"breakOnError": "All",
"breakOnRecordWrite": "None",
"enableSqlInformationDebugger": true,
"enableLongRunningSqlStatements": true,
"longRunningSqlStatementsThreshold": 500,
"numberOfSqlStatements": 10,
"schemaUpdateMode": "Synchronize"
}
]
}
Docker-Container
{
"name": "Docker bcdev",
"type": "al",
"request": "launch",
"server": "http://bcdev",
"serverInstance": "BC",
"authentication": "UserPassword",
"startupObjectType": "Page",
"startupObjectId": 21,
"schemaUpdateMode": "Synchronize"
}
| Eigenschaft | Bedeutung |
|---|---|
name | Frei wählbar, erscheint in der Auswahl beim Start. |
request | launch veröffentlicht und startet eine Sitzung. attach hängt den Debugger an eine laufende Sitzung. snapshotInitialize startet eine Aufzeichnung für die Produktion (beides auf Seite 9). |
environmentType, environmentName | Typ und Name der Online-Umgebung, genau wie im Admin Center. |
tenant | Tenant-ID oder Domäne. Nötig, wenn dein Konto Zugriff auf mehrere Tenants hat, etwa als Partner. Lässt du es weg, wird der Heimat-Tenant deines Kontos verwendet. |
server, serverInstance, port, authentication | Nur für eigene Server und Container. |
startupObjectType, startupObjectId | Welche Seite (oder welcher Bericht, welche Tabelle) öffnet sich nach dem Veröffentlichen? Trage die Seite ein, an der du gerade arbeitest. 21 ist die Debitorenkarte, 22 die Debitorenliste. |
startupCompany | Mandant, in dem gestartet wird. |
launchBrowser | false unterdrückt das Öffnen eines neuen Browserfensters bei jedem Veröffentlichen. |
breakOnError | Debugger hält bei Fehlern an: All, None oder ExcludeTry (Fehler in Try-Funktionen ignorieren). |
breakOnRecordWrite | Hält bei jedem Schreibzugriff an: None, All, ExcludeTemporary. Nützlich für die Frage „Wer ändert diesen Datensatz?“. |
enableSqlInformationDebugger und die SQL-Einstellungen | Zeigt im Debugger die zuletzt ausgeführten und die langsamen SQL-Anweisungen. |
schemaUpdateMode | Was passiert mit Tabellen und Daten deiner App beim erneuten Veröffentlichen? Siehe nächste Tabelle. |
dependencyPublishingOption | Verhalten bei mehreren voneinander abhängigen Projekten im Workspace. |
schemaUpdateMode
| Wert | Verhalten | Wann |
|---|---|---|
Synchronize (Standard) | Daten bleiben erhalten. Zerstörerische Änderungen (Feld gelöscht, Typ geändert) werden abgelehnt. | Normalfall. Verhält sich wie die Produktion. |
Recreate | Alle Tabellen und Erweiterungsfelder deiner App werden geleert und neu angelegt. | Frühe Entwicklung, wenn sich das Datenmodell noch ständig ändert. |
ForceSync | Erzwingt auch zerstörerische Änderungen. Daten in betroffenen Feldern gehen verloren, der Rest bleibt. | Entwicklung, solange die Version noch nicht ausgeliefert wurde. |
Recreate oder ForceSync gewöhnst du dich an Änderungen, die in der Produktion unmöglich sind. Stelle spätestens vor der ersten Auslieferung auf Synchronize zurück und teste damit das Update von der vorherigen Version.
Anmeldung
Beim ersten Zugriff auf eine Online-Umgebung meldet dich VS Code über dein Microsoft-Konto an. Je nach Version der Erweiterung geschieht das über ein Browserfenster oder über einen Gerätecode, den du auf einer Microsoft-Seite eingibst. Das Token wird zwischengespeichert. Landest du im falschen Tenant oder mit dem falschen Konto, hilft AL: Clear credentials cache.
8Symbole herunterladen
Dein Code verweist auf Objekte, die nicht in deinem Projekt liegen, etwa Record Customer. Der Compiler braucht deren Beschreibung. In NAV 2017 lagen sie einfach in derselben Datenbank, jetzt holst du sie als Symbolpakete.
- Strg+Umschalt+P →
AL: Download Symbols. - Gegebenenfalls anmelden.
- Im Ordner
.alpackagesliegen danach mehrere.app-Dateien: System, System Application, Business Foundation, Base Application, Application sowie alle Apps ausdependencies.
Erst jetzt verschwinden die roten Unterstreichungen im Beispielcode, und IntelliSense kennt die Standardobjekte.
- Erneut herunterladen musst du nach einem Update der Sandbox, nach Änderungen an
dependenciesoderapplicationund wenn eine abhängige App eine neue Version bekommen hat. - Nicht einchecken:
.alpackagesgehört nicht ins Repository. Jeder Entwickler und jede Pipeline lädt die Symbole selbst. - Standardcode lesen: Setze den Cursor auf ein Standardobjekt und drücke F12 („Go to Definition“). Du siehst den Quelltext der Base Application, schreibgeschützt. Das ist dein Ersatz für das Öffnen eines Standardobjekts im Object Designer.
9Hello World veröffentlichen
Die von AL: Go! erzeugte Datei HelloWorld.al sieht etwa so aus:
pageextension 50100 CustomerListExt extends "Customer List"
{
trigger OnOpenPage();
begin
Message('App published: Hello world');
end;
}
- Prüfe, dass
startupObjectIdin derlaunch.jsonauf 22 steht (Debitorenliste). - Drücke F5.
- Unten im Ausgabefenster siehst du: Kompilieren, Paket erstellen, Veröffentlichen. Dann öffnet sich der Browser mit der Debitorenliste und der Meldung.
- Öffne in Business Central die Seite Erweiterungsverwaltung. Deine App steht dort mit Name, Herausgeber und Version.
Was dabei im Hintergrund passiert ist, kennst du von Seite 1: veröffentlichen, synchronisieren, installieren. Im Projektordner liegt jetzt außerdem die Datei Meine Firma GmbH_ABC Kundenapp_1.0.0.0.app. Das ist das Paket, das später auch in die Produktion hochgeladen wird.
Tastenkürzel für den Alltag
| Tasten | Wirkung | Früher |
|---|---|---|
| Strg+Umschalt+B | Kompilieren und Paket bauen, ohne zu veröffentlichen | F11 |
| F5 | Veröffentlichen und mit Debugger starten | Strg+R mit aktivem Debugger |
| Strg+F5 | Veröffentlichen ohne Debugger (schneller) | Strg+R |
| Strg+Alt+F5 | Schnelles Veröffentlichen: nur geänderte Objekte (RAD) | Einzelnes Objekt speichern |
| Alt+F5 | Schnelles Veröffentlichen mit Debugger | |
| Strg+Umschalt+F5 | Debugger starten, ohne neu zu veröffentlichen | |
| F12 | Zur Definition springen | „Go To Definition“ |
| Umschalt+F12 | Alle Verwendungen finden | Gab es nicht, nur über Textexport |
| F2 | Umbenennen in allen Dateien | |
| Strg+P | Datei nach Namen öffnen | Filter im Object Designer |
| Strg+T | Objekt oder Funktion im ganzen Projekt suchen | |
| Strg+Leertaste | IntelliSense anzeigen | C/AL Symbol Menu (F5) |
| Umschalt+Alt+F | Datei formatieren | |
| Strg+. | Schnellkorrekturen an der Cursorposition |
Die verbindliche Liste aller Kürzel steht in VS Code unter Datei → Einstellungen → Tastenkombinationen, Suche nach „AL:“.
Code-Schnipsel
Du musst das Grundgerüst eines Objekts nie von Hand tippen. Lege eine neue Datei mit der Endung .al an, tippe t und wähle aus der Liste, z. B.:
| Kürzel | Erzeugt |
|---|---|
ttable | Tabelle |
ttableext | Table Extension |
tpage | Page (Auswahl zwischen Karte, Liste usw.) |
tpageext | Page Extension |
tcodeunit | Codeunit |
tenum | Enum |
treport | Report |
teventsub | Event Subscriber |
tprocedure, ttrigger | Funktion, Trigger |
10Übung: Die erste eigene Erweiterung
Ersetze Hello World durch etwas Sinnvolles. Du brauchst noch nicht jede Zeile zu verstehen, Tabellen folgen auf Seite 3 und Pages auf Seite 4.
- Lösche
HelloWorld.al. - Lege einen Ordner
srcan und darin die folgenden zwei Dateien.
src/ABCCustomerExt.TableExt.al
tableextension 50100 "ABC Customer Ext" extends Customer
{
fields
{
field(50100; "ABC Letzter Besuch"; Date)
{
Caption = 'Last Visit';
DataClassification = CustomerContent;
}
}
}
src/ABCCustomerCardExt.PageExt.al
pageextension 50100 "ABC Customer Card Ext" extends "Customer Card"
{
layout
{
addlast(General)
{
field("ABC Letzter Besuch"; Rec."ABC Letzter Besuch")
{
ApplicationArea = All;
ToolTip = 'Specifies the date of the last visit to the customer.';
}
}
}
}
- Setze
startupObjectIdauf 21 (Debitorenkarte) und drücke F5. - Auf der Debitorenkarte steht im Abschnitt „Allgemein“ das neue Feld. Trage ein Datum ein.
- Setze in VS Code einen Haltepunkt (Klick links neben eine Zeilennummer) gibt es hier noch nicht, weil kein Code vorhanden ist. Ergänze deshalb in der Table Extension einen Trigger und probiere den Debugger aus:
field(50100; "ABC Letzter Besuch"; Date)
{
Caption = 'Last Visit';
DataClassification = CustomerContent;
trigger OnValidate()
var
FutureDateErr: Label 'The last visit cannot be in the future.';
begin
if "ABC Letzter Besuch" > Today() then
Error(FutureDateErr);
end;
}
- Setze einen Haltepunkt auf die Zeile mit
if, drücke F5 und ändere das Datum im Browser. VS Code hält an, links siehst du Variablen und Aufrufliste. F10 geht einen Schritt weiter, F11 springt in Funktionen hinein, F5 lässt weiterlaufen.
11Editor-Einstellungen und Code-Analyse
Einstellungen, die für das Projekt gelten sollen, stehen in .vscode/settings.json. Diese Datei gehört ins Repository, damit alle im Team dieselben Regeln haben.
{
"al.enableCodeAnalysis": true,
"al.codeAnalyzers": [
"${CodeCop}",
"${UICop}",
"${PerTenantExtensionCop}"
],
"al.ruleSetPath": "./abc.ruleset.json",
"editor.formatOnSave": true,
"files.trimTrailingWhitespace": true,
"CRS.ObjectNamePrefix": "ABC ",
"CRS.FileNamePattern": "<ObjectNameShort>.<ObjectTypeShort>.al",
"CRS.FileNamePatternExtensions": "<ObjectNameShort>.<ObjectTypeShort>.al",
"CRS.OnSaveAlFileAction": "Rename"
}
| Analyzer | Prüft | Für wen |
|---|---|---|
| CodeCop | Allgemeine AL-Richtlinien: Benennung, ungenutzte Variablen, veraltete Aufrufe. | Immer |
| UICop | Regeln für den Web-Client, etwa fehlende ToolTips. | Immer |
| PerTenantExtensionCop | Regeln für Kundenerweiterungen, z. B. IDs im erlaubten Bereich, Präfixe. | Kundenprojekte |
| AppSourceCop | Strenge Regeln für AppSource, darunter keine zerstörerischen Änderungen gegenüber der Vorversion. | AppSource-Apps |
Die Analyzer zeigen ihre Hinweise schon beim Tippen im Fenster „Probleme“ (Strg+Umschalt+M). Regeln, die du bewusst nicht befolgen willst, schaltest du in einer Regelsatz-Datei ab oder stufst sie um:
{
"name": "ABC Regeln",
"description": "Regelsatz für alle ABC-Apps",
"rules": [
{
"id": "AA0072",
"action": "None",
"justification": "Variablennamen dürfen vom Objektnamen abweichen."
},
{
"id": "AA0137",
"action": "Error",
"justification": "Ungenutzte Variablen sollen den Build stoppen."
}
]
}
Die Einträge mit CRS. gehören zur Erweiterung von waldo und sorgen dafür, dass Dateien beim Speichern automatisch nach dem Muster umbenannt werden. Die Namen aller Einstellungen stehen in der Beschreibung der Erweiterung.
Ordnerstruktur und Dateinamen
Der Compiler schreibt keine Struktur vor, er liest alle .al-Dateien im Projekt. Bewährt haben sich zwei Regeln: ein Objekt pro Datei und der Dateiname nach dem Muster <Objektname>.<Objekttyp>.al.
Nach Objekttyp (einfach, gut für kleine Apps)
app/
├── app.json
└── src/
├── Table/
├── TableExt/
├── Page/
├── PageExt/
├── Codeunit/
├── Enum/
├── Report/
└── PermissionSet/
Nach Funktion (besser ab mittlerer Größe)
app/
├── app.json
└── src/
├── Kundenklasse/
│ ├── ABCKundenklasse.Enum.al
│ ├── ABCCustomerExt.TableExt.al
│ └── ABCCustomerCardExt.PageExt.al
├── Besuchsplanung/
└── Schnittstelle/
| Objekttyp | Übliches Kürzel im Dateinamen |
|---|---|
| table / tableextension | Table / TableExt |
| page / pageextension | Page / PageExt |
| codeunit | Codeunit |
| report / reportextension | Report / ReportExt |
| enum / enumextension | Enum / EnumExt |
| query, xmlport, interface | Query, Xmlport, Interface |
| permissionset | PermissionSet |
12Das Projekt zu GitHub bringen
.gitignore
Lege im Repository-Ordner (abc-kundenapp, also oberhalb von app) eine Datei .gitignore an:
# Symbole und Zwischenstände
.alpackages/
.alcache/
.snapshots/
rad.json
# Build-Ergebnisse
*.app
# Persönliche Einstellungen (optional, siehe Text)
# .vscode/launch.json
launch.json einchecken oder nicht? Sie enthält keine Kennwörter, aber Tenant- und Umgebungsnamen. Arbeitest du allein, checke sie ein. Im Team mit persönlichen Sandboxes ist es üblich, sie zu ignorieren und stattdessen eine Vorlage launch.example.json ins Repository zu legen.
Erster Commit und Push
- Auf github.com ein neues, leeres Repository anlegen (privat, ohne README und ohne .gitignore), z. B.
abc-kundenapp. - Im Terminal im Repository-Ordner:
cd C:\Repos\abc-kundenapp
git init
git add .
git status
git commit -m "Erste Version: Feld Letzter Besuch am Debitor"
git remote add origin https://github.com/DEINKONTO/abc-kundenapp.git
git push -u origin main
Beim ersten Push öffnet sich ein Browserfenster zur Anmeldung bei GitHub. Prüfe mit git status vor dem Commit, dass weder .alpackages noch .app-Dateien in der Liste stehen.
Alles Weitere geht auch ohne Terminal: Die Ansicht „Quellcodeverwaltung“ in VS Code (Strg+Umschalt+G) zeigt geänderte Dateien, dort schreibst du die Commit-Nachricht und synchronisierst.
microsoft/AL-Go-PTE, klonst es und legst deine App dort in einen Unterordner. Das geht auch nachträglich. Beides zeigt Seite 10.
Der tägliche Ablauf in Kurzform
git pull # neuesten Stand holen
git switch -c feature/kundenklasse # eigenen Zweig anlegen
# ... arbeiten, F5, testen ...
git add .
git commit -m "Kundenklasse als Enum ergänzt"
git push -u origin feature/kundenklasse
# danach Pull Request auf GitHub stellen
13Mehrere Apps in einem Workspace
Sobald du eine Test-App oder eine zweite App hast, öffnest du nicht mehr einen einzelnen Ordner, sondern einen Workspace. Lege im Repository-Ordner eine Datei abc-kundenapp.code-workspace an:
{
"folders": [
{ "path": "app" },
{ "path": "test" }
],
"settings": {
"al.enableCodeAnalysis": true
}
}
Öffne diese Datei über Datei → Arbeitsbereich aus Datei öffnen. Jeder Ordner behält seine eigene app.json und launch.json. Die Test-App trägt die Haupt-App in dependencies ein. VS Code erkennt Abhängigkeiten zwischen Projekten im selben Workspace und verwendet die Symbole direkt aus dem Nachbarprojekt, ohne Umweg über .alpackages.
14Fehlerbehebung
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Alles ist rot unterstrichen, „Customer“ ist unbekannt | Symbole fehlen | AL: Download Symbols. Prüfen, ob in .alpackages Dateien liegen. |
| Symbol-Download scheitert mit 401 oder 403 | Falsches Konto, falscher Tenant oder fehlende Berechtigung | AL: Clear credentials cache, tenant in launch.json setzen, Berechtigungssatz prüfen. |
| Symbol-Download scheitert mit 404 | Umgebungsname falsch geschrieben oder Umgebung existiert nicht | environmentName mit dem Admin Center vergleichen. |
| Die AL-Befehle fehlen in der Befehlspalette | Geöffneter Ordner enthält keine app.json | Den Ordner app öffnen oder einen Workspace verwenden. |
| „Die ID liegt außerhalb des zulässigen Bereichs“ | Objekt- oder Feld-ID nicht in idRanges | ID anpassen oder Bereich erweitern. |
| Veröffentlichen scheitert: Anwendungsversion nicht kompatibel | application in app.json ist höher als die Version der Sandbox | Wert senken oder Sandbox aktualisieren, danach Symbole neu laden. |
| Veröffentlichen scheitert wegen Schemaänderung | Feld gelöscht oder Typ geändert bei Synchronize | Änderung zurücknehmen oder in der Entwicklung vorübergehend ForceSync verwenden. |
| „Eine App mit derselben ID und einer höheren Version ist bereits installiert“ | Version in app.json niedriger als die installierte | Version erhöhen oder die installierte App in der Sandbox deinstallieren. |
| Objektname bereits vorhanden | Namenskonflikt mit einer anderen App | Präfix verwenden. |
| Nach F5 passiert im Browser nichts Neues | Browser zeigt eine alte Sitzung | Seite neu laden (Strg+F5 im Browser), abmelden und neu anmelden. |
| Haltepunkt wird nicht erreicht | Mit Strg+F5 gestartet oder der Code läuft in einer anderen Sitzung | Mit F5 starten. Für Hintergrundsitzungen und Webdienste eine attach-Konfiguration verwenden (Seite 9). |
| Deine App ist nach einem Update der Sandbox verschwunden | Aus VS Code veröffentlichte Apps gelten als Entwicklerversionen und können bei Updates entfernt werden | Neu veröffentlichen. Die Daten bleiben in der Regel erhalten. |
| Docker: Container startet nicht | Docker läuft im Linux-Modus oder zu wenig Arbeitsspeicher | Auf Windows-Container umschalten, Speicher prüfen, Ausgabe von New-BcContainer lesen. |
15Selbsttest
Welche Datei legt fest, in welche Umgebung F5 veröffentlicht?
.vscode/launch.json, über environmentType, environmentName und tenant (online) oder server und serverInstance (Container).
Warum darfst du die id in der app.json nach der ersten Installation nicht mehr ändern?
Das System erkennt die App an dieser ID. Mit neuer ID wäre es eine andere App, und die Daten der bisherigen wären ihr nicht mehr zugeordnet.
Was liegt im Ordner .alpackages, und gehört er ins Repository?
Die Symbolpakete der Apps, auf denen dein Projekt aufbaut. Er gehört nicht ins Repository, jeder lädt sie selbst.
Was ist der Unterschied zwischen Strg+Umschalt+B und F5?
Das erste kompiliert nur und erzeugt die .app-Datei. F5 veröffentlicht zusätzlich in die Umgebung und startet den Debugger.
Du hast ein Feld vom Typ Text in Code geändert, und das Veröffentlichen scheitert. Warum, und was tust du in der Entwicklung?
Das ist eine zerstörerische Schemaänderung, die Synchronize ablehnt. In der Entwicklung hilft vorübergehend ForceSync oder Recreate. Nach einer Auslieferung musst du stattdessen ein neues Feld anlegen und das alte als veraltet markieren.
Die Sandbox hat Version 26, in deiner app.json steht "application": "27.0.0.0". Was passiert?
Die App lässt sich nicht installieren, weil sie eine höhere Mindestversion verlangt, als die Umgebung hat.
Wie siehst du den Quellcode der Codeunit „Sales-Post“?
Im Code auf einen Verweis darauf gehen und F12 drücken. Voraussetzung sind heruntergeladene Symbole.
16Zusammenfassung
Dein Arbeitsplatz besteht aus VS Code mit der AL-Erweiterung, Git und einer Sandbox. Die app.json beschreibt die App, die launch.json das Ziel. Symbole ersetzen den direkten Blick in die Datenbank. Mit F5 läuft der Kreislauf aus Kompilieren, Veröffentlichen und Testen in Sekunden, und das Ergebnis liegt als Textdateien in einem Git-Repository.
Checkliste: VS Code und AL Language installiert · Git eingerichtet · Sandbox vorhanden · Projekt mit AL: Go! angelegt · Symbole geladen · eigenes Feld auf der Debitorenkarte sichtbar · Haltepunkt einmal erreicht · Repository auf GitHub.