Zum Inhalt springen
Von C/AL zu AL: der Kurs für NAV-EntwicklerEin Kurs der decoso GmbH & Co. KGErstgespräch
Kursübersicht › Seite 2 von 11

Setup: Werkzeuge, Sandbox, erste App

VS Code mit AL Language, Sandbox, Git und GitHub: so richtest du die Entwicklung ein und bringst deine erste App in den Tenant.

Stand November 2026 · Version 29

Autor: Elvis Schmidt, decoso GmbH & Co. KG

Lernziele dieser Seite. Am Ende hast du VS Code mit AL eingerichtet, eine Sandbox, ein Projekt mit verstandener 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

BausteinWozuEntsprechung in NAV 2017
Visual Studio CodeEditor. 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
GitVersionsverwaltung auf deinem Rechner.Version List, FOB-Ablage
GitHub-KontoZentrale Ablage, Pull Requests, automatische Builds.Keine
Business-Central-SandboxUmgebung, 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

  1. VS Code von code.visualstudio.com herunterladen und installieren. Die Optionen „Mit Code öffnen“ im Kontextmenü sind praktisch.
  2. VS Code starten, links die Erweiterungsansicht öffnen (Strg+Umschalt+X).
  3. 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:

BefehlWirkung
AL: Go!Neues Projekt mit Grundgerüst anlegen
AL: Download SymbolsSymbole der Apps laden, von denen dein Projekt abhängt
AL: PackageKompilieren und .app-Datei erzeugen
AL: Publish / AL: Publish without debuggingIn die Umgebung aus launch.json veröffentlichen
AL: Clear credentials cacheGespeicherte 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

ErweiterungNutzenWann installieren
AL Object ID NinjaVergibt 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 OutlinerAssistenten für neue Objekte, Gliederungsansicht, Code-Aktionen wie „alle Felder der Tabelle zur Seite hinzufügen“.Sofort
NAB AL ToolsPflege der XLIFF-Übersetzungsdateien.Sobald du übersetzt (Seite 4)
GitLensZeigt pro Zeile, wer sie wann geändert hat.Bei Teamarbeit
GitHub Pull RequestsPull Requests direkt in VS Code bearbeiten.Sobald du mit Pull Requests arbeitest

3Git installieren und einrichten

  1. Git von git-scm.com installieren. Die Standardoptionen passen. Als Standardeditor kannst du Visual Studio Code wählen.
  2. 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-SandboxDocker-Container lokal
EinrichtungWenige Klicks im Admin CenterDocker, PowerShell-Modul, Download mehrerer Gigabyte
VoraussetzungEin Business-Central-Tenant und Administratorrechte darinWindows mit Hyper-V, Docker Desktop im Windows-Container-Modus, eher 16 GB RAM oder mehr
VerhaltenIdentisch zur Produktion, also mit allen Cloud-EinschränkungenAuch On-Premises-Funktionen testbar
DatenDemodaten oder Kopie der ProduktionDemodaten oder eigene Datenbanksicherung
Offline nutzbarNeinJa
Beliebige VersionAktuelle Version, zeitweise auch die Vorschau der nächstenJede veröffentlichte Version und Länderfassung
Typischer EinsatzKundenprojekte, EinstiegBuild-Pipelines, Tests gegen mehrere Versionen, AppSource-Entwicklung

Variante A: Online-Sandbox anlegen

  1. 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.
  2. Unter Umgebungen auf Neu klicken.
  3. Namen vergeben (z. B. DEV), Typ Sandbox, Land DE (oder AT, CH), Version wählen und erstellen. Das dauert einige Minuten.
  4. Alternativ: Eine bestehende Produktionsumgebung markieren und Kopieren wählen. Dann hast du echte Daten zum Testen.
