1Was sich gegenüber NAV 2017 ändert
Test-Codeunits, Handler und Testseiten gab es in NAV 2017 bereits, sie wurden in Kundenprojekten aber selten benutzt. In Business Central werden sie wichtig, weil sich die Plattform unter deiner App monatlich ändert: Nur automatisierte Tests sagen dir vor dem Update, ob deine App mit der nächsten Version noch funktioniert. Neu sind außerdem die Code-Analyse beim Tippen, der Debugger in VS Code und die Telemetrie.
| Thema | NAV 2017 | Business Central (AL) |
|---|---|---|
| Tests | Test-Codeunits im selben Objektbestand, Test Toolkit als FOB, Page 130401 „CAL Test Tool“ | Eigene Test-App mit Abhängigkeit zur Haupt-App, Testbibliotheken als Apps, Page 130451 „AL Test Tool“ |
| Testlauf | Von Hand im Client | Im Client, aus VS Code, per PowerShell und automatisch in der Pipeline (Seite 10) |
| Code-Qualität | Richtlinien auf Papier, Review von Hand | Analyzer (CodeCop, UICop, PerTenantExtensionCop, AppSourceCop) melden Verstöße beim Tippen und im Build |
| Debugger | Eigener Debugger-Client, Start über die Sitzungsliste | In VS Code integriert: Haltepunkte im Quelltext, F5 |
| Fehlersuche in Produktion | Debugger an Produktivsitzung hängen | Snapshot-Debugging: Aufzeichnung, die du nachträglich durchgehst |
| SQL-Analyse | SQL Server Profiler, direkte Abfragen | Kein SQL-Zugriff in der Cloud; SQL-Anweisungen im Debugger, Leistungsprofiler, Telemetrie |
| Datenzugriff | Immer alle Felder geladen | Teilsätze mit SetLoadFields, steuerbare Leseisolation |
| Überwachung | Windows-Ereignisanzeige auf dem Server | Telemetrie in Azure Application Insights, Auswertung mit KQL |
2Die Test-App: Aufbau im Repository
Tests gehören nicht in die App, die du auslieferst. Sie liegen in einer zweiten App, die von der ersten abhängt. Der Kunde bekommt nur die Haupt-App; die Test-App läuft in deiner Sandbox und in der Pipeline.
abc-kundenapp/ <- Git-Repository
├── abc-kundenapp.code-workspace <- Workspace mit beiden Ordnern
├── app/ <- Haupt-App (IDs 50100–50149)
│ ├── app.json
│ └── src/...
└── test/ <- Test-App (IDs 50150–50199)
├── app.json
├── .vscode/launch.json
└── src/
├── ABCVisitTests.Codeunit.al
└── ABCVisitPermTests.Codeunit.al
test/app.json
{
"id": "7b1e4c92-5a3d-4f8e-b6c1-9d2a7e5f3b10",
"name": "ABC Kundenapp Tests",
"publisher": "Meine Firma GmbH",
"version": "1.1.0.0",
"dependencies": [
{
"id": "3f2c8a51-7d4e-4b6a-9c1f-2e5d8a7b6c40",
"name": "ABC Kundenapp",
"publisher": "Meine Firma GmbH",
"version": "1.1.0.0"
},
{
"id": "dd0be2ea-f733-4d65-bb34-a28f4624fb14",
"name": "Library Assert",
"publisher": "Microsoft",
"version": "26.0.0.0"
},
{
"id": "5d86850b-0d76-4eca-bd7b-951ad998e997",
"name": "Tests-TestLibraries",
"publisher": "Microsoft",
"version": "26.0.0.0"
}
],
"platform": "26.0.0.0",
"application": "26.0.0.0",
"idRanges": [ { "from": 50150, "to": 50199 } ],
"runtime": "15.0",
"target": "Cloud"
}
| Punkt | Erklärung |
|---|---|
Eigene id | Die Test-App ist eine eigenständige App mit eigener GUID. Erzeuge sie mit AL: Go! im Ordner test oder per GUID-Generator. |
| Abhängigkeit zur Haupt-App | Die id muss exakt die aus app/app.json sein. Im Workspace löst VS Code die Abhängigkeit direkt auf den Nachbarordner auf. |
| Testbibliotheken | Microsoft liefert sie als Apps (Abschnitt 6). Die GUIDs findest du in der Erweiterungsverwaltung oder im Ordner .alpackages. |
| Eigener ID-Bereich | Getrennt von der Haupt-App, damit Test-Objekte nie Nummern für Produktivobjekte belegen. |
| Kein Präfix-Zwang, keine Übersetzung | Die Test-App wird nicht ausgeliefert. Das Präfix beizubehalten schadet trotzdem nicht. |
Die Test-App sieht von der Haupt-App nur, was öffentlich ist. Prozeduren mit internal und Objekte mit Access = Internal (Seite 5) erreichst du nur, wenn die Haupt-App es ausdrücklich erlaubt. Dazu trägst du in app/app.json ein:
"internalsVisibleTo": [
{
"id": "7b1e4c92-5a3d-4f8e-b6c1-9d2a7e5f3b10",
"name": "ABC Kundenapp Tests",
"publisher": "Meine Firma GmbH"
}
]
3Testumgebung einrichten
Tests laufen nur in Sandbox-Umgebungen, nie in Produktion. Die Umgebung braucht die Testbibliotheken und das Testwerkzeug.
| Umgebung | Einrichtung |
|---|---|
| Docker | Beim Anlegen des Containers -includeTestToolkit angeben; mit -includeTestLibrariesOnly werden nur die Bibliotheken ohne Microsofts eigene Tests installiert (schneller, kleiner). Nachträglich geht es mit Import-TestToolkitToBcContainer. |
| Online-Sandbox | In der Erweiterungsverwaltung die Apps „Test Runner“, „Library Assert“, „Any“, „Library Variable Storage“, „Permissions Mock“ und „Tests-TestLibraries“ installieren. Sie sind in Sandboxes bereitgestellt, aber nicht installiert. |
# Docker: Container mit Testbibliotheken (Ergänzung zu Seite 2)
New-BcContainer -containerName bcdev `
-artifactUrl (Get-BcArtifactUrl -type Sandbox -country de) `
-auth UserPassword -credential $credential `
-accept_eula -updateHosts `
-includeTestToolkit -includeTestLibrariesOnly
Danach lädst du im Ordner test die Symbole (AL: Download Symbols). Veröffentliche zuerst die Haupt-App, dann die Test-App. Bequemer ist der Befehl AL: Publish full dependency tree for active project, der beide in der richtigen Reihenfolge veröffentlicht.
4Aufbau einer Test-Codeunit
codeunit 50150 "ABC Visit Tests"
{
Subtype = Test;
TestPermissions = Disabled;
var
Assert: Codeunit "Library Assert";
LibrarySales: Codeunit "Library - Sales";
IsInitialized: Boolean;
[Test]
procedure InsertVisitUpdatesLastVisitOnCustomer()
var
Customer: Record Customer;
Visit: Record "ABC Customer Visit";
begin
// [SCENARIO] Inserting a visit updates the last visit date on the customer
Initialize();
// [GIVEN] A customer without visits
LibrarySales.CreateCustomer(Customer);
// [WHEN] A visit is inserted for the work date
CreateVisit(Visit, Customer."No.", WorkDate());
// [THEN] The customer shows the work date as last visit
Customer.Get(Customer."No.");
Assert.AreEqual(WorkDate(), Customer."ABC Letzter Besuch", 'Last visit date was not updated.');
end;
local procedure Initialize()
begin
if IsInitialized then
exit;
// einmalige Vorbereitung für alle Tests dieser Codeunit
IsInitialized := true;
Commit();
end;
local procedure CreateVisit(var Visit: Record "ABC Customer Visit"; CustomerNo: Code[20]; VisitDate: Date)
begin
Visit.Init();
Visit.Validate("Customer No.", CustomerNo);
Visit.Validate("Visit Date", VisitDate);
Visit.Insert(true);
end;
}
| Baustein | Erklärung |
|---|---|
Subtype = Test | Macht die Codeunit zur Test-Codeunit. Sie lässt sich nur über einen Test Runner ausführen. |
[Test] | Kennzeichnet eine Testprozedur. Sie hat keine Parameter und keinen Rückgabewert. Jede Testprozedur ist ein eigener Test mit eigenem Ergebnis. |
| Prozedurname | Beschreibt das erwartete Verhalten. Er ist das Erste, was du im Fehlerprotokoll liest. |
[SCENARIO], [GIVEN], [WHEN], [THEN] | Reine Kommentare, aber feste Konvention von Microsoft: Ausgangslage, Aktion, erwartetes Ergebnis. Halte dich daran, die Tests bleiben lesbar. |
Initialize() | Gemeinsame Vorbereitung, die nur beim ersten Test läuft. Das Commit() am Ende sorgt dafür, dass diese Vorbereitung beim Zurückrollen einzelner Tests erhalten bleibt. |
| Hilfsprozeduren | Ohne [Test]. Lagere Datenerzeugung dorthin aus, damit die Tests selbst kurz bleiben. |
TestPermissions | Steuert, mit welchen Rechten die Tests laufen (Abschnitt 10). |
Ein Test gilt als bestanden, wenn die Prozedur ohne Fehler endet. Jeder Fehler, auch ein unerwarteter TestField-Fehler tief im Standard, lässt ihn scheitern.
5Assert und asserterror
Codeunit „Library Assert“
| Methode | Prüft |
|---|---|
AreEqual(Erwartet, Tatsächlich, Meldung) | Gleichheit zweier Werte |
AreNotEqual(...) | Ungleichheit |
AreNearlyEqual(Erwartet, Tatsächlich, Toleranz, Meldung) | Dezimalwerte mit Rundungstoleranz |
IsTrue(Bedingung, Meldung), IsFalse(...) | Boolesche Bedingung |
RecordIsEmpty(Rec), RecordIsNotEmpty(Rec) | Ob es Sätze im Filter gibt |
RecordCount(Rec, Anzahl) | Anzahl der Sätze im Filter |
ExpectedError(Text) | Ob der zuletzt abgefangene Fehler den Text enthält |
ExpectedErrorCode(Code) | Fehlercode statt Text, z. B. 'TestField' oder 'Dialog' |
Fail(Meldung) | Lässt den Test ausdrücklich scheitern |
Die Reihenfolge der Parameter ist immer: erst der erwartete, dann der tatsächliche Wert. Schreibe die Meldung so, dass sie ohne den Quelltext verständlich ist.
Erwartete Fehler mit asserterror
Ein Test muss auch prüfen, dass etwas Verbotenes wirklich abgelehnt wird. asserterror dreht die Logik um: Die folgende Anweisung muss einen Fehler auslösen, sonst scheitert der Test.
[Test]
procedure LastVisitInFutureIsRejected()
var
Customer: Record Customer;
begin
// [SCENARIO] A last visit date in the future is not allowed
Initialize();
LibrarySales.CreateCustomer(Customer);
// [WHEN] The last visit is set to tomorrow
asserterror Customer.Validate("ABC Letzter Besuch", CalcDate('<+1D>', Today()));
// [THEN] The expected error is raised
Assert.ExpectedError('The last visit cannot be in the future.');
end;
asserterror ohne anschließendes ExpectedError besteht bei jedem Fehler, auch bei einem Tippfehler in deinen Testdaten. Außerdem rollt asserterror die Transaktion bis zum letzten Commit zurück; Daten, die du davor im Test angelegt hast, sind danach weg.
6Testdaten und Bibliotheken
Ein guter Test erzeugt die Daten, die er braucht, selbst. Er verlässt sich nicht darauf, dass es in CRONUS den Debitor 10000 gibt. Microsoft liefert dafür Bibliotheken, die du über die Abhängigkeit „Tests-TestLibraries“ bekommst.
| Codeunit | Beispiele |
|---|---|
"Library - Sales" | CreateCustomer, CreateSalesHeader, CreateSalesLine, PostSalesDocument |
"Library - Purchase" | CreateVendor, CreatePurchHeader, PostPurchaseDocument |
"Library - Inventory" | CreateItem, CreateItemJournalLine |
"Library - ERM" | Sachkonten, Buchungsgruppen, Fibu-Buch.-Blätter |
"Library - Random" | RandInt, RandDec, RandDate, RandText |
"Library - Utility" | GenerateGUID, GenerateRandomCode, Nummernserien |
"Library - Variable Storage" | Warteschlange, um Werte zwischen Test und Handler auszutauschen (Abschnitt 7) |
"Library - Report Dataset" | Bericht ausführen und das Dataset als XML prüfen |
Any (eigene App) | Schlanke Alternative für Zufallswerte |
Für deine eigenen Tabellen schreibst du dir eine kleine Bibliothek nach demselben Muster, etwa codeunit 50159 "ABC Library - Visit" mit CreateVisit, CreateVisitSetup und so weiter. Dann steht die Datenerzeugung an einer Stelle, und ein neues Pflichtfeld bricht nicht fünfzig Tests.
7UI-Handler
Tests laufen ohne Oberfläche. Trifft der Code auf ein Message, Confirm oder eine modale Seite, scheitert der Test mit „Unhandled UI“. Du musst jede solche Stelle mit einem Handler beantworten. Das zwingt dich, die Dialoge deiner App bewusst zu testen.
| Attribut | Fängt ab | Signatur |
|---|---|---|
[MessageHandler] | Message | (Message: Text[1024]) |
[ConfirmHandler] | Confirm | (Question: Text[1024]; var Reply: Boolean) |
[StrMenuHandler] | StrMenu | (Options: Text[1024]; var Choice: Integer; Instruction: Text[1024]) |
[PageHandler] | Nicht modale Seite (Page.Run) | (var TestPage: TestPage "X") |
[ModalPageHandler] | Modale Seite (Page.RunModal, Lookups) | (var TestPage: TestPage "X") |
[RequestPageHandler] | Anforderungsseite eines Berichts | (var RequestPage: TestRequestPage "X") |
[ReportHandler] | Berichtslauf | (var Report: Report "X") |
[SendNotificationHandler] | Notification.Send | (var Notification: Notification): Boolean |
[HyperlinkHandler] | Hyperlink | (Url: Text[1024]) |
[Test]
[HandlerFunctions('TopCustomersMessageHandler')]
procedure TopCustomersShowsCustomerWithVisits()
var
Customer: Record Customer;
Visit: Record "ABC Customer Visit";
VisitStatistics: Codeunit "ABC Visit Statistics";
begin
// [SCENARIO] The top customers message lists a customer that has visits
Initialize();
// [GIVEN] A customer with two visits in the last year
LibrarySales.CreateCustomer(Customer);
CreateVisit(Visit, Customer."No.", WorkDate());
CreateVisit(Visit, Customer."No.", WorkDate() - 10);
ExpectedCustomerNo := Customer."No.";
// [WHEN] The statistics are shown
VisitStatistics.ShowTopCustomers();
// [THEN] Verified in the message handler
end;
[MessageHandler]
procedure TopCustomersMessageHandler(Message: Text[1024])
begin
Assert.IsTrue(Message.Contains(ExpectedCustomerNo), 'Customer is missing in the top customers message.');
end;
Dazu gehört eine globale Variable ExpectedCustomerNo: Code[20]. Für mehrere Werte nimmst du die Codeunit "Library - Variable Storage" mit Enqueue im Test und Dequeue im Handler.
| Regel | Erklärung |
|---|---|
| Handler müssen benutzt werden | Ein in HandlerFunctions genannter Handler, der nicht aufgerufen wurde, lässt den Test scheitern. So merkst du, wenn ein erwarteter Dialog ausbleibt. |
| Mehrere Handler | Durch Komma getrennt: [HandlerFunctions('ConfirmYes,PostedMessage')]. |
| Ein Handler je Art | Pro Test nur ein ConfirmHandler; er bekommt alle Rückfragen der Reihe nach. Unterscheide über den Fragetext oder eine Warteschlange. |
| Fehler brauchen keinen Handler | Error fängst du mit asserterror ab. |
8Testseiten (TestPage)
Eine TestPage-Variable bedient eine Page wie ein Anwender, nur ohne Browser: öffnen, Felder füllen, Aktionen auslösen. Dabei laufen alle Page-Trigger, Feldvalidierungen und Editable-Regeln. Damit testest du die Logik, die auf der Page liegt und die ein reiner Tabellentest nicht erreicht.
[Test]
procedure VisitCanBeEnteredOnListPage()
var
Customer: Record Customer;
Visit: Record "ABC Customer Visit";
VisitList: TestPage "ABC Customer Visits";
begin
// [SCENARIO] A user can enter a visit on the list page
Initialize();
LibrarySales.CreateCustomer(Customer);
// [WHEN] The user enters a new line
VisitList.OpenNew();
VisitList."Customer No.".SetValue(Customer."No.");
VisitList."Visit Date".SetValue(WorkDate());
VisitList.Description.SetValue('Entered by test');
VisitList.Close();
// [THEN] Exactly one visit exists for the customer
Visit.SetRange("Customer No.", Customer."No.");
Assert.RecordCount(Visit, 1);
end;
| Methode | Bedeutung |
|---|---|
OpenView(), OpenEdit(), OpenNew() | Seite im Ansichts-, Bearbeitungs- oder Neuanlagemodus öffnen |
GoToRecord(Rec), GoToKey(...) | Auf einen bestimmten Datensatz springen |
First(), Next(), Last(), New() | Navigation in Listen |
Filter.SetFilter(Feld, Wert) | Filter wie über die Filterleiste |
Feld.SetValue(Wert) | Wert eingeben, löst OnValidate aus |
Feld.Value, Feld.AsInteger(), AsDecimal(), AsDate() | Angezeigten Wert lesen |
Feld.AssertEquals(Wert) | Wert prüfen |
Feld.Visible(), Enabled(), Editable() | Zustand des Steuerelements prüfen |
Feld.Lookup(), Drilldown() | Lookup oder DrillDown auslösen (braucht meist einen ModalPageHandler) |
Aktion.Invoke() | Aktion ausführen |
Teilseite.Feld... | Zugriff auf Parts, etwa Belegzeilen |
Trap() | Fängt die nächste Seite ab, die der Code mit Page.Run öffnet |
Close(), OK().Invoke(), Cancel().Invoke() | Seite schließen |
Angesprochen werden die Namen der Steuerelemente aus der Page, also der erste Teil von field(Name; Rec.Feld), nicht die Feldnamen der Tabelle. Felder aus Page Extensions erreichst du genauso über ihren Steuerelementnamen. Felder, die auf der Seite nicht sichtbar oder nicht editierbar sind, lassen sich wie beim Anwender nicht füllen.
9Isolation und Transaktionen
Tests dürfen sich nicht gegenseitig beeinflussen und sollen die Datenbank so hinterlassen, wie sie sie vorgefunden haben. Dafür sorgt der Test Runner, eine Codeunit mit Subtype = TestRunner, über die Eigenschaft TestIsolation.
TestIsolation | Wirkung |
|---|---|
Codeunit | Alle Änderungen werden nach jeder Test-Codeunit zurückgerollt, auch bereits ausgeführte Commits. Das ist der Standard des mitgelieferten Runners. |
Function | Zurückrollen nach jeder einzelnen Testprozedur. Sauberer, aber langsamer. |
Disabled | Nichts wird zurückgerollt. Nur für Sonderfälle. |
Den Runner musst du nicht selbst schreiben; die App „Test Runner“ bringt fertige mit, und im AL Test Tool wählst du den gewünschten aus. Innerhalb eines Tests steuert zusätzlich ein Attribut das Transaktionsverhalten:
[Test]
[TransactionModel(TransactionModel::AutoRollback)]
procedure SomethingWithoutCommit()
begin
...
end;
| Wert | Bedeutung |
|---|---|
AutoCommit | Standard. Am Ende der Prozedur wird festgeschrieben (und vom Runner je nach Isolation wieder zurückgerollt). Der getestete Code darf Commit aufrufen. |
AutoRollback | Alles wird am Ende zurückgerollt. Ruft der getestete Code Commit auf, gibt es einen Fehler. |
None | Der Test läuft ohne umgebende Schreibtransaktion, wie ein Aufruf aus der Oberfläche. Nötig für Tests mit Testseiten, die einen sauberen Transaktionszustand erwarten. |
Trotz Isolation gilt: Schreibe jeden Test so, dass er allein und in beliebiger Reihenfolge läuft. Was ein Test voraussetzt, legt er selbst an.
10Tests mit Berechtigungen
Auf Seite 8 hast du mit einem zweiten Benutzer von Hand geprüft, ob deine Berechtigungssätze reichen. Das lässt sich automatisieren. Die Codeunit „Permissions Mock“ (eigene App von Microsoft) tauscht innerhalb eines Tests die wirksamen Berechtigungssätze aus.
codeunit 50151 "ABC Visit Perm. Tests"
{
Subtype = Test;
TestPermissions = Disabled;
var
Assert: Codeunit "Library Assert";
LibrarySales: Codeunit "Library - Sales";
PermissionsMock: Codeunit "Permissions Mock";
[Test]
procedure EditSetCanInsertVisitAndUpdatesCustomerIndirectly()
var
Customer: Record Customer;
Visit: Record "ABC Customer Visit";
begin
// [GIVEN] A customer, created with full permissions
LibrarySales.CreateCustomer(Customer);
// [GIVEN] A user with read access to standard data and the edit set
PermissionsMock.Set('D365 READ');
PermissionsMock.Assign('ABC Visit - Edit');
// [WHEN] The user inserts a visit
Visit.Init();
Visit.Validate("Customer No.", Customer."No.");
Visit.Validate("Visit Date", WorkDate());
Visit.Insert(true);
// [THEN] The customer was updated through the indirect permission
Customer.Get(Customer."No.");
Assert.AreEqual(WorkDate(), Customer."ABC Letzter Besuch", 'Indirect modify permission did not work.');
PermissionsMock.ClearAssignments();
end;
[Test]
procedure ReadSetCannotInsertVisit()
var
Customer: Record Customer;
Visit: Record "ABC Customer Visit";
begin
LibrarySales.CreateCustomer(Customer);
// [GIVEN] A user with read-only sets
PermissionsMock.Set('D365 READ');
PermissionsMock.Assign('ABC Visit - Read');
// [WHEN] The user tries to insert a visit
Visit.Init();
Visit.Validate("Customer No.", Customer."No.");
Visit.Validate("Visit Date", WorkDate());
asserterror Visit.Insert(true);
// [THEN] A permission error is raised
Assert.AreNotEqual('', GetLastErrorText(), 'Insert should have failed.');
PermissionsMock.ClearAssignments();
end;
}
| Methode | Bedeutung |
|---|---|
Set(Name) | Ersetzt alle wirksamen Sätze durch diesen einen |
Assign(Name) | Fügt einen weiteren Satz hinzu |
ClearAssignments() | Stellt die vollen Rechte wieder her |
Der zweite Test ist schwächer, als er aussieht: Er besteht bei jedem Fehler. Besser ist eine Prüfung auf den Fehlercode oder einen Textbestandteil der Berechtigungsmeldung. Sieh dir dazu in deiner Version einmal GetLastErrorCode() im Debugger an und prüfe dann mit Assert.ExpectedErrorCode.
Die Eigenschaft TestPermissions an der Test-Codeunit ist der ältere Mechanismus: Disabled lässt alles mit vollen Rechten laufen, Restrictive und NonRestrictive arbeiten mit vordefinierten Rechtegruppen des Runners. Mit dem Permissions Mock bist du genauer, weil du deine eigenen Sätze prüfst.
11Tests ausführen
| Weg | Vorgehen | Geeignet für |
|---|---|---|
| AL Test Tool im Client | Suche „AL Test Tool“ (Page 130451) oder ?page=130451; „Test-Codeunits abrufen“, auswählen, „Ausführen“. Ergebnis je Prozedur mit Fehlertext und Aufrufliste. | Einstieg, einzelne Tests |
| VS Code | Die AL-Erweiterung zeigt Tests in neueren Versionen im Test-Explorer; verbreitet ist außerdem die Erweiterung „AL Test Runner“ (James Pearson), die Tests direkt aus dem Editor startet und das Ergebnis an der Prozedur anzeigt. | Tägliche Entwicklung |
| Debugger | launch.json der Test-App mit "startupObjectId": 130451, "startupObjectType": "Page"; Haltepunkt in den Test setzen, F5. | Fehlersuche im Test |
| PowerShell | Run-TestsInBcContainer aus BcContainerHelper | Skripte, Pipeline |
| AL-Go für GitHub | Erkennt Test-Apps im Repository, baut einen Container, führt alle Tests bei jedem Pull Request aus (Seite 10) | Automatische Absicherung |
# Alle Tests der Test-App im Container ausführen
Run-TestsInBcContainer -containerName bcdev `
-credential $credential `
-extensionId "7b1e4c92-5a3d-4f8e-b6c1-9d2a7e5f3b10" `
-detailed
12Was testen, was nicht?
| Lohnt sich | Lohnt sich kaum |
|---|---|
| Eigene Berechnungen und Prüfungen Event Subscriber auf Buchungsroutinen: Beleg anlegen, buchen, Ergebnis prüfen Durchreichen eigener Felder in gebuchte Belege und Posten Berechtigungssätze Import- und Exportformate (Stream hinein, Ergebnis prüfen) API-Pages über Testseiten oder direkte Record-Logik Jeder gemeldete Fehler als Regressionstest |
Den Standard selbst (das testet Microsoft) Reine Layoutfragen von Pages und Berichten Triviale Felder ohne Logik Externe Webdienste direkt (stattdessen die eigene Verarbeitung mit gespeicherten Antworten testen) |
Für Webaufrufe (Seite 6) baust du den Code so, dass das Senden und das Verarbeiten der Antwort getrennte Prozeduren sind. Die Verarbeitung testest du mit einem festen JSON-Text. Sauberer wird es mit einem Interface für den Aufruf, das der Test durch eine Attrappe ersetzt (Seite 5). Neuere Versionen kennen zusätzlich einen [HttpClientHandler], der ausgehende Aufrufe im Test abfängt.
Der wichtigste Nutzen in der Cloud: Du lässt deine Tests gegen die nächste Business-Central-Version laufen, bevor Microsoft sie beim Kunden einspielt. Vorschauversionen stehen als Docker-Artefakte und als Sandbox-Vorschau bereit; AL-Go kann das regelmäßig automatisch tun (Seite 10).
13Code-Analyse: die Cops
Auf Seite 2 hast du in .vscode/settings.json die Analyzer eingeschaltet. Sie prüfen den Code beim Tippen und im Build und zeigen Meldungen im Fenster „Probleme“ (Strg+Umschalt+M).
| Analyzer | Präfix | Prüft | Einsatz |
|---|---|---|---|
| Compiler | AL | Syntax, Typen, veraltete Elemente | Immer |
| CodeCop | AA | Stil und gute Praxis im Code | Immer |
| UICop | AW | Regeln für den Web-Client: Aktionen, Bilder, Seitentypen | Immer |
| PerTenantExtensionCop | PTE | Technische Vorgaben für Per-Tenant-Extensions: ID-Bereich, Präfix, Berechtigungen | Kundenspezifische Apps |
| AppSourceCop | AS | Vorgaben für AppSource, vor allem Verbot inkompatibler Änderungen gegenüber der Vorversion | AppSource-Apps; nicht zusammen mit PTE-Cop |
| LinterCop (Community) | LC | Zusätzliche Regeln, z. B. fehlende SetLoadFields-Kandidaten, Komplexität | Optional, wird als Analyzer-DLL eingebunden |
Regeln, die Umsteiger am häufigsten treffen
| Regel | Inhalt |
|---|---|
AA0005 | begin..end nur um zusammengesetzte Anweisungen |
AA0008 | Prozeduraufrufe mit Klammern: Rec.Insert(), Today() |
AA0021 | Reihenfolge der Variablendeklarationen (Record, Report, Codeunit … vor einfachen Typen) |
AA0072 | Variablennamen sollen den Objektnamen enthalten |
AA0073 | Temporäre Variablen beginnen mit Temp |
AA0074 | Labels mit Endung nach Verwendungszweck (Msg, Err, Qst, Lbl, Tok, Txt) |
AA0137 | Unbenutzte Variable |
AA0139 | Möglicher Überlauf bei Zuweisung an ein kürzeres Textfeld |
AA0175, AA0181, AA0233 | Falsche Find-Methode: gefundenen Satz nicht benutzt, FindSet ohne Next, FindFirst mit Next |
AA0210 | Filter auf Feldern ohne Schlüssel |
AA0216, AA0217 | Texte in Error, Message, StrSubstNo als Label statt als Literal |
AA0218, AA0219 | ToolTip vorhanden und beginnt mit „Specifies“ |
AA0228 | Unbenutzte lokale Prozedur |
AL0432 | Verwendung eines veralteten Elements (ObsoleteState = Pending) |
AL0604, AL0606 | Stillschweigendes oder ausdrückliches WITH |
PTE0004 | Tabelle ohne passende Berechtigung in einem Berechtigungssatz der App (Seite 8) |
Viele Meldungen behebt VS Code selbst: Cursor auf die Stelle, Strg+., und die Glühbirne bietet eine Korrektur an, teils für das ganze Projekt.
14Rulesets und Pragmas
Nicht jede Regel passt zu jedem Team. Mit einem Ruleset stellst du je Regel ein, ob sie Fehler, Warnung, Hinweis oder ausgeschaltet ist. Die Datei hast du auf Seite 2 angelegt.
{
"name": "ABC Ruleset",
"description": "Regeln fuer die ABC Kundenapp",
"rules": [
{ "id": "AA0072", "action": "None", "justification": "Kurze Variablennamen sind bei uns erlaubt." },
{ "id": "AA0137", "action": "Error", "justification": "Unbenutzte Variablen werden nicht eingecheckt." },
{ "id": "AA0218", "action": "Error", "justification": "Jedes Feld braucht einen ToolTip." },
{ "id": "AL0432", "action": "Warning", "justification": "Veraltetes sichtbar halten, aber Build nicht brechen." },
{ "id": "PTE0004","action": "Error", "justification": "Keine Tabelle ohne Berechtigungssatz." }
]
}
action | Wirkung |
|---|---|
Error | Build scheitert |
Warning | Gelbe Meldung |
Info | Blauer Hinweis |
Hidden | Nur im Editor als Punktlinie |
None | Regel abgeschaltet |
Default | Vorgabe des Analyzers |
Über includedRuleSets kann ein Ruleset ein anderes einbinden, etwa ein gemeinsames Firmen-Ruleset für alle Repositories. Das Ruleset liegt im Repository, also gelten für alle Entwickler und für die Pipeline dieselben Regeln.
Einzelne Stellen ausnehmen
#pragma warning disable AL0432
Visit."Contact No." := FindContactNo(Visit."Contact Person"); // veraltetes Feld, hier gewollt
#pragma warning restore AL0432
Ein Pragma gilt von disable bis restore. Schreibe immer dazu, warum. Für eine ganze App gibt es in app.json die Liste "suppressWarnings"; sie ist das gröbste Mittel und versteckt auch neue Fälle.
Error stellen. Ein Projekt mit dreihundert ignorierten Warnungen ist so gut wie eines ohne Analyse: Die eine wichtige neue Warnung sieht niemand.
15Debugger
Der Debugger sitzt in VS Code. Haltepunkt mit F9 in eine Zeile setzen, F5 drücken, im Browser die Stelle auslösen. VS Code hält an und zeigt Variablen, Aufrufliste und den aktuellen Datensatz.
| Taste | Wirkung |
|---|---|
| F5 | Veröffentlichen und mit Debugger starten |
| Strg+F5 | Veröffentlichen ohne Debugger |
| Strg+Umschalt+F5 | Debuggen ohne erneutes Veröffentlichen |
| Alt+F5 | Schnelles Veröffentlichen nur der geänderten Objekte (RAD) mit Debugger |
| F10 / F11 / Umschalt+F11 | Prozedurschritt / Einzelschritt hinein / hinaus |
| F5 (im Halt) | Weiterlaufen bis zum nächsten Haltepunkt |
| Umschalt+F5 | Debuggen beenden |
Was der Debugger kann
| Funktion | Beschreibung |
|---|---|
| Bedingte Haltepunkte | Rechtsklick auf den Haltepunkt, Bedingung eingeben, z. B. Customer."No." = '10000'. Unverzichtbar in Schleifen. |
| Protokollpunkte | Schreiben eine Meldung in die Debugkonsole, ohne anzuhalten. |
| Standardcode debuggen | Mit F12 in die Base Application springen und dort Haltepunkte setzen; F11 läuft in Microsoft-Code hinein. |
| Variablen | Lokale und globale Variablen, bei Records alle Felder, Filter, aktueller Schlüssel und ob der Satz temporär ist. Werte lassen sich nicht ändern. |
| Überwachen | Ausdrücke dauerhaft im Blick behalten. |
| Datenbankstatistik | Unter den Variablen: Zahl der SQL-Anweisungen und gelesenen Zeilen seit Start, dazu die letzten SQL-Anweisungen im Wortlaut. Das ist dein Ersatz für den SQL Profiler. |
| Bei Fehler anhalten | Hält an der Zeile an, die den Fehler auslöst, auch ohne Haltepunkt. |
| Bei Schreibzugriff anhalten | Hält bei jedem Insert, Modify, Delete an. Hilft bei der Frage „Wer ändert dieses Feld?“. |
Einstellungen in launch.json
{
"name": "Sandbox DEV",
"type": "al",
"request": "launch",
"environmentType": "Sandbox",
"environmentName": "DEV",
"tenant": "contoso.onmicrosoft.com",
"startupObjectId": 50100,
"startupObjectType": "Page",
"breakOnError": "ExcludeTry",
"breakOnRecordWrite": "None",
"enableSqlInformationDebugger": true,
"enableLongRunningSqlStatements": true,
"longRunningSqlStatementsThreshold": 500,
"numberOfSqlStatements": 10
},
{
"name": "An laufende Sitzung anhaengen",
"type": "al",
"request": "attach",
"environmentType": "Sandbox",
"environmentName": "DEV",
"tenant": "contoso.onmicrosoft.com",
"breakOnNext": "WebServiceClient"
}
Die zweite Konfiguration hängt den Debugger an die nächste Sitzung der angegebenen Art an, ohne etwas zu veröffentlichen. Mit "breakOnNext": "WebServiceClient" debuggst du so einen API-Aufruf aus Seite 7, mit "Background" einen Lauf der Aufgabenwarteschlange, mit "WebClient" die nächste Browser-Sitzung.
[NonDebuggable] markierte Prozeduren und Variablen (Seite 6) zeigt er nicht an.
16Snapshot-Debugging und Fehlersuche beim Kunden
In der Produktion darfst du keine Sitzung anhalten. Stattdessen zeichnest du den Ablauf auf und gehst ihn anschließend in VS Code durch wie eine Aufnahme.
{
"name": "Snapshot PROD",
"type": "al",
"request": "snapshotInitialize",
"environmentType": "Production",
"environmentName": "Production",
"tenant": "kunde.onmicrosoft.com",
"breakOnNext": "WebClient",
"userId": "anwender@kunde.de",
"executionContext": "DebugAndProfile",
"snapshotVerbosity": "SnapPoint"
}
| Schritt | Vorgehen |
|---|---|
| 1. Snappoints setzen | Wie Haltepunkte, aber als „Snappoint“. An diesen Stellen wird der Zustand der Variablen festgehalten. |
| 2. Aufzeichnung starten | F7. Die nächste Sitzung des genannten Benutzers wird aufgezeichnet. |
| 3. Fehler nachstellen | Der Anwender (oder du mit seinem Vorgehen) führt den Ablauf im Browser aus. Er merkt nichts außer etwas geringerer Geschwindigkeit. |
| 4. Aufzeichnung beenden | Alt+F7. Die Snapshot-Datei wird heruntergeladen. |
| 5. Abspielen | Umschalt+F7, Snapshot wählen. VS Code zeigt den Ablauf; du springst von Snappoint zu Snappoint und siehst Variablen und Aufrufliste. |
Der Benutzer, der aufzeichnet, braucht den Berechtigungssatz D365 SNAPSHOT DEBUG, und du brauchst die Symbole und den Quellcode genau der Version, die beim Kunden läuft. Dafür hast du auf Seite 8 den Git-Tag gesetzt. Mit "executionContext": "Profile" entsteht statt eines Debug-Snapshots ein Leistungsprofil (Abschnitt 18).
Weitere Hilfen ohne Entwicklerwerkzeug
| Werkzeug | Wo | Nutzen |
|---|---|---|
| Seitenprüfung | Strg+Alt+F1 | Tabelle, Felder, Filter, beteiligte Erweiterungen der aktuellen Seite |
| Letzter Fehler | „Hilfe und Support“ → Problembehandlung | Fehlertext mit AL-Aufrufliste; der Anwender kann sie kopieren und dir schicken |
| Ereignisaufzeichnung | Suche „Ereignisaufzeichnung“ | Welche Events löst ein Ablauf aus? (Seite 5) |
| Leistungsprofiler | Suche „Leistungsprofiler“ | Ablauf aufzeichnen, Zeitanteile je App und Prozedur sehen |
| Datenbanksperren | Suche „Datenbanksperren“ | Wer sperrt gerade was? |
| Tabelleninformationen | Suche „Tabelleninformationen“ | Satzanzahl und Größe je Tabelle |
| Effektive Berechtigungen | Benutzerkarte | Woher kommt ein Recht, wo fehlt es? (Seite 8) |
| Telemetrie | Application Insights | Fehler, lange Abfragen, Sperren im Rückblick (Abschnitt 19) |
17Leistung: Datenzugriff
In NAV 2017 konntest du langsamen Code mit einem stärkeren Server und einem Index direkt auf dem SQL Server retten. In der Cloud teilst du dir die Ressourcen, es gibt Zeitlimits, und an den SQL Server kommst du nicht heran. Leistung entsteht im AL-Code.
Teilsätze mit SetLoadFields
Standardmäßig lädt jede Leseoperation alle Felder der Tabelle und, per Join, alle Felder aller Table Extensions. Bei einer Tabelle wie Debitor mit mehreren installierten Apps ist das viel. SetLoadFields beschränkt das Laden auf die genannten Felder.
Vorher
if Customer.FindSet() then
repeat
Total += Customer."Credit Limit (LCY)";
until Customer.Next() = 0;
Nachher
Customer.SetLoadFields("Credit Limit (LCY)");
if Customer.FindSet() then
repeat
Total += Customer."Credit Limit (LCY)";
until Customer.Next() = 0;
| Regel | Erklärung |
|---|---|
| Vor dem Lesen setzen | SetLoadFields wirkt auf das nächste Get, Find… oder Next. |
| Immer geladen | Primärschlüssel, Systemfelder und Felder mit gesetztem Filter. |
| Nachladen | Greifst du auf ein nicht geladenes Feld zu, lädt die Plattform es nach. Das funktioniert, kostet aber eine zusätzliche Abfrage je Datensatz. In einer Schleife ist das schlimmer als gar kein SetLoadFields. |
| Schreiben | Vor Modify, Delete, Rename oder TransferFields lädt die Plattform den ganzen Satz nach. Für Schleifen, die ändern, bringt es wenig. |
| Übergabe an andere Prozeduren | Vorsicht: Die aufgerufene Prozedur weiß nicht, welche Felder fehlen. Nutze Teilsätze dort, wo du den ganzen Lesevorgang überblickst. |
| Berichte und Pages | Laden von sich aus nur die verwendeten Felder; dort musst du nichts tun. |
Die richtige Lesemethode
| Absicht | Richtig | Falsch |
|---|---|---|
| Gibt es einen Satz? | if not Rec.IsEmpty() then | if Rec.FindFirst() then, if Rec.Count() > 0 then |
| Genau einen Satz lesen | Get oder FindFirst / FindLast | FindSet, Find('-') |
| Alle Sätze durchlaufen | FindSet() mit Next() | FindFirst mit Next |
| Durchlaufen und ändern | FindSet(true) | FindSet() ohne Sperrabsicht, dann Modify |
| Summe bilden | CalcSums, FlowField, Query | Schleife mit Addition |
| Alle Sätze gleich ändern | ModifyAll, DeleteAll | Schleife mit Modify / Delete |
| Zwei Tabellen verknüpft auswerten | Query (Seite 7) | Verschachtelte Schleifen |
| Anzahl für eine Anzeige | Count nur wenn nötig, sonst IsEmpty | Count in jeder Zeile einer Liste |
// Summe ohne Schleife
CustLedgerEntry.SetRange("Customer No.", CustomerNo);
CustLedgerEntry.SetRange(Open, true);
CustLedgerEntry.CalcSums("Sales (LCY)");
Total := CustLedgerEntry."Sales (LCY)";
Schlüssel und Filter
Filterst oder sortierst du regelmäßig nach einem Feld, braucht die Tabelle einen passenden Schlüssel. In eigenen Tabellen legst du ihn im Abschnitt keys an, für Standardtabellen in der Table Extension (nur über Standardfelder oder nur über eigene Felder, Seite 3). SetCurrentKey bestimmt nur die Sortierung; welchen Index der SQL Server zum Filtern nimmt, entscheidet er selbst. Zu viele Schlüssel bremsen das Schreiben, lege also nur an, was du brauchst.
Weitere Bremsen
| Bremse | Abhilfe |
|---|---|
Code im OnAfterGetRecord einer Listenseite | Läuft für jede sichtbare Zeile. Nichts Teures dort; Werte als FlowField oder im OnAfterGetCurrRecord berechnen. |
| Viele FlowFields auf einer Liste | Jedes ist eine Unterabfrage je Zeile. Nur zeigen, was gebraucht wird; passende SumIndexFields anlegen. |
| FactBox mit schwerer Berechnung | Page Background Task (Seite 5): Die Seite öffnet sofort, der Wert kommt nach. |
| Subscriber auf Datenbank-Events vielgenutzter Tabellen | Läuft bei jedem Schreibzugriff. Als Erstes if Rec.IsTemporary() then exit; und die billigste Bedingung prüfen. |
| Wiederholtes Lesen der Einrichtung in Schleifen | Einmal vor der Schleife lesen oder in einer SingleInstance-Codeunit zwischenspeichern. |
Einzelne Insert-Aufrufe mit Zwischenabfragen | Die Plattform bündelt aufeinanderfolgende Inserts. Ein Find auf dieselbe Tabelle oder die Abfrage des Rückgabewerts von Insert unterbricht die Bündelung. |
| Zwischenergebnisse in echten Tabellen | Temporäre Tabellen, Listen und Dictionaries leben im Speicher. |
| Große Auswertungen auf der Hauptdatenbank | DataAccessIntent = ReadOnly an Berichten, Queries und API-Pages (Seite 7). |
| Texte in Schleifen zusammensetzen | TextBuilder (Seite 6). |
18Leistung: Sperren und Profiler
Sperren
Die meisten Klagen über „Business Central hängt“ sind Sperren: Eine Sitzung hält Datensätze fest, andere warten und laufen in die Zeitüberschreitung. Die Grundregeln sind dieselben wie früher, die Mittel sind feiner geworden.
| Regel | Erklärung |
|---|---|
| Transaktionen kurz halten | Erst lesen, rechnen und prüfen, dann gebündelt schreiben. Keine Webaufrufe und keine Dialoge in einer offenen Schreibtransaktion. |
LockTable spät und selten | Nach LockTable sperrt jedes Lesen dieser Tabelle bis zum Transaktionsende. Am Anfang einer langen Routine ist das eine Vollbremsung für alle. |
| Immer in derselben Reihenfolge sperren | Zwei Routinen, die dieselben Tabellen in umgekehrter Reihenfolge sperren, erzeugen Deadlocks. |
| Leseisolation gezielt wählen | Rec.ReadIsolation stellt je Record-Variable ein, wie gelesen wird, statt per LockTable die ganze Tabelle zu betreffen. |
| Nummernserien und Einrichtungssätze | Klassische Engstellen: Wer die Nummernserienzeile ändert, sperrt sie für alle. So spät wie möglich in der Transaktion ziehen. |
// Nur zählen oder anzeigen: nicht auf fremde Schreibsperren warten
Visit.ReadIsolation := IsolationLevel::ReadUncommitted;
VisitCount := Visit.Count();
// Lesen mit Änderungsabsicht: nur diese Sätze sperren
Visit.ReadIsolation := IsolationLevel::UpdLock;
Visit.SetRange("Customer No.", CustomerNo);
if Visit.FindSet() then ...
| Wert | Bedeutung |
|---|---|
Default | Verhalten der Plattform je nach Transaktionszustand |
ReadUncommitted | Liest auch noch nicht festgeschriebene Daten anderer, wartet nie. Für Anzeigen und Schätzungen. |
ReadCommitted | Liest nur Festgeschriebenes, hält keine Sperren |
RepeatableRead | Gelesene Sätze bleiben bis zum Transaktionsende für andere unveränderbar |
UpdLock | Gelesene Sätze werden zum Ändern reserviert, wie früher nach LockTable |
Profiler
Miss, bevor du optimierst. Zwei Werkzeuge zeigen dir, wo die Zeit bleibt.
| Werkzeug | Vorgehen | Ergebnis |
|---|---|---|
| Leistungsprofiler im Client | Seite „Leistungsprofiler“ öffnen, Aufzeichnung starten, Ablauf ausführen, stoppen | Zeit je App und je Prozedur; die Datei lässt sich herunterladen und in VS Code öffnen. Auch der Kunde kann das selbst tun und dir die Datei schicken. |
| AL-Profiler in VS Code | Snapshot-Konfiguration mit "executionContext": "Profile", F7 / Alt+F7, dann AL: Generate profile file | .alcpuprofile-Datei mit Aufrufbaum, Eigenzeit und Gesamtzeit je Prozedur, Sprung in den Quelltext |
Lies das Ergebnis von oben: Welche App verbraucht den größten Anteil, welche Prozedur darin, wie oft wurde sie aufgerufen? Eine Prozedur mit zehntausend Aufrufen und wenig Eigenzeit deutet auf eine Schleife hin, die es nicht geben sollte. Ergänzend zeigt dir die Datenbankstatistik im Debugger (Abschnitt 15), wie viele SQL-Anweisungen ein Ablauf erzeugt. Zähle sie vor und nach deiner Änderung.
19Telemetrie
Telemetrie ist der Ersatz für die Ereignisanzeige des Servers, nur viel reicher. Business Central sendet technische Ereignisse an eine Azure-Application-Insights-Ressource, die du auswertest.
| Ebene | Einrichtung | Wer sieht was? |
|---|---|---|
| Umgebung | Im Admin Center an der Umgebung die Verbindungszeichenfolge eintragen | Kunde oder betreuender Partner: alles, was in dieser Umgebung passiert, über alle Apps |
| App | In app.json: "applicationInsightsConnectionString": "InstrumentationKey=...;IngestionEndpoint=..." | Der Herausgeber: alles, was seine App betrifft, über alle Kunden hinweg |
Was von selbst ankommt
| Signal | Nutzen |
|---|---|
| Lang laufende SQL-Abfragen | Mit SQL-Text und AL-Aufrufliste: Du siehst, welche Zeile deines Codes die Abfrage ausgelöst hat |
| Lang laufende AL-Methoden | Kandidaten für die Optimierung |
| Sperrzeitüberschreitungen und Deadlocks | Wer hat gewartet, wer hat gesperrt |
| Fehlerdialoge | Welche Fehlermeldungen sehen Anwender wie oft |
| Lebenszyklus von Erweiterungen | Installation, Upgrade und deren Fehlschläge (Seite 8) |
| Webdienst- und API-Aufrufe | Dauer, Statuscode, Endpunkt |
| Ausgehende HTTP-Aufrufe | Dauer und Ergebnis deiner HttpClient-Aufrufe |
| Aufgabenwarteschlange | Start, Ende, Fehler |
| Berichte | Laufzeit, Zeilenzahl, Layouttyp |
| Berechtigungsfehler | Fehlende Rechte je Objekt |
Eigene Signale senden
local procedure LogVisitCreated(Visit: Record "ABC Customer Visit")
var
Dimensions: Dictionary of [Text, Text];
begin
Dimensions.Add('VisitType', Format(Visit."Visit Type"));
Session.LogMessage(
'ABC0001', // eigene, eindeutige Ereignis-ID
'Customer visit created', // fester Text ohne Kundendaten
Verbosity::Normal,
DataClassification::SystemMetadata,
TelemetryScope::ExtensionPublisher,
Dimensions);
end;
| Parameter | Erklärung |
|---|---|
| Ereignis-ID | Frei wählbar, mit deinem Präfix. Führe eine Liste im Repository, damit jede ID nur eine Bedeutung hat. |
Verbosity | Critical, Error, Warning, Normal, Verbose |
DataClassification | Nur SystemMetadata wird tatsächlich gesendet. Das ist Absicht: keine Kundendaten in die Telemetrie. |
TelemetryScope | ExtensionPublisher: nur an die Ressource aus app.json. All: zusätzlich an die Ressource der Umgebung. |
| Dimensionen | Zusätzliche Werte als Text. In Application Insights erscheinen sie mit dem Präfix al, hier also alVisitType. |
Die System Application bietet darüber eine bequemere Schicht, die Codeunit „Feature Telemetry“ mit LogUsage, LogUptake und LogError. Damit misst du, ob eine Funktion entdeckt, eingerichtet und benutzt wird.
Auswerten mit KQL
// Wie oft wurden Besuche angelegt, je Tag und Besuchsart?
traces
| where timestamp > ago(30d)
| where customDimensions.eventId == 'ABC0001'
| summarize Anzahl = count() by bin(timestamp, 1d), tostring(customDimensions.alVisitType)
// Die langsamsten SQL-Abfragen aus meiner App in den letzten 7 Tagen
traces
| where timestamp > ago(7d)
| where customDimensions.eventId == 'RT0005'
| where customDimensions.extensionName == 'ABC Kundenapp'
| project timestamp,
Dauer = customDimensions.executionTime,
SQL = customDimensions.sqlStatement,
Aufrufliste = customDimensions.alStackTrace
| order by timestamp desc
Die Abfragen laufen im Azure-Portal unter „Protokolle“ der Application-Insights-Ressource. Microsoft stellt fertige Power-BI-Berichte für Umgebungs- und App-Telemetrie bereit sowie eine Sammlung von Beispielabfragen auf GitHub. Auf Signale lassen sich Warnungen legen, etwa eine E-Mail, wenn ein Upgrade deiner App fehlschlägt.
20Übung: Die Besuchsverwaltung absichern
Schritt 1 – Test-App anlegen
Lege im Repository den Ordner test an, erzeuge darin mit AL: Go! ein Projekt und ersetze app.json durch die Fassung aus Abschnitt 2 (eigene GUID behalten). Lösche die Beispieldatei. Kopiere launch.json aus dem Ordner app und setze "startupObjectId": 130451. Nimm den Ordner in die Workspace-Datei auf:
{
"folders": [
{ "path": "app" },
{ "path": "test" }
]
}
Schritt 2 – Testbibliotheken bereitstellen
Richte die Umgebung nach Abschnitt 3 ein, lade im Ordner test die Symbole und veröffentliche zuerst die Haupt-App.
Schritt 3 – Funktionstests test/src/ABCVisitTests.Codeunit.al
Übernimm codeunit 50150 "ABC Visit Tests" aus Abschnitt 4 und ergänze die Tests aus den Abschnitten 5, 7 und 8 samt der globalen Variablen ExpectedCustomerNo: Code[20]. Veröffentliche die Test-App, öffne das AL Test Tool, rufe die Test-Codeunits ab und führe sie aus.
| Test | Prüft |
|---|---|
InsertVisitUpdatesLastVisitOnCustomer | Tabellentrigger aus Seite 3 |
LastVisitInFutureIsRejected | Feldvalidierung aus Seite 2 |
TopCustomersShowsCustomerWithVisits | Query und Meldung aus Seite 7, mit Handler |
VisitCanBeEnteredOnListPage | Page aus Seite 4 über eine Testseite |
Schritt 4 – Einen Test scheitern sehen
Kommentiere in der Haupt-App die Zeile aus, die „ABC Letzter Besuch“ am Debitor setzt, veröffentliche und führe die Tests aus. Der erste Test muss rot werden. Sieh dir Meldung und Aufrufliste im Test Tool an, nimm die Änderung zurück und prüfe, dass wieder alles grün ist.
Schritt 5 – Berechtigungstests test/src/ABCVisitPermTests.Codeunit.al
Ergänze in test/app.json die Abhängigkeit auf die App „Permissions Mock“ (ID, Name und Version aus der Erweiterungsverwaltung übernehmen), lade die Symbole neu und übernimm codeunit 50151 aus Abschnitt 10. Entferne danach probeweise in der Haupt-App die Zeile tabledata Customer = m aus dem Satz „ABC Visit - Edit“: Der erste Berechtigungstest muss scheitern.
Schritt 6 – Ruleset schärfen
Ersetze den Inhalt von app/abc.ruleset.json durch das Ruleset aus Abschnitt 14. Baue mit Strg+Umschalt+B und behebe alle Fehler. Für die Test-App legst du ein eigenes, lockereres Ruleset an (ToolTips und Übersetzungsregeln sind dort unnötig).
Schritt 7 – Debugger und SQL-Statistik
Setze in ShowTopCustomers (Codeunit 50111) einen Haltepunkt auf VisitsPerCustomer.Open() und einen auf Message. Starte mit F5, löse die Aktion „Top Customers“ aus und notiere aus der Datenbankstatistik die Zahl der SQL-Anweisungen zwischen den beiden Haltepunkten. Schreibe zum Vergleich in der Test-App eine Prozedur, die dasselbe mit zwei verschachtelten Schleifen über Debitoren und Besuche ermittelt, und vergleiche die Zahl.
Schritt 8 – SetLoadFields einsetzen
Im Verarbeitungsbericht report 50101 "ABC Update Last Visit" (Seite 7) wird je Debitor der letzte Besuch gelesen, gebraucht wird nur das Datum:
Visit.SetLoadFields("Visit Date");
Visit.SetRange("Customer No.", Customer."No.");
Visit.SetCurrentKey("Customer No.", "Visit Date");
if not Visit.FindLast() then
CurrReport.Skip();
Prüfe im Debugger an den letzten SQL-Anweisungen, dass die Abfrage auf die Besuchstabelle jetzt nur noch wenige Spalten nennt.
Schritt 9 – Telemetrie
Lege in Azure eine Application-Insights-Ressource an (kostenloses Kontingent genügt) und trage ihre Verbindungszeichenfolge in app/app.json ein. Ergänze LogVisitCreated aus Abschnitt 19 in codeunit 50105 "ABC Visit Subscribers" und rufe sie aus einem Subscriber auf OnAfterInsertEvent der Besuchstabelle auf (zuerst if Rec.IsTemporary() then exit;). Lege einige Besuche an, warte einige Minuten und führe die erste KQL-Abfrage aus Abschnitt 19 aus.
Schritt 10 – Einchecken
git add .
git commit -m "Test-App, Berechtigungstests, Ruleset, SetLoadFields, Telemetrie"
git push
21Typische Fallen
| Falle | Was passiert | Abhilfe |
|---|---|---|
| Tests in der Haupt-App | Testcode und Abhängigkeit zu Testbibliotheken landen beim Kunden; Installation scheitert in Produktion | Eigene Test-App |
| Test verlässt sich auf CRONUS-Daten | Läuft lokal, scheitert in der Pipeline oder in der nächsten Version | Daten im Test selbst erzeugen |
asserterror ohne Prüfung des Fehlers | Test besteht auch bei falschem Fehler | Immer Assert.ExpectedError oder ExpectedErrorCode |
| Dialog ohne Handler | „Unhandled UI“ | Passenden Handler ergänzen und in HandlerFunctions nennen |
| Handler genannt, aber nicht ausgelöst | Test scheitert am Ende | Richtig so: Der erwartete Dialog fehlt. Code oder Test korrigieren |
| Erwarteter und tatsächlicher Wert vertauscht | Irreführende Fehlermeldung | Erst erwartet, dann tatsächlich |
| Tests hängen voneinander ab | Einzeln rot, zusammen grün (oder umgekehrt) | Jeder Test legt seine Voraussetzungen selbst an |
internal-Prozedur aus der Test-App aufgerufen | Compilerfehler | internalsVisibleTo in der Haupt-App |
| Nur als SUPER getestet | Berechtigungsfehler erst beim Kunden | Tests mit Permissions Mock |
| Warnungen ignoriert | Wichtige neue Warnung geht unter; veraltete Elemente fallen erst beim Update auf | Warnungen auf null, wichtige Regeln als Fehler |
Pragma ohne restore | Regel bleibt für den Rest der Datei aus | Immer paarweise, mit Begründung |
| Debugger in gemeinsamer Sandbox angehalten | Kollegen warten auf deine Sperren | Eigener Container oder eigene Sandbox |
SetLoadFields und dann doch andere Felder gelesen | Zusätzliche Abfrage je Datensatz, langsamer als vorher | Alle gebrauchten Felder nennen; im Debugger die SQL-Zahl prüfen |
FindFirst in einer Schleife mit Next | Jeder Next wird eine eigene Abfrage | FindSet |
Count für die Frage „gibt es etwas?“ | Zählt alle Sätze | IsEmpty |
LockTable am Anfang einer langen Routine | Alle anderen Benutzer warten | Spät sperren, ReadIsolation gezielt setzen |
| Optimiert ohne zu messen | Aufwand an der falschen Stelle | Profiler und SQL-Statistik vorher und nachher |
| Kundendaten in der Telemetrie | Datenschutzverstoß | Nur technische Angaben, SystemMetadata |
| Telemetrie eingerichtet, nie angesehen | Probleme bleiben unbemerkt bis zur Beschwerde | Warnungen auf Upgrade-Fehler und lange Abfragen, regelmäßiger Blick in den Bericht |
22Selbsttest und Zusammenfassung
Selbsttest
- Warum liegen Tests in einer eigenen App, und wie erreicht die Test-App
internal-Prozeduren der Haupt-App? - Was macht
asserterror, und warum brauchst du danach immer eine weitere Prüfung? - Dein Test scheitert mit „Unhandled UI: Confirm“. Was fehlt?
- Wann nimmst du eine Testseite statt eines direkten Zugriffs auf Records?
- Wie prüfst du automatisiert, dass ein Benutzer mit deinem Edit-Satz einen Besuch anlegen kann?
- Was bewirkt
"action": "Error"im Ruleset, und wann nimmst du ein Pragma? - Du sollst einen Fehler untersuchen, der nur in der Produktion bei einer bestimmten Anwenderin auftritt. Wie gehst du vor?
- Was tut
SetLoadFields, und wann macht es den Code langsamer? - Welche Methode nimmst du für „gibt es einen Satz?“, „lies den letzten Satz“, „durchlaufe alle Sätze“?
- Was darf in ein eigenes Telemetriesignal, was nicht?
Lösungen anzeigen
- Damit Testcode und Testbibliotheken nicht beim Kunden landen. Zugriff auf Internes gibt die Haupt-App über
internalsVisibleToin ihrerapp.json. - Die folgende Anweisung muss einen Fehler auslösen, sonst scheitert der Test. Da jeder beliebige Fehler genügt, prüfst du mit
Assert.ExpectedErroroderExpectedErrorCode, dass es der richtige war. - Eine Prozedur mit
[ConfirmHandler], die die Rückfrage beantwortet, und ihr Name im Attribut[HandlerFunctions('...')]am Test. - Wenn die zu prüfende Logik auf der Page liegt: Sichtbarkeit, Editierbarkeit, Aktionen, Page-Trigger, Zusammenspiel von Kopf und Zeilen. Reine Geschäftslogik testest du über Records und Codeunits.
- Im Test mit der Codeunit „Permissions Mock“ die wirksamen Sätze auf einen Standardsatz plus den Edit-Satz setzen, den Besuch anlegen und das Ergebnis prüfen; danach die Zuweisung zurücksetzen.
- Die Regel lässt den Build scheitern. Ein Pragma nimmst du, um eine einzelne, begründete Stelle auszunehmen, ohne die Regel insgesamt abzuschalten.
- Snapshot-Debugging: Quellcode der ausgelieferten Version auschecken, Snappoints setzen, Aufzeichnung für die Benutzerin starten, Ablauf ausführen lassen, Aufzeichnung beenden und in VS Code durchgehen. Ergänzend die Aufrufliste des letzten Fehlers und die Telemetrie.
- Es beschränkt das Laden auf die genannten Felder. Langsamer wird es, wenn du danach doch auf nicht geladene Felder zugreifst: Dann lädt die Plattform je Datensatz nach.
IsEmpty;FindLast;FindSetmitNext.- Erlaubt sind technische Angaben wie Vorgangsart, Anzahl, Dauer, Enum-Werte. Nicht erlaubt sind personenbezogene und geschäftliche Daten wie Namen, Beträge, Belegnummern.
Zusammenfassung
Qualität ist in Business Central kein Abschluss am Projektende, sondern läuft mit: Eine Test-App neben der Haupt-App prüft Logik, Oberfläche und Berechtigungen automatisch, und zwar auch gegen die nächste Plattformversion. Die Analyzer mit einem gemeinsamen Ruleset halten den Code einheitlich und fangen veraltete Elemente früh ab. Der Debugger in VS Code zeigt neben Variablen auch die SQL-Anweisungen, der Snapshot-Debugger macht Fehlersuche in der Produktion möglich. Leistung entsteht durch den richtigen Datenzugriff: passende Find-Methode, Teilsätze, Queries, kurze Transaktionen. Und die Telemetrie zeigt dir, was beim Kunden wirklich passiert, bevor er anruft.
Weiter mit Seite 10: Arbeiten mit Git-Branches und Pull Requests, AL-Go für GitHub mit Build- und Testpipeline, Versionierung und Auslieferung in den Tenant, Claude Code im Repository mit CLAUDE.md und AL-Werkzeugen, Umwandlung von altem C/AL-Code mit Txt2AL und der Weg der NAV-2017-Daten in die Cloud.