CLAUDE.md und dem AL MCP Server sinnvoll im Repository einsetzen, alten C/AL-Code mit Txt2AL als Ausgangsmaterial umwandeln und den Weg der Daten von NAV 2017 nach Business Central einschätzen.
1Was sich gegenüber NAV 2017 ändert
In NAV 2017 lag der Code in der Datenbank. Versionsverwaltung war die „Version List“, das Datum am Objekt und ein Ordner mit FOB-Dateien. Mehrere Entwickler an einem Objekt bedeutete Absprache auf Zuruf. In Business Central liegt der Code in Textdateien, und damit gelten die Werkzeuge der restlichen Softwarewelt.
| Thema | NAV 2017 | Business Central |
|---|---|---|
| Ort des Codes | Entwicklungsdatenbank | Git-Repository |
| Versionsstand | Version List, Modified-Flag, Datum | Commit-Historie, Tags, Versionsnummer in app.json |
| Paralleles Arbeiten | Objekt sperren oder absprechen | Jeder arbeitet in seinem Branch, Zusammenführen per Pull Request |
| Wer hat was geändert? | Vergleich von Textexporten | git log, git blame, GitLens zeigt es je Zeile |
| Review | Selten, von Hand | Pull Request mit Diff, Kommentaren und automatischem Build |
| Build | „Compile all“ im Object Designer | Pipeline baut bei jeder Änderung in einer sauberen Umgebung |
| Auslieferung | FOB importieren, Schema synchronisieren | .app-Datei aus der Pipeline, Upload über das Admin Center oder automatisch |
| Zurück zum alten Stand | Datenbanksicherung oder altes FOB | Alten Tag auschecken; beim Kunden gilt aber: nur vorwärts mit höherer Version |
| Hilfe beim Schreiben | Keine | KI-Assistenten, die den Code im Repository lesen, ändern und über den Compiler prüfen |
2Git-Begriffe für C/SIDE-Entwickler
| Begriff | Bedeutung | Vergleich aus der alten Welt |
|---|---|---|
| Repository | Ordner mit allen Dateien und ihrer vollständigen Geschichte | Entwicklungsdatenbank plus alle je gesicherten Stände |
| Commit | Benannter, unveränderlicher Stand aller Dateien | FOB-Export mit Datum und Kommentar |
| Branch | Eigene Entwicklungslinie, in der du ungestört arbeitest | Kopie der Entwicklungsdatenbank |
main | Die Hauptlinie; sie ist immer baubar und auslieferbar | Die „saubere“ Entwicklungsdatenbank |
| Merge | Zwei Linien zusammenführen | Text-Merge mit dem Merge Tool, nur automatisch |
| Pull Request | Antrag, einen Branch in main zu übernehmen, mit Diff, Review und Build | „Kannst du mal drüberschauen, bevor ich importiere?“ |
Remote (origin) | Das Repository auf GitHub | Zentraler Server |
| Clone, Pull, Push | Holen, aktualisieren, hochladen | – |
| Tag | Fester Name für einen Commit, z. B. v1.1.0.0 | Versionsstempel |
| Stash | Halbfertige Änderungen kurz beiseitelegen | – |
Die Befehle für den Alltag
git status # Was ist geändert?
git pull # Neuesten Stand holen
git switch -c feature/besuchsplan # Neuen Branch anlegen und wechseln
git add . # Änderungen für den Commit vormerken
git commit -m "Besuchsplan: Tabelle und Liste"
git push -u origin feature/besuchsplan
git switch main # Zurück zur Hauptlinie
git log --oneline -10 # Die letzten zehn Commits
git diff # Noch nicht vorgemerkte Änderungen ansehen
git restore datei.al # Änderung an einer Datei verwerfen
Fast alles davon geht auch in VS Code über die Seitenleiste „Quellcodeverwaltung“ (Strg+Umschalt+G). Die Befehle zu kennen hilft trotzdem, weil Anleitungen und Fehlermeldungen sie verwenden.
3Branches und Pull Requests
Für ein kleines Team genügt ein einfaches Modell: Es gibt main, und für jede Aufgabe einen kurzlebigen Branch.
| Schritt | Was passiert |
|---|---|
| 1. Aufgabe als Issue anlegen | Auf GitHub beschreibst du, was gebaut werden soll. Das Issue bekommt eine Nummer. |
| 2. Branch anlegen | git switch -c feature/42-besuchsplan von aktuellem main. |
| 3. Entwickeln | Kleine Commits, lokal mit F5 und den Tests aus Seite 9 prüfen. |
| 4. Push und Pull Request | Branch hochladen, auf GitHub „Compare & pull request“. In der Beschreibung „Closes #42“. |
| 5. Automatischer Build | AL-Go baut App und Test-App und führt alle Tests aus (Abschnitt 6). |
| 6. Review | Ein Kollege liest den Diff, kommentiert, gibt frei. Arbeitest du allein, liest du deinen eigenen Diff. Das findet erstaunlich viel. |
| 7. Merge | „Squash and merge“ macht aus allen Commits des Branches einen einzigen in main. Der Branch wird gelöscht. |
8. CI/CD auf main | AL-Go baut erneut und liefert auf Wunsch gleich in eine Testumgebung. |
| Branch-Name | Zweck |
|---|---|
main | Auslieferbarer Stand |
feature/... | Neue Funktion |
bugfix/... | Fehlerbehebung |
release/1.1 | Nur bei Bedarf: Wartungslinie für einen Hotfix auf eine bereits ausgelieferte Version, während main schon weiter ist |
main landen. Halbfertiges versteckst du nicht im Branch, sondern hinter einer fehlenden Aktion oder einem Schalter in der Einrichtung.
4Konflikte und Repository-Regeln
Typische Konfliktquellen in AL-Projekten
| Quelle | Problem | Abhilfe |
|---|---|---|
| Objektnummern | Zwei Entwickler vergeben in ihren Branches dieselbe Nummer. Git meldet keinen Konflikt, weil es verschiedene Dateien sind; erst der Build scheitert. | AL Object ID Ninja (Seite 2) vergibt Nummern über einen gemeinsamen Dienst; der Build im Pull Request fängt den Rest. |
| Feldnummern in derselben Table Extension | Wie oben, innerhalb einer Datei | Ebenso; Konflikt wird beim Merge sichtbar |
Übersetzungsdateien (.xlf) | Große XML-Dateien, an denen jede Textänderung dreht | .g.xlf nicht einchecken oder beim Konflikt neu erzeugen; die .de-DE.xlf nach dem Merge mit NAB AL Tools abgleichen |
| Berechtigungssatz „Objects“ | Jede neue Objektdatei ändert dieselbe Liste | Zeilen alphabetisch halten, dann lassen sich Konflikte leicht auflösen |
app.json (Version) | Zwei Branches erhöhen die Version | Version nicht im Feature-Branch ändern, sondern über den Workflow (Abschnitt 8) |
Layoutdateien (.docx, .xlsx) | Binär, nicht zusammenführbar | Absprechen, wer das Layout ändert; im Konfliktfall eine Fassung wählen |
Einen Konflikt löst du in VS Code: Die Datei zeigt beide Fassungen mit den Schaltflächen „Aktuelle Änderung“, „Eingehende Änderung“ und „Beide“. Danach bauen, testen, committen.
Regeln auf GitHub
| Einstellung | Wirkung |
|---|---|
Branch-Schutz für main | Kein direkter Push; Änderungen nur per Pull Request |
| Erforderliche Statusprüfung | Merge erst, wenn der Pull-Request-Build grün ist |
| Erforderliches Review | Mindestens eine Freigabe (im Zwei-Personen-Team sinnvoll, allein abschalten) |
| Lineare Historie | Nur Squash oder Rebase, kein Merge-Commit-Geflecht |
| Secret Scanning, Push Protection | GitHub blockiert Commits, die erkennbare Zugangsdaten enthalten |
Was nie ins Repository gehört
Kennwörter, Client Secrets, Tokens, Lizenzdateien, Kundendaten, Datenbanksicherungen, die .app-Dateien aus .alpackages. Was einmal gepusht wurde, bleibt in der Geschichte, auch wenn du die Datei löschst. Ein versehentlich eingechecktes Secret gilt als verbrannt: sofort im Entra-Portal neu erzeugen, nicht nur aus Git entfernen.
5AL-Go für GitHub einrichten
AL-Go für GitHub ist Microsofts fertige Sammlung von GitHub-Actions-Workflows für Business-Central-Apps. Du schreibst keine Pipeline, du übernimmst eine Vorlage und stellst sie über Einstellungsdateien ein. Es gibt zwei Vorlagen: microsoft/AL-Go-PTE für Per-Tenant-Extensions und microsoft/AL-Go-AppSource für AppSource-Apps.
Weg A: Neues Repository aus der Vorlage
Auf GitHub microsoft/AL-Go-PTE öffnen, „Use this template“ → „Create a new repository“, privat anlegen, klonen und die Ordner app und test hineinkopieren.
Weg B: Vorhandenes Repository umstellen
Für das Kursprojekt abc-kundenapp übernimmst du die Ordner .github und .AL-Go aus der Vorlage in dein Repository und checkst sie ein. Danach führst du einmal den Workflow „Update AL-Go System Files“ aus, damit alles zum aktuellen Stand der Vorlage passt.
abc-kundenapp/
├── .github/
│ ├── workflows/ <- die Workflows von AL-Go (nicht von Hand ändern)
│ └── AL-Go-Settings.json <- Einstellungen für das Repository
├── .AL-Go/
│ └── settings.json <- Einstellungen für das Projekt
├── app/ <- Haupt-App
├── test/ <- Test-App
├── CLAUDE.md <- Abschnitt 12
└── abc-kundenapp.code-workspace
AL-Go findet Apps selbst: Jeder Ordner mit einer app.json ist eine App; hängt sie von den Testbibliotheken ab, gilt sie als Test-App. In den Einstellungen kannst du die Ordner auch ausdrücklich nennen (appFolders, testFolders).
6Die Workflows von AL-Go
Die Workflows findest du im Repository unter „Actions“. Manche starten von selbst, andere stößt du mit „Run workflow“ an.
| Workflow | Start | Aufgabe |
|---|---|---|
| Pull Request Build | Automatisch bei jedem Pull Request | Baut alle Apps, führt die Tests aus, meldet das Ergebnis am Pull Request |
| CI/CD | Automatisch bei jedem Push auf main | Baut, testet, legt die .app-Dateien als Artefakte ab und liefert bei eingerichteter Umgebung aus |
| Create Release | Von Hand | Macht aus einem erfolgreichen Build ein GitHub-Release mit Tag, Notizen und .app-Dateien |
| Increment Version Number | Von Hand | Erhöht die Version in allen app.json-Dateien und erzeugt dafür einen Pull Request |
| Publish To Environment | Von Hand | Spielt einen Build oder ein Release in eine Business-Central-Umgebung ein |
| Test Current / Next Minor / Next Major | Von Hand oder nach Zeitplan | Baut und testet gegen die aktuelle, die nächste Minor- und die nächste Major-Version von Business Central |
| Create a new app / Create a new test app | Von Hand | Legt einen neuen App-Ordner samt app.json an |
| Create Online Dev. Environment | Von Hand | Erzeugt eine Online-Sandbox für die Entwicklung |
| Update AL-Go System Files | Von Hand oder nach Zeitplan | Holt die neueste Fassung der Workflows aus der Vorlage; braucht das Secret GhTokenWorkflow |
7Einstellungen von AL-Go
Einstellungen stehen in JSON-Dateien und werden in fester Reihenfolge zusammengeführt: Organisation, Repository (.github/AL-Go-Settings.json), Projekt (.AL-Go/settings.json), dazu Fassungen je Workflow oder Benutzer.
// .AL-Go/settings.json
{
"country": "de",
"appFolders": [ "app" ],
"testFolders": [ "test" ],
"enableCodeCop": true,
"enableUICop": true,
"enablePerTenantExtensionCop": true,
"rulesetFile": "app/abc.ruleset.json",
"failOn": "error"
}
// .github/AL-Go-Settings.json
{
"type": "PTE",
"templateUrl": "https://github.com/microsoft/AL-Go-PTE@main",
"versioningStrategy": 0,
"environments": [ "TEST", "PROD" ],
"DeployToTEST": {
"EnvironmentName": "TEST",
"ContinuousDeployment": true
},
"DeployToPROD": {
"EnvironmentName": "Production",
"ContinuousDeployment": false
}
}
| Einstellung | Bedeutung |
|---|---|
country | Lokalisierung, gegen die gebaut wird. Für dich de, at oder ch. |
artifact | Legt die Business-Central-Version fest, gegen die gebaut wird. Ohne Angabe die aktuelle. |
enableCodeCop usw., rulesetFile | Dieselben Analyzer und dasselbe Ruleset wie lokal (Seite 9). |
versioningStrategy | Wie Build- und Revisionsnummer der erzeugten App entstehen (Abschnitt 8). |
environments, DeployTo… | Zielumgebungen und ob nach jedem Build auf main automatisch geliefert wird. |
useCompilerFolder | Kompiliert ohne Docker-Container. Schneller, aber Tests brauchen weiterhin eine laufende Umgebung. |
doNotRunTests | Schaltet Tests ab. Nur als Notbehelf. |
installApps, appDependencyProbingPaths | Fremde Apps, von denen deine App abhängt, und woher sie kommen. |
Die vollständige Liste mit Erklärungen steht in der Dokumentation von AL-Go unter „Settings“.
8Versionieren und freigeben
Auf Seite 8 hast du die Version von Hand in app.json erhöht und einen Tag gesetzt. Mit AL-Go teilt ihr euch die Arbeit: Du bestimmst Major und Minor, die Pipeline vergibt Build und Revision.
| Stelle | Wer setzt sie? | Beispiel |
|---|---|---|
| Major.Minor | Du, über den Workflow „Increment Version Number“ (Eingabe z. B. +0.1 oder 2.0) | 1.2 |
| Build.Revision | AL-Go beim Bauen, je nach versioningStrategy aus der Laufnummer des Workflows oder aus dem Datum | 1.2.57.0 |
Damit hat jeder Build eine eindeutige, aufsteigende Version, und du kannst jede .app-Datei beim Kunden einem Lauf und einem Commit zuordnen.
Ablauf einer Freigabe
| Nr. | Schritt |
|---|---|
| 1 | Alle Pull Requests für die Version sind in main; der letzte CI/CD-Lauf ist grün. |
| 2 | Die Version läuft in der Testumgebung, der Kunde hat abgenommen. |
| 3 | Workflow „Create Release“ starten: Name, Tag (z. B. 1.2.0), Art der Version. AL-Go erzeugt das Release mit den .app-Dateien und Versionshinweisen aus den Pull Requests. |
| 4 | „Publish To Environment“ für die Produktion mit genau diesem Release. |
| 5 | „Increment Version Number“, damit main für die nächste Version weiterzählt. „Create Release“ bietet das als Option gleich mit an. |
Hotfix auf eine ausgelieferte Version
Ist main schon bei 1.3, der Kunde aber auf 1.2 und braucht sofort eine Korrektur, legst du vom Release-Tag einen Branch release/1.2 an (der Workflow „Create Release“ kann das mit erledigen), behebst dort den Fehler, lässt AL-Go bauen und lieferst 1.2.x aus. Dieselbe Korrektur muss zusätzlich nach main. Vergisst du das, kommt der Fehler mit 1.3 zurück.
9Auslieferung in den Tenant
Es gibt drei Wege, eine Per-Tenant-Extension in eine Online-Umgebung zu bringen.
| Weg | Vorgehen | Geeignet für |
|---|---|---|
| VS Code (F5) | Veröffentlicht als Entwicklerversion. Nur in Sandboxes, und die Entwicklerversion kann bei Umgebungsupdates entfernt werden. | Entwicklung, nie für Auslieferung |
| Admin Center | Im Business Central Admin Center die Umgebung öffnen, dort die Apps der Umgebung verwalten und die .app-Datei hochladen, installieren oder für das nächste Update einplanen. | Gelegentliche Auslieferung von Hand |
| AL-Go „Publish To Environment“ oder Continuous Deployment | Die Pipeline spielt den geprüften Build selbst ein. | Regelmäßige Auslieferung, mehrere Umgebungen |
Anmeldung der Pipeline: das Secret AuthContext
Damit AL-Go in eine Umgebung liefern darf, braucht es Zugangsdaten als GitHub-Secret. AL-Go sucht der Reihe nach <Umgebungsname>-AuthContext, <Umgebungsname>_AuthContext und zuletzt das allgemeine AuthContext. Der empfohlene Weg ist eine App-Registrierung in Entra ID (Service-to-Service):
| Nr. | Schritt |
|---|---|
| 1 | App-Registrierung in Microsoft Entra ID anlegen, wie auf Seite 7 für die Schnittstelle, aber eine eigene nur für die Auslieferung. |
| 2 | In Business Central auf der Seite „Microsoft Entra-Anwendungen“ die Client-ID eintragen und die Berechtigungssätze D365 AUTOMATION und EXTEN. MGT. - ADMIN zuweisen. |
| 3 | Anmeldung wählen: am besten Federated Credential (das Repository wird in der App-Registrierung eingetragen, es gibt kein gespeichertes Kennwort), sonst Client Secret. |
| 4 | Auf GitHub unter Settings → Secrets and variables → Actions das Secret anlegen, z. B. TEST-AuthContext. |
// Wert des Secrets mit Federated Credential – eine Zeile, ohne Umbrüche
{"tenantId":"<tenantId>","scopes":"https://api.businesscentral.dynamics.com/","clientId":"<clientId>"}
// Wert des Secrets mit Client Secret – eine Zeile, ohne Umbrüche
{"tenantId":"<tenantId>","scopes":"https://api.businesscentral.dynamics.com/","clientId":"<clientId>","clientSecret":"<clientSecret>"}
AuthContext zurück. Betreust du mehrere Kunden in einem Repository, lege je Umgebung ein eigenes Secret an und kein allgemeines. Quelle: AL-Go: Secrets.
Für die Produktion richtest du auf GitHub zusätzlich ein „Environment“ mit Pflichtfreigabe ein: Der Workflow hält an, bis eine benannte Person auf „Approve“ klickt. In privaten Repositories setzt das einen bezahlten GitHub-Plan voraus; ohne ihn lieferst du in die Produktion von Hand über „Publish To Environment“.
10Umgebungen und Updates
| Umgebung | Typ | Inhalt | Auslieferung |
|---|---|---|---|
| Lokaler Container je Entwickler | Docker | CRONUS, Testbibliotheken | F5 |
| DEV | Online-Sandbox | CRONUS oder anonymisierte Daten | F5 oder automatisch aus Feature-Branches |
| TEST | Online-Sandbox | Kopie der Produktion | Automatisch nach jedem Build auf main |
| PROD | Produktion | Echtdaten | Nur freigegebene Releases, mit Freigabe |
Plattform-Updates im Blick behalten
| Was | Wann | Deine Aufgabe |
|---|---|---|
| Minor-Update | Monatlich | In der Regel nichts; „Test Next Minor“ zeigt Ausnahmen |
| Major-Update | Zweimal im Jahr (Release Wave 1 im Frühjahr, Wave 2 im Herbst) | Vorher gegen die Vorschau bauen und testen, Warnungen zu veralteten Elementen abarbeiten |
| Update-Fenster | Im Admin Center je Umgebung einstellbar | Mit dem Kunden festlegen; TEST vor PROD aktualisieren lassen |
| Veraltete Elemente | Mindestens zwölf Monate zwischen Markierung und Entfernung (Abschnitt 19) | AL0432-Warnungen nicht liegen lassen |
Kompiliert deine App gegen die neue Version nicht mehr, kann die Umgebung nicht aktualisiert werden. Microsoft benachrichtigt den Administrator, und nach Ablauf einer Frist wird die App im Zweifel deinstalliert, damit das Update durchläuft. Genau dafür lädst du eine angepasste Fassung vorab für „das nächste Major-Update“ hoch (Seite 8).
11Claude Code im Repository
Claude Code ist ein Coding-Agent: Er liest die Dateien im Repository, schlägt Änderungen vor, schreibt sie, führt Befehle aus und arbeitet in Schleifen, bis ein Ziel erreicht ist. Für AL-Entwicklung ist das dann wertvoll, wenn Claude nicht nur Text erzeugt, sondern kompilieren und die Fehler selbst lesen kann. Sonst rät es bei Event-Namen und Signaturen genauso, wie dieser Kurs es an manchen Stellen musste.
| Einsatzform | Beschreibung | Geeignet für |
|---|---|---|
| Lokal im Repository | Im Terminal im Projektordner gestartet; arbeitet auf deinem Branch, du siehst jeden Schritt | Tägliche Entwicklung |
| In GitHub | Reagiert auf @claude in Issues und Pull Requests und erstellt selbst Pull Requests (Abschnitt 15) | Kleine, klar beschriebene Aufgaben; Review |
| Chat mit Repository als Kontext | Gespräch über Code, Architektur, Fehlersuche; ohne Compiler | Erklären, Entwürfe, Fragen wie in diesem Kurs |
Wo Claude bei AL stark ist, und wo nicht
| Stark | Mit Vorsicht |
|---|---|
| Gerüste: Tabelle, Liste, Karte, Berechtigungssatz, Test-Codeunit nach vorhandenem Muster C/AL-Logik in AL-Schreibweise übertragen Tests zu vorhandenem Code schreiben Analyzer-Warnungen abarbeiten Übersetzungen in der XLIFF-Datei ergänzen Code erklären, auch fremden Standardcode Diffs prüfen und auf Lücken hinweisen |
Namen von Events, Prozeduren und Feldern der Base Application: ohne Symbolsuche oft plausibel, aber falsch Was in welcher Version verfügbar ist Regeln für Schemaänderungen und Upgrade: Claude kennt deine ausgelieferten Versionen nicht Fachliche Entscheidungen: Was soll bei Storno passieren? Das weißt nur du Alles, was Produktionsdaten oder Zugangsdaten berührt |
main. Jede Änderung geht durch denselben Pull Request mit Build, Tests und deinem Review wie die eines Kollegen. Gib Claude keine Zugangsdaten zur Produktion und lass es nicht in Produktionsumgebungen veröffentlichen.
12Die Datei CLAUDE.md
Claude Code liest beim Start die Datei CLAUDE.md im Wurzelordner des Repositorys. Dort steht alles, was ein neuer Kollege am ersten Tag wissen müsste. Ohne sie beginnt jede Sitzung bei null und Claude erfindet Präfix, Nummern und Stil neu.
# ABC Kundenapp
Per-Tenant-Extension für Dynamics 365 Business Central (Online, Lokalisierung DE).
Sprache: AL. Zielversion und Runtime stehen in app/app.json – nicht ändern.
## Aufbau
- app/ Haupt-App (wird ausgeliefert), Objekt-IDs 50100–50149
- test/ Test-App, Objekt-IDs 50150–50199, hängt von app/ ab
- Eine Datei je Objekt in src/, Dateiname: <Objektname ohne Leerzeichen>.<Typ>.al
(z. B. ABCCustomerVisit.Table.al, ABCCustomerCardExt.PageExt.al)
## Feste Regeln
- Präfix "ABC " für alle Objekte, Felder in Extensions und Steuerelemente in Page Extensions.
- Nächste freie Objekt- und Feldnummer immer über das Werkzeug al_getnextobjectid
ermitteln, nie raten.
- Captions, ToolTips und Labels nur auf Englisch im Code. Deutsche Texte gehören in
app/Translations/ABC Kundenapp.de-DE.xlf. Die .g.xlf nie bearbeiten.
- Jedes Feld: Caption, ToolTip (beginnt mit "Specifies"), DataClassification.
- Kein WITH, Felder auf Pages immer mit Rec. qualifizieren.
- Texte in Error/Message/Confirm als Label mit Endung Err/Msg/Qst.
- Enum statt Option. Neue Enums: Extensible = true.
- Standardlogik nur über Event Subscriber ändern. Subscriber liegen in eigenen
Codeunits (Name endet auf "Subscribers") und enthalten keine Geschäftslogik.
- Kein Commit in Subscribern. Keine Webaufrufe in Schreibtransaktionen.
- Neue Tabelle => in die Berechtigungssätze ABC Visit - Objects/Read/Edit/Admin aufnehmen.
## Schema – besonders wichtig
Version 1.1 ist beim Kunden ausgeliefert. Deshalb:
- Keine Felder löschen, umbenennen, kürzen oder im Typ ändern.
- Keine Primärschlüssel ändern.
- Statt dessen: neues Feld, altes auf ObsoleteState = Pending, Upgrade-Schritt mit
Upgrade Tag in codeunit "ABC Upgrade". Vorher nachfragen.
## Tests
- Zu jeder Änderung an Logik gehört ein Test in test/src.
- Aufbau: [SCENARIO] / [GIVEN] / [WHEN] / [THEN], Daten über Library-Codeunits erzeugen.
- Kein Test darf sich auf CRONUS-Stammdaten verlassen.
## Arbeitsweise
- Vor dem Schreiben: Event- und Prozedurnamen der Base Application mit
al_symbolsearch nachschlagen. Nichts aus dem Gedächtnis übernehmen.
- Nach jeder Änderung: al_compile, dann al_getdiagnostics. Erst fertig melden,
wenn es keine Fehler und keine neuen Warnungen gibt.
- Nicht veröffentlichen (al_publish) ohne ausdrückliche Aufforderung.
Nie in eine Produktionsumgebung.
- app.json (id, version, idRanges, runtime), launch.json und die Dateien unter
.github/ und .AL-Go/ nicht ändern.
- Kleine Commits mit deutscher Nachricht im Imperativ. Nicht auf main arbeiten.
## Nicht tun
- Keine Zugangsdaten, Tenant-IDs oder Kundendaten in Dateien schreiben.
- Keine Analyzer-Regeln per Pragma oder Ruleset abschalten, um einen Build grün zu bekommen.
| Grundsatz | Erklärung |
|---|---|
| Kurz und konkret | Die Datei wird bei jeder Sitzung gelesen. Schreibe Regeln, keine Aufsätze; diesen Kurs kopierst du nicht hinein. |
| Begründungen dort, wo Verstöße teuer sind | Die Schema-Regel steht mit Grund da, damit Claude sie auch in Fällen anwendet, die du nicht aufgezählt hast. |
| Lebendes Dokument | Macht Claude denselben Fehler zweimal, ergänzt du eine Zeile. Die Datei liegt im Repository und geht durch denselben Review wie Code. |
| Auch für Menschen | Was dort steht, sind eure Teamregeln. Ein neuer Kollege liest sie genauso. |
13AL MCP Server
Der AL MCP Server ist ein eigenständiger Server von Microsoft, der die AL-Werkzeuge über das Model Context Protocol für beliebige KI-Agenten bereitstellt: bauen, kompilieren, veröffentlichen, Symbole suchen, Diagnosen lesen. Er läuft als eigener Prozess und braucht kein geöffnetes VS Code. Voraussetzungen laut Microsoft: AL-Language-Erweiterung ab Version 17.0 (sie bringt das Programm altool mit), die .NET-8-Laufzeit und für Werkzeuge mit Serverzugriff eine Netzwerkverbindung zur Umgebung.
| Werkzeug | Aufgabe | Nutzen für Claude |
|---|---|---|
al_compile | Code prüfen, ohne .app zu erzeugen; schneller als ein voller Build | Nach jeder Änderung die eigenen Fehler sehen |
al_getdiagnostics | Compiler- und Analyzer-Meldungen gefiltert abrufen | Gezielt Fehler und Warnungen abarbeiten |
al_symbolsearch | Symbole im Projekt, in den Abhängigkeiten oder auf der Umgebung suchen | Echte Event-, Feld- und Prozedurnamen statt geratener |
al_getnextobjectid | Nächste freie Objektnummern reservieren | Keine Nummernkonflikte |
al_build | Projekt bauen und .app erzeugen | Paket für den Test |
al_downloadsymbols | Symbolpakete laden | Frisches Projekt arbeitsfähig machen |
al_getpackagedependencies | Abhängigkeiten aus app.json auflisten | Überblick |
al_addproject | Weiteres Projekt nach dem Start hinzufügen | App und Test-App gemeinsam |
al_publish | In eine Umgebung veröffentlichen | Nur auf Aufforderung und nur in Sandboxes |
al_auth_login, al_auth_logout | Anmeldung an Entra ID im Browser, Token zwischenspeichern und löschen | Vor Cloud-Zugriffen |
Start und Einbindung
# Start von Hand, zwei Projekte, Standard-Ein-/Ausgabe
altool launchmcpserver "C:\Repos\abc-kundenapp\app" "C:\Repos\abc-kundenapp\test" --transport stdio
// .mcp.json im Wurzelordner des Repositorys
{
"mcpServers": {
"al": {
"command": "altool",
"args": [
"launchmcpserver",
"C:\\Repos\\abc-kundenapp\\app",
"C:\\Repos\\abc-kundenapp\\test",
"--transport", "stdio"
]
}
}
}
Der Agent startet den Server selbst und fragt die verfügbaren Werkzeuge ab. Der Server hält über seine Laufzeit eine Kompiliersitzung; Symbole und Zwischenstände bleiben zwischen den Aufrufen erhalten, was die Schleife aus Kompilieren, Fehler lesen, Korrigieren und erneut Kompilieren schnell macht. Bei mehreren Projekten wählt der Parameter projectPath das Ziel eines Aufrufs. Quelle und Einzelheiten: AL MCP Server (Microsoft Learn).
altool liegt im Installationsordner der AL-Erweiterung und steht nicht von selbst im Suchpfad. Trage entweder den vollen Pfad als command ein oder nimm den Ordner in die Umgebungsvariable PATH auf. Da der Pfad die Versionsnummer der Erweiterung enthält, ändert er sich mit jedem Update; die PATH-Lösung oder ein kleines Startskript erspart dir das Nachziehen. Wie genau dein Agent MCP-Server registriert, steht in dessen Dokumentation.
14Aufgaben für Claude beschreiben
Deine ursprüngliche Frage in diesem Kurs war: „Ihm Objekte beschreiben mit ID und Typ?“ Die Antwort nach zehn Seiten: Den Typ ja, die ID nicht. Die Nummer holt sich Claude über al_getnextobjectid, das Präfix aus CLAUDE.md. Du beschreibst das, was nur du weißt: das fachliche Verhalten.
Zu dünn
Mach eine Tabelle für
Besuchspläne mit Page.
Brauchbar
Neue Funktion "Besuchsplan".
Tabelle "ABC Visit Plan":
- Customer No. (Pflicht, Relation Customer)
- Planned Date (Pflicht, nicht in der
Vergangenheit)
- Visit Type (Enum "ABC Visit Type",
Vorgabe aus "ABC Visit Setup")
- Salesperson Code (Relation
Salesperson/Purchaser, Vorgabe vom
Debitor)
- Status: Open, Done, Cancelled
PK: fortlaufende Entry No.
Liste mit Suche "Visit Plans", editierbar.
Aktion "Mark as Done": legt einen
"ABC Customer Visit" mit dem geplanten
Datum an und setzt Status Done. Nur bei
Status Open, sonst Fehler.
Berechtigungssätze ergänzen. Tests für:
Vorgabewerte, Datum in Vergangenheit
abgelehnt, Mark as Done legt Besuch an,
zweites Mark as Done scheitert.
Zeig mir zuerst deinen Plan
(Objekte, Dateien), dann umsetzen.
| Baustein einer guten Aufgabe | Warum |
|---|---|
| Fachliches Verhalten mit Regeln und Ausnahmen | Das kann Claude nicht wissen |
| Verweis auf vorhandene Muster („wie die Besuchsliste“) | Einheitlicher Stil ohne lange Erklärung |
| Erwartete Tests | Sie sind deine Abnahme: Was getestet ist, musst du nicht von Hand prüfen |
| „Erst Plan, dann umsetzen“ | Ein falscher Ansatz kostet dich eine Minute Lesen statt zwanzig Dateien Review |
| Abgrenzung („nichts an der Besuchstabelle ändern“) | Verhindert gut gemeinte Umbauten |
| Kleine Aufgaben | Ein Pull Request, den du in zehn Minuten lesen kannst |
Die Arbeitsschleife
| Nr. | Schritt | Wer |
|---|---|---|
| 1 | Branch anlegen, Aufgabe beschreiben | Du |
| 2 | Plan vorschlagen | Claude |
| 3 | Plan prüfen, korrigieren, freigeben | Du |
| 4 | Symbole nachschlagen, Dateien schreiben, kompilieren, Fehler beheben | Claude mit AL MCP Server |
| 5 | Diff lesen, mit F5 ausprobieren, Tests laufen lassen | Du |
| 6 | Nachbessern lassen oder selbst ändern | Beide |
| 7 | Pull Request, Build durch AL-Go, Merge | Du |
asserterror ohne Fehlerprüfung, Seite 9), abgeschaltete Regeln, vergessene Berechtigungssätze und Übersetzungen, Commit an Stellen ohne Grund, Schemaänderungen an ausgelieferten Tabellen und unnötig viel Code für eine einfache Sache.
15Claude in Issues und Pull Requests
Mit der Claude-Code-GitHub-Integration reagiert Claude auf Erwähnungen in Issues und Pull Requests. Die Einrichtung startest du lokal in Claude Code mit dem Befehl /install-github-app; er installiert die GitHub-App im Repository und legt Workflow und Secret an. Die Beschreibung findest du unter Claude Code GitHub Actions.
| Anwendung | Beispiel |
|---|---|
| Review eines Pull Requests | @claude prüfe diesen PR gegen die Regeln in CLAUDE.md, besonders Schemaänderungen und fehlende Tests |
| Kleine Aufgabe aus einem Issue | @claude setze dieses Issue um und erstelle einen Pull Request |
| Fehlgeschlagenen Build erklären | @claude warum scheitert der Build? Schlage eine Korrektur vor |
| Versionshinweise | @claude fasse die Änderungen seit dem letzten Release für den Kunden auf Deutsch zusammen |
16Alten Code umwandeln: Txt2AL
Du hast vermutlich Jahre an C/AL-Code. Niemand tippt den ab. Microsoft hat dafür das Kommandozeilenprogramm Txt2AL ausgeliefert, das Textexporte von C/AL-Objekten in AL-Dateien umwandelt. Es lag den Versionen NAV 2018 bis Business Central 14 bei.
Ablauf
# 1. Eigene Objekte (neue Tabellen, Pages, Codeunits, Reports) aus BC 14 exportieren
finsql.exe Command=ExportToNewSyntax, File="C:\Convert\New\objects.txt", `
Database="BC14", ServerName="localhost", Filter="Id=50000..99999"
# 2. Für geänderte Standardobjekte: Deltas gegen den unveränderten Standard bilden
# (Standard und geänderte Fassung jeweils in neuer Syntax exportiert)
Compare-NAVApplicationObject `
-OriginalPath "C:\Convert\Base\*.txt" `
-ModifiedPath "C:\Convert\Modified\*.txt" `
-DeltaPath "C:\Convert\Delta" `
-ExportToNewSyntax
# 3. Umwandeln
txt2al.exe --source="C:\Convert\New" --target="C:\Convert\AL\New" --rename
txt2al.exe --source="C:\Convert\Delta" --target="C:\Convert\AL\Delta" --rename --extensionStartId=50100
| Was Txt2AL liefert | Was es nicht liefert |
|---|---|
| Eigene Tabellen, Pages, Codeunits, Reports, XMLports, Queries als AL-Objekte Aus Deltas: neue Felder als tableextension, neue Steuerelemente und Aktionen als pageextensionBerichtslayouts als Dateien |
Codeänderungen in Standardobjekten: Sie werden nicht zu Event Subscribern, sondern fehlen oder stehen als Kommentar da Ersatz für DotNet, Dateizugriffe, Automation (Seite 6) Präfixe, ToolTips, DataClassification, Enums statt OptionsCode ohne WITH und mit Rec.Berechtigungssätze, Tests |
Das Ergebnis ist Rohmaterial, kein Produkt. Es kompiliert selten auf Anhieb gegen "target": "Cloud". Hier spielt Claude seine Stärke aus: Die mechanische Nacharbeit (WITH entfernen, Rec. ergänzen, Labels, ToolTips, Präfix, Options zu Enums, Analyzer-Warnungen) ist genau die Sorte Arbeit, die ein Agent mit Compiler-Zugriff zuverlässig und geduldig erledigt. Die fachliche Arbeit (welche Standardänderung wird welcher Subscriber, was entfällt, weil der Standard es heute kann) bleibt bei dir.
17Von der Anpassung zur Extension
Der häufigste Fehler beim Umstieg ist, die alte Lösung eins zu eins nachzubauen. Zwischen NAV 2017 und heute liegen viele Versionen Standardentwicklung. Gehe deine Anpassungen einzeln durch und sortiere sie.
| Kategorie | Typischer Anteil | Vorgehen |
|---|---|---|
| Kann der Standard heute | Mehr als gedacht | Weglassen, Standard einrichten. Beispiele: E-Mail-Versand von Belegen, Excel-Layouts, Genehmigungen, Dimensionskorrekturen, Analysemodus statt eigener Listenberichte |
| Wird nicht mehr gebraucht | Erheblich | Weglassen. Frage den Fachbereich; vieles wurde für jemanden gebaut, der längst nicht mehr im Haus ist |
| Gibt es als AppSource-App | Einige große Brocken | Kaufen statt bauen: Dokumentenmanagement, Zahlungsverkehr, EDI, Lagerscanner |
| Geht ohne Code | Einige | Power Automate, Personalisierung, Profile, Berichtslayouts des Kunden |
| Eigene Felder, Tabellen, Auswertungen | Der Kern | Als Extension neu bauen, Txt2AL als Starthilfe |
| Eingriffe in Buchungsroutinen | Wenige, aber heikle | Event suchen (Seite 5). Fehlt eines, bei Microsoft im Repository für Event-Anfragen beantragen und bis dahin einen anderen Weg wählen |
| Geht in der Cloud grundsätzlich nicht | Selten | Lokale Dateien, COM, direkter SQL-Zugriff: Ersatz nach Seite 6 oder Auslagerung in einen Azure-Dienst |
Eine oder mehrere Apps?
| Schnitt | Vorteil | Nachteil |
|---|---|---|
| Eine App je Kunde | Einfach, keine Abhängigkeiten | Wird mit den Jahren groß; nichts wiederverwendbar |
| Basis-App plus Fach-Apps | Wiederverwendbare Teile, getrennte Auslieferung | Abhängigkeiten, Reihenfolge bei Upgrade, mehr Verwaltung |
Beginne mit einer App. Teile erst, wenn du einen konkreten Grund hast, etwa denselben Baustein für einen zweiten Kunden.
18Der Weg der Daten
Es gibt zwei grundsätzlich verschiedene Wege von einer NAV-2017-Datenbank nach Business Central Online.
Weg 1: Technisches Upgrade mit vollständiger Historie
Ein direktes Upgrade von NAV 2017 auf eine aktuelle Version gibt es nicht. Microsoft nennt für NAV 2017 (Version 10) als Ziel der aktuellen Versionen diesen Pfad: zuerst auf Business Central Spring 2019 (Version 14), dann auf 2024 Release Wave 2 (Version 25), dann auf die Zielversion; der Pfad verlangt die Umwandlung der Anwendung von C/AL nach AL. Version 25 ist dabei eine Pflichtstation („stepping stone“), weil Microsoft seit Version 26 die über die Jahre als entfernt markierten Tabellen und Felder tatsächlich aus dem Schema löscht. Die Cloud-Migration nach Version 26 oder höher läuft deshalb ebenfalls über Version 25. Quellen: Supported upgrade paths und Deprecated features in the platform.
| Nr. | Station | Was passiert |
|---|---|---|
| 1 | NAV 2017 → Business Central 14 (noch C/AL) | Klassisches Upgrade wie früher: Objekte zusammenführen, Datenbank technisch konvertieren, Datenupgrade mit dem Upgrade Toolkit. Deine Anpassungen sind danach noch C/AL-Änderungen im Standard. |
| 2 | Anpassungen in Extensions umwandeln | Txt2AL und Nacharbeit (Abschnitte 16 und 17). Die Felder in den Table Extensions bekommen dieselben Nummern und Namen wie die alten 50000er-Felder, eigene Tabellen behalten Nummer und Namen. Nur so lassen sich die vorhandenen Daten der Extension zuordnen. |
| 3 | Version 14 → Version 25 on-premises | Wechsel auf Microsofts Base Application als Extension. Die Daten deiner Anpassungen gehen dabei aus den Standardtabellen in den Besitz deiner Extension über. Dafür gibt es ein eigenes, in der Upgrade-Dokumentation beschriebenes Verfahren. |
| 4 | Cloud-Migration | In der Online-Umgebung dieselben Extensions installieren, dann die geführte Einrichtung für die Cloud-Migration ausführen. Sie kopiert die Daten tabellenweise aus der lokalen SQL-Datenbank in den Online-Tenant und führt anschließend das Datenupgrade auf die Online-Version aus. |
| 5 | Nacharbeit | Benutzer und Berechtigungen neu zuordnen, Schnittstellen umstellen (OAuth, APIs), Berichtslayouts, Aufgabenwarteschlange, Abnahme durch den Fachbereich. |
Weg 2: Neueinführung mit Datenübernahme
| Nr. | Schritt |
|---|---|
| 1 | Leere Online-Umgebung einrichten, Standard konfigurieren, Extension installieren |
| 2 | Stammdaten über Konfigurationspakete oder APIs übernehmen: Debitoren, Kreditoren, Artikel, Sachkonten, Preise, deine eigenen Tabellen |
| 3 | Offene Posten, Lagerbestände und Salden zum Stichtag über Buch.-Blätter einbuchen |
| 4 | Offene Aufträge und Bestellungen übernehmen oder zum Stichtag abarbeiten |
| 5 | Altsystem lesend weiterbetreiben oder die Historie in ein Auswertungssystem auslagern |
Abwägung
| Kriterium | Weg 1: Upgrade | Weg 2: Neueinführung |
|---|---|---|
| Historie | Vollständig im neuen System | Bleibt im Altsystem |
| Aufwand technisch | Hoch: drei Stationen, Zwischenversionen aufbauen, alle Anpassungen müssen mit | Mittel: nur was gebraucht wird |
| Altlasten | Wandern mit: Datenmüll, veraltete Einrichtungen, vergessene Felder | Chance zum Aufräumen |
| Prozesse | Bleiben wie sie sind | Lassen sich am heutigen Standard neu ausrichten |
| Stichtag | Jederzeit | Am besten zum Geschäftsjahreswechsel |
| Risiko | Technisch: scheiternde Upgrade-Schritte, lange Laufzeiten | Fachlich: vergessene Daten, Abstimmung der Salden |
| Passt bei | Wenig Anpassungen, Historie zwingend, Prozesse stabil | Viel gewachsener Code, Wunsch nach Neuordnung, lange Zeit seit dem letzten Upgrade |
19Geprüft: Korrekturen zu früheren Seiten
Auf Seite 1 hattest du zwei Punkte zur Prüfung vorgemerkt. Für diese Seite wurden sie in der Microsoft-Dokumentation nachgeschlagen (Stand der Abfrage: November 2026). Dabei sind weitere Punkte aufgefallen, die frühere Seiten betreffen.
| Seite | Dort stand | Laut Microsoft-Dokumentation |
|---|---|---|
| 1, 7 | SOAP ist auslaufend, der Zeitplan wurde mehrfach angepasst | SOAP-Endpunkte gelten seit 2021 Release Wave 1 als veraltet. Konkret entfällt mit Version 29.0 (2026 Release Wave 2) die Möglichkeit, eine Microsoft-Page als SOAP-Endpunkt bereitzustellen; schon seit Version 26 war das nur noch über einen Schalter in der Funktionsverwaltung möglich. Wer es weiter braucht, muss den Quelltext der Page in eine eigene Extension kopieren. |
| 7 | OData V4 auf veröffentlichten UI-Pages „funktioniert, ist aber zerbrechlich“ | Schärfer: Ab Version 30 (2027 Release Wave 1) lassen sich Microsoft-Pages auch nicht mehr als OData-Endpunkt bereitstellen. Das betrifft jede Page aus einer App des Herausgebers Microsoft. Eigene API-Pages sind damit nicht nur die Empfehlung, sondern der einzige dauerhafte Weg. |
| 1 | Übergangsfrist für veraltete Objekte „mindestens ein Jahr“ | Bestätigt: Nach der Markierung als veraltet vergehen mindestens zwölf Monate bis zur Entfernung, teils mehr; ein festes Datum nennt Microsoft nicht. Der ObsoleteTag nennt die Version der Markierung, nicht die der Entfernung. Beispiel aus der Dokumentation: Tag '18.0' bedeutet, der Code ist in 19 und 20 noch da und wird frühestens in 21 entfernt. |
| 8 | Upload der App über „Erweiterungsverwaltung → Erweiterung hochladen“ | Wird abgelöst: seit 2026 Release Wave 1 Admin Center oder Admin Center API; Entfall als Upload-Weg voraussichtlich 2027 Release Wave 1 (Abschnitt 9). Das betrifft auch den Upgrade-Test in der Online-Sandbox aus Abschnitt 19 der Seite 8. |
| 8 | Lizenzdatei .flf als NAV-2017-Begriff | Ergänzung für On-Premises: Seit Version 22 wird das Format .flf nicht mehr importiert, es gilt .bclicense. |
| 8 | Berechtigungssätze als AL-Objekte | Ergänzung: On-Premises ließ sich bis Version 28 noch auf rein datenbasierte Berechtigungssätze umschalten; ab Version 29.0 gibt es das nicht mehr. |
| 8, 9 | PowerShell-Befehle mit BcContainerHelper | Hinweis: Die Verwaltungsmodule des Servers sind auf PowerShell 7 umgestellt; Windows PowerShell 5 ist ab Version 29 keine unterstützte Konfiguration mehr. Nutze PowerShell 7 für Container aktueller Versionen. |
| 7 | Basic Authentication mit Web Service Access Key ist online abgeschaltet | Bestätigt: Für Online endete das zum 1. Oktober 2022; OAuth 2.0 ist dort die einzige Möglichkeit. On-Premises bleibt der Zugriffsschlüssel vorerst möglich. |
| 9 | Telemetrie über Verbindungszeichenfolge | Bestätigt: Der Instrumentation Key allein wird seit Version 22 nicht mehr unterstützt; die Verbindungszeichenfolge ist richtig. |
Quellen: Deprecated features in the platform und Microsoft Timeline for Deprecating Code in Business Central.
app.json nennen Version 26 und Runtime 15.0. Die Upgrade-Dokumentation führt inzwischen 2026 Release Wave 2 (Version 29) als Ziel. Trage in deinen Projekten die Version deiner tatsächlichen Umgebung ein; AL: Go! schlägt passende Werte vor.
20Übung: Vom Branch bis in den Tenant
Schritt 1 – Hauptlinie schützen
Aktiviere auf GitHub für main den Branch-Schutz: Änderungen nur per Pull Request. Die Pflicht-Statusprüfung trägst du nach Schritt 3 nach, wenn der Workflow einmal gelaufen ist.
Schritt 2 – AL-Go übernehmen
Lege einen Branch feature/al-go an. Übernimm .github und .AL-Go aus der Vorlage microsoft/AL-Go-PTE und trage die Einstellungen aus Abschnitt 7 ein, zunächst ohne den Block environments. Committe, pushe und öffne einen Pull Request.
Schritt 3 – Ersten Pull-Request-Build beobachten
Unter „Actions“ läuft der „Pull Request Build“. Sieh dir das Protokoll an: Container anlegen, Apps kompilieren, Test-App veröffentlichen, Tests ausführen. Scheitert er, lies die Meldung; häufige Ursachen sind eine application-Version in app.json, die es als Artefakt nicht gibt, und Abhängigkeiten der Test-App mit falscher GUID (Seite 9). Nach grünem Lauf: Merge, und beobachte den CI/CD-Lauf auf main. Lade das Artefakt mit den .app-Dateien herunter und vergleiche die Versionsnummer mit app.json.
Schritt 4 – CLAUDE.md und MCP-Konfiguration
Neuer Branch feature/claude-setup. Lege CLAUDE.md aus Abschnitt 12 an und passe sie an (Präfix, ID-Bereiche, ausgelieferte Version). Lege .mcp.json aus Abschnitt 13 an. Starte den AL MCP Server einmal von Hand im Terminal, um zu sehen, ob altool gefunden wird. Pull Request, Merge.
Schritt 5 – Eine Funktion mit Claude bauen
Lege ein Issue „Besuchsplan“ mit der Beschreibung aus Abschnitt 14 an und einen Branch feature/<Nr>-besuchsplan. Starte Claude Code im Repository und gib die Aufgabe. Achte auf den Ablauf:
| Beobachte | Erwartung |
|---|---|
| Legt Claude zuerst einen Plan vor? | Ja: Liste der Objekte und Dateien |
| Woher kommen die Objektnummern? | Aus al_getnextobjectid, nicht geraten |
| Schlägt Claude Namen aus der Base Application nach? | Ja, etwa das Feld für den Verkäufer am Debitor über al_symbolsearch |
| Kompiliert Claude nach den Änderungen? | Ja, und behebt die eigenen Fehler |
| Sind Berechtigungssätze und Tests dabei? | Ja, wie in CLAUDE.md verlangt |
Wo Claude von den Regeln abweicht, ergänze CLAUDE.md um eine Zeile, statt es nur im Gespräch zu sagen.
Schritt 6 – Review wie bei einem Kollegen
Lies den Diff vollständig. Veröffentliche mit F5, probiere „Mark as Done“ aus, führe die Tests im AL Test Tool aus. Prüfe die Punkte aus dem Kasten in Abschnitt 14. Ergänze die deutschen Übersetzungen (oder lass Claude sie ergänzen und lies sie gegen). Dann Pull Request mit „Closes #Nr“, Build abwarten, Merge.
Schritt 7 – Auslieferung einrichten
Lege eine App-Registrierung für die Auslieferung an, trage sie in deiner Sandbox als Entra-Anwendung mit D365 AUTOMATION und EXTEN. MGT. - ADMIN ein und lege das Secret TEST-AuthContext an (Abschnitt 9, komprimiertes JSON). Ergänze in .github/AL-Go-Settings.json die Umgebung TEST mit ContinuousDeployment. Nach dem Merge liefert der nächste CI/CD-Lauf in die Sandbox. Prüfe dort im Admin Center oder in der Erweiterungsverwaltung die installierte Version.
Schritt 8 – Release 1.2
Starte „Create Release“ mit Tag 1.2.0. Sieh dir das Release auf GitHub an: Versionshinweise, .app-Dateien. Starte danach „Increment Version Number“ mit +0.1 und führe den erzeugten Pull Request zusammen. main steht jetzt auf 1.3.
Schritt 9 – Blick nach vorn
Starte „Test Next Major“ von Hand. Läuft er durch, ist deine App für die nächste Version bereit. Wenn nicht, hast du deine erste echte Wartungsaufgabe, und zwar rechtzeitig.
21Typische Fallen
| Falle | Was passiert | Abhilfe |
|---|---|---|
Direkt auf main gearbeitet | Kein Review, kein Build vor der Übernahme; ein Fehler steht sofort in der Hauptlinie | Branch-Schutz, Pull Requests |
| Langlebige Branches | Große Konflikte, vor allem in XLIFF und Berechtigungssätzen | Kleine Aufgaben, täglich zusammenführen |
| Gleiche Objektnummer in zwei Branches | Build scheitert nach dem Merge | Object ID Ninja oder al_getnextobjectid, Build im Pull Request |
| Secret eingecheckt | Bleibt in der Geschichte, auch nach dem Löschen | Sofort neu erzeugen; GitHub-Secrets und Push Protection nutzen |
| AuthContext als mehrzeiliges JSON | Workflows brechen mit maskierten Klammern | Komprimiert in einer Zeile |
Nur ein allgemeines AuthContext bei mehreren Kunden | Auslieferung mit den falschen Zugangsdaten, ohne Warnung | Je Umgebung ein eigenes Secret |
| Auslieferung per F5 in die Kundensandbox, dann „ist ja drauf“ | Entwicklerversion, kein echter Upgrade-Weg, kann beim Update verschwinden | Immer das Paket aus der Pipeline über Admin Center oder AL-Go |
.app vom Entwicklerrechner ausgeliefert | Niemand weiß, aus welchem Stand sie gebaut wurde | Nur Artefakte aus CI/CD oder Release |
| Hotfix nur im Release-Branch | Fehler kehrt mit der nächsten Version zurück | Korrektur immer auch nach main |
| Workflows von AL-Go von Hand geändert | Nächstes „Update AL-Go System Files“ überschreibt die Änderung | Anpassen über Einstellungen |
| „Test Next Major“ nie gestartet | Inkompatibilität fällt erst auf, wenn Microsoft das Update blockiert meldet | Wöchentlich nach Zeitplan |
Claude ohne CLAUDE.md | Jede Sitzung erfindet Präfix, Nummern und Stil neu | Regeln ins Repository |
| Claude ohne Compiler | Plausibler Code mit erfundenen Events und Feldnamen | AL MCP Server; Symbolsuche zur Pflicht machen |
| KI-Code ungelesen übernommen | Schemaänderungen, abgeschaltete Regeln, wirkungslose Tests | Review wie bei jedem Kollegen; Build und Tests entscheiden |
| Riesige Aufgabe an Claude | Fünfzig Dateien, die niemand prüfen kann | Kleine Aufgaben, erst Plan |
| Txt2AL-Ergebnis für fertig gehalten | Kompiliert nicht für die Cloud; Standardänderungen fehlen stillschweigend | Als Rohmaterial behandeln; Liste der Standardänderungen getrennt abarbeiten |
| Alles eins zu eins nachgebaut | Teure Extension für Dinge, die der Standard längst kann | Jede Anpassung zuerst gegen den heutigen Standard prüfen |
| Direktes Upgrade von NAV 2017 geplant | Gibt es nicht | Pfad über Version 14 und 25, oder Neueinführung |
| Integration auf Microsoft-Pages als Webdienst gebaut | Entfällt als SOAP mit Version 29, als OData mit Version 30 | Standard-APIs oder eigene API-Pages |
| Sandbox-Kopie der Produktion sendet echte E-Mails | Testbelege beim Kunden des Kunden | Nach dem Kopieren E-Mail, Schnittstellen und Warteschlangen prüfen |
22Selbsttest, Zusammenfassung, Ausblick
Selbsttest
- Was ist der Unterschied zwischen Commit, Branch und Pull Request?
- Zwei Entwickler vergeben in ihren Branches dieselbe Objektnummer. Warum meldet Git keinen Konflikt, und wo fällt es auf?
- Welche Workflows von AL-Go laufen automatisch, und was tun sie?
- Wer bestimmt bei AL-Go welchen Teil der Versionsnummer?
- Was braucht AL-Go, um in eine Umgebung zu liefern, und welche Berechtigungssätze bekommt die Entra-Anwendung?
- Warum lieferst du nie die
.app-Datei von deinem Rechner aus? - Was gehört in die
CLAUDE.md, und warum steht die Schema-Regel dort mit Begründung? - Welche Werkzeuge des AL MCP Servers verhindern erfundene Event-Namen und doppelte Objektnummern?
- Was leistet Txt2AL bei Codeänderungen in Standardobjekten?
- Über welche Stationen führt ein technisches Upgrade von NAV 2017, und wann ist eine Neueinführung die bessere Wahl?
Lösungen anzeigen
- Ein Commit ist ein gespeicherter Stand, ein Branch eine eigene Entwicklungslinie aus Commits, ein Pull Request der Antrag, einen Branch nach Review und Build in
mainzu übernehmen. - Die Objekte liegen in verschiedenen Dateien, also gibt es textlich keinen Konflikt. Der Compiler meldet die doppelte Nummer beim Build nach dem Zusammenführen.
- „Pull Request Build“ bei jedem Pull Request (bauen, testen, Ergebnis am Pull Request) und „CI/CD“ bei jedem Push auf
main(bauen, testen, Artefakte ablegen, bei Einrichtung ausliefern). - Major und Minor bestimmst du über „Increment Version Number“; Build und Revision vergibt AL-Go beim Bauen.
- Ein Secret mit dem AuthContext, am besten je Umgebung (
<Umgebung>-AuthContext), als komprimiertes JSON. Die Entra-Anwendung bekommtD365 AUTOMATIONundEXTEN. MGT. - ADMIN. - Weil nicht nachvollziehbar ist, aus welchem Stand sie gebaut wurde und ob Tests gelaufen sind. Ausgeliefert wird nur, was die Pipeline aus einem bestimmten Commit gebaut und geprüft hat.
- Aufbau, Präfix, ID-Bereiche, Stil- und Schema-Regeln, Testvorgaben, Arbeitsweise und Verbote. Die Begründung sorgt dafür, dass die Regel auch auf Fälle angewandt wird, die nicht aufgezählt sind.
al_symbolsearchfür echte Namen aus Projekt und Abhängigkeiten,al_getnextobjectidfür freie Nummern; dazual_compileundal_getdiagnosticsals Kontrolle.- Nichts Brauchbares: Sie werden nicht zu Event Subscribern. Txt2AL wandelt eigene Objekte und aus Deltas neue Felder und Steuerelemente um; die Eingriffe in Standardcode baust du von Hand über Events neu.
- NAV 2017 → Version 14 → Version 25 → Zielversion beziehungsweise Cloud-Migration, mit Umwandlung von C/AL nach AL. Eine Neueinführung passt, wenn viel gewachsener Code vorhanden ist, Prozesse neu geordnet werden sollen und die Historie im Altsystem bleiben darf.
Zusammenfassung dieser Seite
Der Code lebt im Git-Repository, Änderungen entstehen in kurzlebigen Branches und kommen nur über Pull Requests in die Hauptlinie. AL-Go für GitHub baut und testet jede Änderung, vergibt Versionsnummern, erzeugt Releases, liefert in die Umgebungen und prüft deine App gegen kommende Versionen. Claude Code wird mit CLAUDE.md und dem AL MCP Server zu einem Kollegen, der eure Regeln kennt und seinen Code selbst kompiliert; Review, Tests und fachliche Entscheidungen bleiben bei dir. Alter C/AL-Code ist über Txt2AL Rohmaterial, und für die Daten wählst du bewusst zwischen technischem Upgrade über die Versionen 14 und 25 und einer Neueinführung.
Der ganze Kurs auf einen Blick
| Seite | Kernsatz |
|---|---|
| 1 Umdenken | Du änderst den Standard nicht mehr, du erweiterst ihn von außen. |
| 2 Setup | VS Code, AL-Erweiterung, Git und eine Sandbox ersetzen C/SIDE. |
| 3 Tabellen | Table Extensions und Enums; nach der Auslieferung wird am Schema nur noch ergänzt. |
| 4 Pages | Page Extensions, Suche statt Menü, Englisch im Code und Deutsch in XLIFF. |
| 5 Code & Events | Event Subscriber statt Codeänderung, Interfaces statt CASE. |
| 6 DotNet-Ersatz | Streams, HttpClient, Json und die System Application statt DotNet und Dateisystem. |
| 7 Reports & Daten | Layouts als Dateien, Report Extensions, eigene API-Pages mit OAuth. |
| 8 Berechtigungen & Upgrade | Berechtigungssätze und Datenumzug sind Teil der App. |
| 9 Qualität | Tests, Analyzer, Debugger und Telemetrie laufen ständig mit. |
| 10 Git, Claude, Deployment | Vom Branch über die Pipeline in den Tenant, mit einem Agenten als Kollegen. |
Wie es weitergeht
| Schritt | Empfehlung |
|---|---|
| Üben | Die Besuchsverwaltung aus den Übungen einmal vollständig bauen und alle Stellen korrigieren, die in den roten Kästen zur Prüfung markiert sind. Was der Compiler bei dir anders meldet, ist richtiger als dieser Kurs. |
| Erstes echtes Projekt | Eine kleine, abgegrenzte Anpassung eines Kunden als Extension umsetzen: zwei Felder, eine Liste, ein Subscriber, ein Bericht. Mit Tests und Pipeline, auch wenn es übertrieben wirkt. |
| Standard lesen | Mit F12 regelmäßig in die Base Application schauen. Der Quelltext von Microsoft ist das beste Lehrbuch für Muster und Events. |
| Auf dem Laufenden bleiben | Zweimal im Jahr die Release-Pläne und die Liste der veralteten Funktionen lesen; die Warnungen AL0432 im eigenen Code sind dein Frühwarnsystem. |
| Nachweis | Die Microsoft-Lernpfade zur Entwicklerprüfung MB-820 decken denselben Stoff ab und eignen sich zur Lückensuche. |