Vorsicht bei Kopien der Produktion. Eine kopierte Sandbox enthält echte Kundendaten und eingerichtete Schnittstellen. Beim Kopieren werden zwar einige Dinge automatisch entschärft (z. B. Aufgabenwarteschlangen angehalten), prüfe aber E-Mail-Versand, Zahlungsdienste und angebundene Systeme, bevor du dort buchst. Kläre außerdem, wer auf diese Daten zugreifen darf.

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).

  1. In VS Code Strg+Umschalt+P, AL: Go! wählen.
  2. Pfad angeben: C:\Repos\abc-kundenapp\app.
  3. Zielversion wählen. Nimm die Version deiner Sandbox, im Zweifel die neueste.
  4. Server wählen: Microsoft cloud sandbox oder Your own server (für Docker).
  5. VS Code fragt nach der Anmeldung und versucht, Symbole zu laden. Wenn das scheitert, ist das kein Problem, erst muss die launch.json stimmen (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
Ordner richtig öffnen. Die AL-Erweiterung erwartet, dass der in VS Code geöffnete Ordner direkt die 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"
}
EigenschaftBedeutungHinweis
idEindeutige 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.
nameAnzeigename in der Erweiterungsverwaltung.Nachträgliches Ändern ist heikel, wenn andere Apps von deiner abhängen.
publisherHerausgeber.Einheitlich für alle deine Apps halten.
versionVier Stellen: Haupt.Neben.Build.Revision.Für jede Auslieferung in die Produktion erhöhen. Eine niedrigere Version als die installierte wird abgelehnt.
dependenciesAndere Apps, deren Objekte du verwendest (außer der Base Application).Siehe unten.
platformMindestversion der Plattform.Meist so lassen, wie AL: Go! es erzeugt.
applicationMindestversion 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.
idRangesErlaubte Objekt-IDs dieser App. Mehrere Bereiche möglich.Der Compiler lehnt IDs außerhalb ab. Gib jeder App einen eigenen Teilbereich aus 50000–99999.
runtimeSprachstand von AL.Muss zur ältesten Version passen, auf der die App laufen soll. Zuordnung siehe unten.
targetCloud oder OnPrem.Bei Cloud bleiben, siehe Seite 1.
featuresSchaltet Zusatzfunktionen ein.TranslationFile erzeugt beim Bauen die XLIFF-Datei (Seite 4).
resourceExposurePolicyDü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, privacyStatementBeschreibende Angaben.Für PTEs optional, für AppSource Pflicht.

Runtime und Version

Business CentralAnwendungsversionRuntime
2024 Wave 22514.0
2025 Wave 12615.0
2025 Wave 22716.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:

AppBereich
Kundenapp Vertrieb50100–50199
Kundenapp Schnittstellen50200–50299
Test-App50900–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"
}
EigenschaftBedeutung
nameFrei wählbar, erscheint in der Auswahl beim Start.
requestlaunch 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, environmentNameTyp und Name der Online-Umgebung, genau wie im Admin Center.
tenantTenant-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, authenticationNur für eigene Server und Container.
startupObjectType, startupObjectIdWelche 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.
startupCompanyMandant, in dem gestartet wird.
launchBrowserfalse unterdrückt das Öffnen eines neuen Browserfensters bei jedem Veröffentlichen.
breakOnErrorDebugger hält bei Fehlern an: All, None oder ExcludeTry (Fehler in Try-Funktionen ignorieren).
breakOnRecordWriteHält bei jedem Schreibzugriff an: None, All, ExcludeTemporary. Nützlich für die Frage „Wer ändert diesen Datensatz?“.
enableSqlInformationDebugger und die SQL-EinstellungenZeigt im Debugger die zuletzt ausgeführten und die langsamen SQL-Anweisungen.
schemaUpdateModeWas passiert mit Tabellen und Daten deiner App beim erneuten Veröffentlichen? Siehe nächste Tabelle.
dependencyPublishingOptionVerhalten bei mehreren voneinander abhängigen Projekten im Workspace.

schemaUpdateMode

WertVerhaltenWann
Synchronize (Standard)Daten bleiben erhalten. Zerstörerische Änderungen (Feld gelöscht, Typ geändert) werden abgelehnt.Normalfall. Verhält sich wie die Produktion.
RecreateAlle Tabellen und Erweiterungsfelder deiner App werden geleert und neu angelegt.Frühe Entwicklung, wenn sich das Datenmodell noch ständig ändert.
ForceSyncErzwingt auch zerstörerische Änderungen. Daten in betroffenen Feldern gehen verloren, der Rest bleibt.Entwicklung, solange die Version noch nicht ausgeliefert wurde.
Falle. Mit 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.

  1. Strg+Umschalt+P → AL: Download Symbols.
  2. Gegebenenfalls anmelden.
  3. Im Ordner .alpackages liegen danach mehrere .app-Dateien: System, System Application, Business Foundation, Base Application, Application sowie alle Apps aus dependencies.

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 dependencies oder application und wenn eine abhängige App eine neue Version bekommen hat.
  • Nicht einchecken: .alpackages gehö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;
}
  1. Prüfe, dass startupObjectId in der launch.json auf 22 steht (Debitorenliste).
  2. Drücke F5.
  3. Unten im Ausgabefenster siehst du: Kompilieren, Paket erstellen, Veröffentlichen. Dann öffnet sich der Browser mit der Debitorenliste und der Meldung.
  4. Ö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

TastenWirkungFrüher
Strg+Umschalt+BKompilieren und Paket bauen, ohne zu veröffentlichenF11
F5Veröffentlichen und mit Debugger startenStrg+R mit aktivem Debugger
Strg+F5Veröffentlichen ohne Debugger (schneller)Strg+R
Strg+Alt+F5Schnelles Veröffentlichen: nur geänderte Objekte (RAD)Einzelnes Objekt speichern
Alt+F5Schnelles Veröffentlichen mit Debugger
Strg+Umschalt+F5Debugger starten, ohne neu zu veröffentlichen
F12Zur Definition springen„Go To Definition“
Umschalt+F12Alle Verwendungen findenGab es nicht, nur über Textexport
F2Umbenennen in allen Dateien
Strg+PDatei nach Namen öffnenFilter im Object Designer
Strg+TObjekt oder Funktion im ganzen Projekt suchen
Strg+LeertasteIntelliSense anzeigenC/AL Symbol Menu (F5)
Umschalt+Alt+FDatei 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ürzelErzeugt
ttableTabelle
ttableextTable Extension
tpagePage (Auswahl zwischen Karte, Liste usw.)
tpageextPage Extension
tcodeunitCodeunit
tenumEnum
treportReport
teventsubEvent Subscriber
tprocedure, ttriggerFunktion, 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.

  1. Lösche HelloWorld.al.
  2. Lege einen Ordner src an 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.';
            }
        }
    }
}
  1. Setze startupObjectId auf 21 (Debitorenkarte) und drücke F5.
  2. Auf der Debitorenkarte steht im Abschnitt „Allgemein“ das neue Feld. Trage ein Datum ein.
  3. 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;
        }
  1. 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.
Damit hast du den kompletten Kreislauf einmal durchlaufen: Objekt als Datei anlegen, kompilieren, in die Sandbox veröffentlichen, im Browser testen, debuggen.

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"
}
AnalyzerPrüftFür wen
CodeCopAllgemeine AL-Richtlinien: Benennung, ungenutzte Variablen, veraltete Aufrufe.Immer
UICopRegeln für den Web-Client, etwa fehlende ToolTips.Immer
PerTenantExtensionCopRegeln für Kundenerweiterungen, z. B. IDs im erlaubten Bereich, Präfixe.Kundenprojekte
AppSourceCopStrenge 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 / tableextensionTable / TableExt
page / pageextensionPage / PageExt
codeunitCodeunit
report / reportextensionReport / ReportExt
enum / enumextensionEnum / EnumExt
query, xmlport, interfaceQuery, Xmlport, Interface
permissionsetPermissionSet

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

  1. Auf github.com ein neues, leeres Repository anlegen (privat, ohne README und ohne .gitignore), z. B. abc-kundenapp.
  2. 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.

Ausblick AL-Go. Wenn du von Anfang an automatische Builds willst, erstellst du das Repository stattdessen aus der Vorlage 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

SymptomWahrscheinliche UrsacheLösung
Alles ist rot unterstrichen, „Customer“ ist unbekanntSymbole fehlenAL: Download Symbols. Prüfen, ob in .alpackages Dateien liegen.
Symbol-Download scheitert mit 401 oder 403Falsches Konto, falscher Tenant oder fehlende BerechtigungAL: Clear credentials cache, tenant in launch.json setzen, Berechtigungssatz prüfen.
Symbol-Download scheitert mit 404Umgebungsname falsch geschrieben oder Umgebung existiert nichtenvironmentName mit dem Admin Center vergleichen.
Die AL-Befehle fehlen in der BefehlspaletteGeöffneter Ordner enthält keine app.jsonDen Ordner app öffnen oder einen Workspace verwenden.
„Die ID liegt außerhalb des zulässigen Bereichs“Objekt- oder Feld-ID nicht in idRangesID anpassen oder Bereich erweitern.
Veröffentlichen scheitert: Anwendungsversion nicht kompatibelapplication in app.json ist höher als die Version der SandboxWert senken oder Sandbox aktualisieren, danach Symbole neu laden.
Veröffentlichen scheitert wegen SchemaänderungFeld 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 installierteVersion erhöhen oder die installierte App in der Sandbox deinstallieren.
Objektname bereits vorhandenNamenskonflikt mit einer anderen AppPräfix verwenden.
Nach F5 passiert im Browser nichts NeuesBrowser zeigt eine alte SitzungSeite neu laden (Strg+F5 im Browser), abmelden und neu anmelden.
Haltepunkt wird nicht erreichtMit Strg+F5 gestartet oder der Code läuft in einer anderen SitzungMit F5 starten. Für Hintergrundsitzungen und Webdienste eine attach-Konfiguration verwenden (Seite 9).
Deine App ist nach einem Update der Sandbox verschwundenAus VS Code veröffentlichte Apps gelten als Entwicklerversionen und können bei Updates entfernt werdenNeu veröffentlichen. Die Daten bleiben in der Regel erhalten.
Docker: Container startet nichtDocker läuft im Linux-Modus oder zu wenig ArbeitsspeicherAuf 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.

Umgebung, Git und Auslieferung für dein Team aufsetzen?Wir richten das gemeinsam mit euch ein.

Erstgespräch vereinbaren

Fehler gefunden? Bitte melden. Wir prüfen jede Meldung.