ErrorInfo melden. Das ist die wichtigste Seite des Kurses, weil hier der Ersatz für „Code im Standard ändern“ steht.
1C/AL und AL: die Unterschiede in der Schreibweise
| C/AL (NAV 2017) | AL (Business Central) | Anmerkung |
|---|---|---|
Customer.FINDSET | Customer.FindSet() | PascalCase und Klammern, auch ohne Parameter. |
IF … THEN BEGIN … END ELSE | if … then begin … end else | Schlüsselwörter klein. Der Compiler akzeptiert beides, der Formatierer stellt um. |
Cust : Record 18; | Customer: Record Customer; | Name statt Nummer. |
Text001 : TextConst 'DEU=…;ENU=…' | CustomerBlockedErr: Label '…'; | Sprechender Name mit Endung (Seite 4). |
CODEUNIT.RUN(80,SalesHeader) | Codeunit.Run(Codeunit::"Sales-Post", SalesHeader) | |
PAGE.RUNMODAL(21,Cust) | Page.RunModal(Page::"Customer Card", Customer) | |
DATABASE::Customer | Database::Customer | |
| Option-Variable | Enum "…" | Seite 3. |
WITH Cust DO | Entfällt | Abschnitt 2. |
Funktion mit Local=Yes | local procedure | Abschnitt 3. |
Rückgabewert über EXIT(Wert) | exit(Wert) oder benannter Rückgabewert | procedure Calc() Result: Decimal |
| Ein Funktionsname, eine Funktion | Überladung erlaubt | Gleicher Name mit unterschiedlichen Parametern. |
FOR i := 1 TO … | Zusätzlich foreach … in … | Für Listen, Enums, JSON (Seite 6). |
| Text mit fester Länge | Text ohne Länge ist unbegrenzt | Dazu Methoden wie .Contains(), .Replace(), .Split() (Seite 6). |
| Dokumentationstrigger | Kommentare //, /* */ und /// für XML-Dokumentation | ///-Kommentare erscheinen in IntelliSense. |
Ein typisches Stück Code im Vergleich
PROCEDURE CountOpenOrders@1(CustNo@1000 : Code[20]) : Integer;
VAR
SalesHeader@1001 : Record 36;
Cnt@1002 : Integer;
BEGIN
WITH SalesHeader DO BEGIN
SETRANGE("Document Type","Document Type"::Order);
SETRANGE("Sell-to Customer No.",CustNo);
SETRANGE(Status,Status::Open);
IF FINDSET THEN
REPEAT
Cnt += 1;
UNTIL NEXT = 0;
END;
EXIT(Cnt);
END;
procedure CountOpenOrders(CustomerNo: Code[20]): Integer
var
SalesHeader: Record "Sales Header";
begin
SalesHeader.SetRange("Document Type",
SalesHeader."Document Type"::Order);
SalesHeader.SetRange("Sell-to Customer No.", CustomerNo);
SalesHeader.SetRange(Status,
SalesHeader.Status::Open);
exit(SalesHeader.Count());
end;
Neuere Sprachmittel
| Sprachmittel | Beispiel |
|---|---|
| Mehrere Variablen in einer Zeile | FromDate, ToDate: Date; |
| Benannter Rückgabewert | procedure GetName() Result: Text |
| Bedingter Operator | Style := IsLate ? 'Attention' : 'Standard'; |
this | this.Calculate(); als ausdrücklicher Verweis auf das eigene Objekt |
| Präprozessor | #if, #region, #pragma warning disable AA0137 |
| Attribute | [Obsolete('Use NewProc instead.', '2.0')], [TryFunction], [NonDebuggable] |
Die letzten Sprachmittel hängen von der runtime in deiner app.json ab. Der Compiler meldet es, wenn eines für deine Zielversion noch nicht verfügbar ist.
Namespaces
Seit Version 23 ordnet Microsoft die Objekte der Base Application in Namespaces ein, z. B. Microsoft.Sales.Customer. Du kannst für deine App ebenfalls einen Namespace vergeben:
namespace MeineFirma.Kundenapp.Besuche;
using Microsoft.Sales.Customer;
using Microsoft.Sales.Document;
using Microsoft.Sales.Posting;
codeunit 50101 "ABC Sales Post Checks"
{
...
}
- Der Namespace steht in der ersten Zeile der Datei. Mit
usingmachst du Objekte aus anderen Namespaces ohne vollen Namen verfügbar. - VS Code bietet fehlende
using-Zeilen als Schnellkorrektur an (Strg+.). - Namespaces sind freiwillig. Die Beispiele dieses Kurses kommen ohne aus. Für neue Projekte sind sie empfehlenswert, weil sie Namenskonflikte entschärfen. Das Präfix an Objekten brauchst du für PTEs trotzdem.
2Der Abschied von WITH
WITH war bequem, aber gefährlich für Erweiterungen: Fügt Microsoft einer Tabelle ein Feld hinzu, das so heißt wie eine deiner Variablen, ändert sich die Bedeutung deines Codes, ohne dass der Compiler etwas meldet. Deshalb wurde WITH abgeschafft, und zwar in zwei Formen:
| Form | Früher | Heute |
|---|---|---|
| Ausdrückliches WITH | WITH SalesHeader DO … | Nicht mehr erlaubt. Variable ausschreiben. |
| Stillschweigendes WITH auf Seiten | "No." meinte automatisch Rec."No." | Rec."No." schreiben. |
Stillschweigendes WITH in Codeunits mit TableNo | Felder ohne Rec. | Rec. schreiben. |
| In Tabellen und Table Extensions | Felder ohne Rec. | Weiterhin erlaubt, Rec. ist dort optional. |
Beim Umbau alten Codes ist das die meiste Tipparbeit. VS Code bietet für das Ergänzen von Rec. eine Schnellkorrektur an, die sich auf die ganze Datei oder das ganze Projekt anwenden lässt.
3Sichtbarkeit von Funktionen und Variablen
| Schlüsselwort | Sichtbar für | Wann verwenden |
|---|---|---|
local procedure | Nur das eigene Objekt | Standard für alles, was niemand sonst braucht. |
internal procedure | Alle Objekte der eigenen App | Hilfsfunktionen, die du in der App mehrfach nutzt, die aber kein fremder Code aufrufen soll. |
protected procedure | Das Objekt und seine Erweiterungen | In Tabellen, Seiten und Berichten, wenn Extensions darauf zugreifen sollen. |
procedure (ohne Zusatz) | Alle, auch andere Apps | Deine öffentliche Schnittstelle. Bewusst klein halten. |
protected var | Globale Variablen für Erweiterungen sichtbar | Selten. |
Dazu kommt die Objekteigenschaft Access = Internal;, die ein ganzes Objekt vor anderen Apps verbirgt.
local als Normalfall an.
4Codeunits
codeunit 50100 "ABC Visit Mgt."
{
Access = Public;
Permissions = tabledata "ABC Customer Visit" = rim;
procedure CreateVisit(CustomerNo: Code[20]; VisitDate: Date): Integer
begin
...
end;
local procedure CheckDate(VisitDate: Date)
begin
...
end;
}
| Eigenschaft | Bedeutung |
|---|---|
Subtype | Normal, Test, TestRunner (Seite 9), Install, Upgrade (Seite 8). |
TableNo | Die Codeunit bekommt einen Datensatz als Rec übergeben, wie früher. Nötig für Codeunit.Run(…, Rec) und für die Aufgabenwarteschlange. |
SingleInstance | Eine Instanz pro Sitzung, globale Variablen behalten ihren Wert. Wie früher, nützlich für Zwischenspeicher und Schalter. |
EventSubscriberInstance | StaticAutomatic (Standard) oder Manual (Abschnitt 9). |
Access | Public oder Internal. |
Permissions, InherentPermissions | Rechte, die der Code unabhängig vom Benutzer hat (Seite 8). |
Empfehlung zum Schnitt: Lieber mehrere kleine Codeunits mit klarer Aufgabe als eine große „ABC Functions“. Üblich ist die Trennung in Geschäftslogik (z. B. „ABC Visit Mgt.“) und Subscriber (z. B. „ABC Sales Subscribers“), wobei die Subscriber nur die Logik aufrufen und selbst kaum Code enthalten.
5Events: das Grundprinzip
Ein Event besteht aus zwei Teilen:
- Publisher: Eine leere Funktion mit einem Attribut. Sie wird an einer bestimmten Stelle im Code aufgerufen und sagt damit „hier darf sich jemand einhängen“.
- Subscriber: Eine Funktion in einer beliebigen Codeunit, die sich über ein Attribut für dieses Event anmeldet. Die Plattform ruft sie auf, sobald der Publisher aufgerufen wird.
// Im Standard, Codeunit "Sales-Post" (vereinfacht)
procedure Run(var SalesHeader: Record "Sales Header")
begin
OnBeforePostSalesDoc(SalesHeader, ...); // Publisher wird aufgerufen
...
end;
[IntegrationEvent(false, false)]
local procedure OnBeforePostSalesDoc(var SalesHeader: Record "Sales Header"; ...)
begin
end;
// In deiner App
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post", 'OnBeforePostSalesDoc', '', false, false)]
local procedure CheckOnBeforePostSalesDoc(var SalesHeader: Record "Sales Header")
begin
// dein Code
end;
Die Arten von Events
| Art | Woher | Beispiele |
|---|---|---|
| Integration Events | Von Microsoft oder anderen Entwicklern im Code platziert | OnBeforePostSalesDoc, OnAfterCopySellToCustomerAddressFieldsFromCustomer |
| Business Events | Wie Integration Events, mit dem Versprechen, dass sich die Signatur nicht ändert | Im Standard selten |
| Internal Events | Nur innerhalb derselben App abonnierbar | Für dich als Subscriber nicht nutzbar |
| Datenbank-Trigger-Events | Automatisch für jede Tabelle vorhanden | OnBeforeInsertEvent, OnAfterModifyEvent, OnAfterValidateEvent |
| Seiten-Trigger-Events | Automatisch für jede Seite vorhanden | OnOpenPageEvent, OnAfterGetCurrRecordEvent, OnAfterActionEvent |
6Events abonnieren
Das Attribut im Detail
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post", 'OnBeforePostSalesDoc', '', false, false)]
// │ │ │ │ │ │
// │ │ │ │ │ └ SkipOnMissingPermission
// │ │ │ │ └ SkipOnMissingLicense
// │ │ │ └ Element (Feld- oder Aktionsname, sonst leer)
// │ │ └ Name des Events
// │ └ Objekt, das das Event veröffentlicht
// └ Objekttyp: Codeunit, Table, Page, Report, XmlPort, Query
- Der Name deiner Funktion ist frei. Üblich ist eine Kombination aus Zweck und Eventname.
- Die Parameter werden über Name und Typ zugeordnet. Du darfst Parameter weglassen, die du nicht brauchst, aber keine umbenennen oder im Typ ändern.
- Willst du einen Wert an den Aufrufer zurückgeben, muss der Parameter
varsein, und zwar genau dann, wenn er es im Publisher auch ist. - Die beiden letzten Parameter lässt du auf
false. Dann bricht der Vorgang mit einem Fehler ab, wenn dem Benutzer Rechte auf deine Codeunit fehlen, statt dass deine Prüfung stillschweigend ausfällt.
Events finden
| Weg | So geht es |
|---|---|
| Quelltext lesen | Mit F12 in die Standardcodeunit springen und die Stelle suchen, an der du früher Code eingefügt hättest. Davor und danach stehen meist OnBefore…- und OnAfter…-Aufrufe. |
| Befehl in VS Code | AL: Find Event (Umschalt+Alt+E) zeigt eine durchsuchbare Liste aller Events und fügt den fertigen Subscriber mit allen Parametern ein. |
| Schnipsel | teventsub erzeugt das Gerüst. IntelliSense schlägt danach Objekt, Event und Parameter vor. |
| Ereignisaufzeichnung | Im Web-Client die Seite „Ereignisaufzeichnung“ (Event Recorder) öffnen, Aufzeichnung starten, den Vorgang durchführen, stoppen. Du siehst alle ausgelösten Events in ihrer Reihenfolge. |
Datenbank-Trigger-Events
[EventSubscriber(ObjectType::Table, Database::"Sales Header", 'OnAfterInsertEvent', '', false, false)]
local procedure SalesHeaderOnAfterInsert(var Rec: Record "Sales Header"; RunTrigger: Boolean)
begin
if Rec.IsTemporary() then
exit;
if not RunTrigger then
exit;
// ...
end;
[EventSubscriber(ObjectType::Table, Database::Customer, 'OnAfterValidateEvent', 'Salesperson Code', false, false)]
local procedure CustomerOnAfterValidateSalesperson(var Rec: Record Customer; var xRec: Record Customer; CurrFieldNo: Integer)
begin
// ...
end;
| Event | Parameter |
|---|---|
OnBeforeInsertEvent, OnAfterInsertEvent | var Rec; RunTrigger: Boolean |
OnBeforeModifyEvent, OnAfterModifyEvent | var Rec; var xRec; RunTrigger: Boolean |
OnBeforeDeleteEvent, OnAfterDeleteEvent | var Rec; RunTrigger: Boolean |
OnBeforeRenameEvent, OnAfterRenameEvent | var Rec; var xRec; RunTrigger: Boolean |
OnBeforeValidateEvent, OnAfterValidateEvent | var Rec; var xRec; CurrFieldNo: Integer, Feldname als Element |
- Sie laufen auch für temporäre Datensätze. Prüfe fast immer zuerst
Rec.IsTemporary(). - Sie laufen auch bei
Insert(false)undModify(false). Der ParameterRunTriggersagt dir, ob die Tabellentrigger ausgeführt werden. Die Trigger in einer Table Extension laufen dagegen nur beitrue. xRecinOnAfterModifyEvententhält nicht zuverlässig den Stand aus der Datenbank, sondern das, was der Aufrufer in seiner Variablen hatte. Bei Änderungen per Code ist es oft identisch mitRec.
OnAfterModifyEvent einer viel beschriebenen Tabelle (Verkaufszeile, Artikelposten) läuft tausendfach. Nimm lieber ein fachlich engeres Integration Event.
Seiten-Events
[EventSubscriber(ObjectType::Page, Page::"Customer Card", 'OnAfterGetCurrRecordEvent', '', false, false)]
local procedure CustomerCardOnAfterGetCurrRecord(var Rec: Record Customer)
begin
// ...
end;
[EventSubscriber(ObjectType::Page, Page::"Sales Order", 'OnAfterActionEvent', 'Release', false, false)]
local procedure SalesOrderOnAfterRelease(var Rec: Record "Sales Header")
begin
// ...
end;
Für Seiten ist die Page Extension mit eigenen Triggern (Seite 4) meist der übersichtlichere Weg. Seiten-Events brauchst du vor allem dann, wenn du die Seite nicht erweitern kannst oder dieselbe Logik an viele Seiten hängen willst.
Was ein Subscriber nicht kann
- Keine garantierte Reihenfolge. Abonnieren mehrere Apps dasselbe Event, ist offen, wer zuerst läuft.
- Kein Rückgabewert. Daten gehen nur über
var-Parameter zurück. - Kein Zugriff auf lokale Variablen der veröffentlichenden Funktion, nur auf das, was als Parameter übergeben wird.
- Gleiche Transaktion. Ein Fehler im Subscriber bricht den gesamten Vorgang ab und rollt alles zurück. Das ist bei Prüfungen gewollt. Ein
Commitim Subscriber ist dagegen fast immer ein Fehler, weil du damit die Transaktion des Standards zerschneidest.
7Das IsHandled-Muster
Viele OnBefore…-Events haben einen Parameter var IsHandled: Boolean. Setzt ein Subscriber ihn auf true, überspringt der Standard den folgenden Codeblock. Damit ersetzt du Standardlogik, ohne sie zu ändern.
// Im Standard (vereinfacht)
procedure CheckCreditLimit(var SalesHeader: Record "Sales Header")
var
IsHandled: Boolean;
begin
IsHandled := false;
OnBeforeCheckCreditLimit(SalesHeader, IsHandled);
if IsHandled then
exit;
// ... Standardprüfung ...
end;
// In deiner App: Standardprüfung für A-Kunden überspringen
[EventSubscriber(ObjectType::Codeunit, Codeunit::"…", 'OnBeforeCheckCreditLimit', '', false, false)]
local procedure SkipCreditLimitForClassA(var SalesHeader: Record "Sales Header"; var IsHandled: Boolean)
var
Customer: Record Customer;
begin
if IsHandled then
exit;
if not Customer.Get(SalesHeader."Sell-to Customer No.") then
exit;
if Customer."ABC Kundenklasse" = Customer."ABC Kundenklasse"::A then
IsHandled := true;
end;
IsHandled setzt, übernimmt die Verantwortung für alles, was der übersprungene Block getan hätte, auch für das, was Microsoft dort in Zukunft ergänzt. Setzen zwei Apps IsHandled am selben Event, gewinnt eine davon, und die andere läuft ins Leere. Regeln: zuerst prüfen, ob schon jemand gehandelt hat, den Wert nie auf false zurücksetzen und das Muster nur einsetzen, wenn ein OnAfter…-Event nicht reicht.
8Eigene Events veröffentlichen
Sobald andere Apps auf deiner aufbauen, oder du selbst deine Logik an einer Stelle erweiterbar halten willst, veröffentlichst du eigene Events.
codeunit 50100 "ABC Visit Mgt."
{
procedure CreateVisit(CustomerNo: Code[20]; VisitDate: Date; VisitType: Enum "ABC Visit Type"; Description: Text[100]): Integer
var
Visit: Record "ABC Customer Visit";
begin
Visit.Init();
Visit.Validate("Customer No.", CustomerNo);
Visit.Validate("Visit Date", VisitDate);
Visit.Validate("Visit Type", VisitType);
Visit.Description := Description;
OnBeforeInsertVisit(Visit);
Visit.Insert(true);
OnAfterCreateVisit(Visit);
exit(Visit."Entry No.");
end;
[IntegrationEvent(false, false)]
local procedure OnBeforeInsertVisit(var Visit: Record "ABC Customer Visit")
begin
end;
[IntegrationEvent(false, false)]
local procedure OnAfterCreateVisit(Visit: Record "ABC Customer Visit")
begin
end;
}
| Punkt | Erklärung |
|---|---|
[IntegrationEvent(IncludeSender, GlobalVarAccess)] | Erster Parameter true: Subscriber bekommen die veröffentlichende Codeunit als sender. Zweiter Parameter: Zugriff auf globale Variablen, wird nicht mehr empfohlen. Fast immer (false, false). |
| Leerer Rumpf | Ein Publisher enthält nie Code. |
local | Der Publisher darf lokal sein. Abonnieren können ihn andere trotzdem, nur aufrufen nicht. |
var oder nicht | var, wenn Subscriber den Wert ändern dürfen. Ohne var bekommen sie eine Kopie. |
| Benennung | OnBefore… und OnAfter… plus das, was passiert. Der Analyzer prüft das. |
[InternalEvent(false)] | Event, das nur deine eigene App abonnieren kann. |
[BusinessEvent(false)] | Event mit Stabilitätsversprechen. Für PTEs kaum relevant. |
9Subscriber gezielt ein- und ausschalten
Normale Subscriber sind immer aktiv. Manchmal soll einer nur während eines bestimmten Vorgangs laufen, etwa um eine Prüfung während eines Imports auszusetzen. Dafür gibt es die manuelle Bindung.
codeunit 50106 "ABC Skip Class Check"
{
EventSubscriberInstance = Manual;
[EventSubscriber(ObjectType::Codeunit, Codeunit::"ABC Sales Post Checks", 'OnBeforeCheckCustomerClass', '', false, false)]
local procedure SkipCheck(var IsHandled: Boolean)
begin
IsHandled := true;
end;
}
// Aufrufer, z. B. ein Import
procedure PostImportedInvoices()
var
SkipClassCheck: Codeunit "ABC Skip Class Check";
begin
BindSubscription(SkipClassCheck);
// ... hier gebuchte Belege durchlaufen die Prüfung nicht ...
UnbindSubscription(SkipClassCheck);
end;
- Die Bindung gilt nur für die Instanz in dieser Variablen und nur in dieser Sitzung.
- Verlässt die Variable ihren Gültigkeitsbereich, endet die Bindung automatisch.
UnbindSubscriptionist trotzdem guter Stil. - Die Instanz kann eigene Variablen tragen. So übergibst du einem Subscriber Zustand, ohne
SingleInstance-Codeunits zu missbrauchen. - Dieses Muster ersetzt die globalen Schaltervariablen („HideValidationDialog“, „SkipCheck“), die du früher in Standardcodeunits eingebaut hast.
10Ersatz für Codeunit 1
Die Funktionen der alten Codeunit 1 „ApplicationManagement“ sind auf mehrere Systemcodeunits verteilt und als Events abonnierbar.
| Früher in Codeunit 1 | Heute (Codeunit und Event) |
|---|---|
CompanyOpen, LogInStart | „System Initialization“: OnAfterLogin. Daneben „LogInManagement“ und „Company Triggers“. |
CompanyClose | „Company Triggers“: OnCompanyClose |
OnDatabaseInsert, OnDatabaseModify, OnDatabaseDelete, GetDatabaseTableTriggerSetup | „GlobalTriggerManagement“ mit gleichnamigen OnAfter…-Events |
CaptionClassTranslate | „Caption Class“: OnResolveCaptionClass |
AutoFormatTranslate | „Auto Format“: OnResolveAutoFormat |
FindPrinter, HasCustomLayout, Berichtsauswahl | „ReportManagement“: z. B. OnAfterSubstituteReport, mit dem du einen Standardbericht durch deinen eigenen ersetzt |
MakeDateText, MakeTimeText, MakeText | Filter- und Eingabehilfen in Codeunits der System Application |
DefaultRoleCenter | Profile und „Conf./Personalization Mgt.“ |
Die genauen Namen haben sich über die Versionen mehrfach verschoben. Suche mit AL: Find Event nach dem Stichwort, statt dich auf diese Tabelle zu verlassen.
11Interfaces
Ein Interface beschreibt, welche Funktionen eine Codeunit anbieten muss, ohne sie zu implementieren. Zusammen mit Enums ersetzt es die langen CASE-Blöcke, in denen du früher je Optionswert unterschiedlichen Code aufgerufen hast.
CASE "Visit Type" OF
"Visit Type"::"On Site":
Duration := 60;
"Visit Type"::Phone:
Duration := 15;
"Visit Type"::"Trade Show":
Duration := 0;
END;
Ein neuer Wert bedeutet: jeden CASE im ganzen Code finden und ändern.
var
VisitTypeHandler: Interface "ABC IVisit Type";
begin
VisitTypeHandler := Rec."Visit Type";
Duration := VisitTypeHandler.GetDefaultDuration();
end;
Ein neuer Wert bringt seine Implementierung mit. Der aufrufende Code bleibt unverändert.
Schritt 1: Interface definieren
interface "ABC IVisit Type"
{
/// <summary>Returns the default duration in minutes.</summary>
procedure GetDefaultDuration(): Integer;
/// <summary>Checks a visit before it is inserted.</summary>
procedure CheckVisit(Visit: Record "ABC Customer Visit");
}
Interfaces haben keine Objekt-ID und verbrauchen keinen Platz in deinem Nummernbereich.
Schritt 2: Implementierungen schreiben
codeunit 50102 "ABC Visit On Site" implements "ABC IVisit Type"
{
procedure GetDefaultDuration(): Integer
begin
exit(60);
end;
procedure CheckVisit(Visit: Record "ABC Customer Visit")
begin
Visit.TestField("Salesperson Code");
end;
}
Schritt 3: Enum mit dem Interface verbinden
enum 50101 "ABC Visit Type" implements "ABC IVisit Type"
{
Extensible = true;
Caption = 'Visit Type';
DefaultImplementation = "ABC IVisit Type" = "ABC Visit Default";
value(0; "On Site")
{
Caption = 'On Site';
Implementation = "ABC IVisit Type" = "ABC Visit On Site";
}
value(1; Phone)
{
Caption = 'Phone';
Implementation = "ABC IVisit Type" = "ABC Visit Phone";
}
value(2; "Trade Show")
{
Caption = 'Trade Show';
}
}
Implementationlegt je Wert die Codeunit fest.DefaultImplementationgilt für alle Werte ohne eigene Angabe, hier für „Trade Show“ und für Werte aus Erweiterungen, die keine Implementierung mitbringen.- Eine
enumextensiongibt bei ihrem neuen Wert ebenfallsImplementation = …an und liefert die Codeunit dazu. So erweitert eine fremde App dein Verhalten, ohne dass du ein Event vorsehen musst.
Interfaces ohne Enum
var
Handler: Interface "ABC IVisit Type";
OnSite: Codeunit "ABC Visit On Site";
begin
Handler := OnSite;
Handler.CheckVisit(Visit);
end;
Das ist nützlich für Tests: Du übergibst einer Funktion statt der echten Implementierung eine Attrappe.
Wo der Standard das nutzt
Microsoft hat viele frühere Optionen auf Enums mit Interfaces umgestellt, zum Beispiel Preisberechnungsmethoden, Belegversandarten und E-Mail-Konnektoren. Wenn du mit F12 auf ein Enum mit implements stößt, weißt du jetzt, dass du dort mit einer enumextension eigenes Verhalten einhängen kannst.
12Fehlerbehandlung
Was gleich geblieben ist
Error(CustomerBlockedErr, Customer."No.");
Customer.TestField("ABC Kundenklasse");
Customer.FieldError("ABC Kundenklasse", MustNotBeCErr);
Message(VisitCreatedMsg, Visit."Entry No.");
if not Confirm(DeleteQst, false) then
exit;
ErrorInfo: Fehler mit Zusatzinformationen und Aktionen
Der Typ ErrorInfo erweitert die einfache Fehlermeldung um einen Titel, technische Details und Schaltflächen, mit denen der Benutzer das Problem direkt behebt oder zur richtigen Stelle springt.
local procedure ThrowCustomerClassMissing(Customer: Record Customer)
var
ClassMissingErr: ErrorInfo;
ClassMissingTitleLbl: Label 'Customer class is missing';
ClassMissingMsg: Label 'Customer %1 has no customer class. Documents can only be posted for classified customers.', Comment = '%1 = Customer No.';
OpenCustomerLbl: Label 'Open customer card';
begin
ClassMissingErr.Title := ClassMissingTitleLbl;
ClassMissingErr.Message := StrSubstNo(ClassMissingMsg, Customer."No.");
ClassMissingErr.DetailedMessage := 'ABC Sales Post Checks: field "ABC Kundenklasse" is blank.';
ClassMissingErr.RecordId := Customer.RecordId();
ClassMissingErr.PageNo := Page::"Customer Card";
ClassMissingErr.AddNavigationAction(OpenCustomerLbl);
Error(ClassMissingErr);
end;
| Bestandteil | Wirkung |
|---|---|
Title, Message | Überschrift und Text für den Benutzer. |
DetailedMessage | Technischer Zusatz, der beim Kopieren der Fehlerdetails und in der Telemetrie erscheint. |
RecordId, PageNo, AddNavigationAction | Schaltfläche, die die angegebene Seite mit dem Datensatz öffnet. |
AddAction(Caption, CodeunitId, 'Methodenname') | Schaltfläche, die eine Funktion in einer Codeunit aufruft. Die Funktion bekommt das ErrorInfo als Parameter und kann den Fehler beheben. |
CustomDimensions | Schlüssel-Wert-Paare, die an die Aktion und die Telemetrie weitergegeben werden. |
Collectible | Fehler wird gesammelt statt sofort ausgelöst (siehe unten). |
Fehler sammeln
Mit dem Attribut [ErrorBehavior(ErrorBehavior::Collect)] an einer Funktion werden Fehler, deren ErrorInfo als Collectible markiert ist, nicht sofort ausgelöst. Am Ende fragst du mit HasCollectedErrors() und GetCollectedErrors() ab, was alles schiefging, und zeigst dem Benutzer die ganze Liste auf einmal. Der Standard nutzt das zum Beispiel bei der Prüfung von Buch.-Blättern.
Fehler abfangen
Codeunit.Run (wie früher, der robuste Weg)
Commit();
if not Codeunit.Run(Codeunit::"Sales-Post", SalesHeader) then begin
LogError(SalesHeader."No.", GetLastErrorText());
ClearLastError();
end;
Alle Datenbankänderungen der fehlgeschlagenen Codeunit werden zurückgerollt. Vor dem Aufruf darf keine Schreibtransaktion offen sein.
TryFunction
[TryFunction]
local procedure TryParseDate(Input: Text; var Result: Date)
begin
Evaluate(Result, Input);
end;
if not TryParseDate(Input, VisitDate) then
Error(InvalidDateErr, Input);
Gut für Umwandlungen und Aufrufe externer Dienste.
Codeunit.Run.
Nützlich für die Fehlersuche: GetLastErrorText(), GetLastErrorCode() und GetLastErrorCallStack().
13Transaktionen und Commit
- Das Transaktionsmodell ist unverändert: Die erste Schreiboperation öffnet eine Transaktion, das Ende des äußersten Aufrufs oder ein
Commitschließt sie, ein Fehler rollt sie zurück. - Kein
Commitin Subscribern. Du weißt nicht, in welchem Zustand der Standard gerade ist. Ein Commit an der falschen Stelle hinterlässt halb gebuchte Belege. - Mit dem Attribut
[CommitBehavior(CommitBehavior::Ignore)]an einer Funktion werden alle Commits ignoriert, die innerhalb ihres Aufrufs geschehen. Damit schützt du deine eigene Transaktion vor Commits in aufgerufenem Fremdcode. LockTablegibt es weiter. Feiner steuerst du das Sperrverhalten beim Lesen mitRec.ReadIsolation(Seite 9).
14Hintergrundverarbeitung ohne NAS
| Mittel | Wofür | Hinweis |
|---|---|---|
| Aufgabenwarteschlange (Job Queue) | Wiederkehrende und zeitgesteuerte Aufgaben | Wie in NAV 2017, läuft aber ohne NAS direkt auf dem Server. Deine Codeunit braucht TableNo = "Job Queue Entry". |
TaskScheduler.CreateTask | Einmalige Aufgabe zu einem späteren Zeitpunkt | Übersteht Server-Neustarts. Die Aufgabenwarteschlange baut darauf auf. |
StartSession | Sofortige Verarbeitung in einer eigenen Sitzung | Keine Garantie bei Server-Neustart, begrenzte Anzahl gleichzeitiger Sitzungen. |
| Page Background Task | Langsame Berechnung für die Anzeige auf einer Seite | Nur lesend. Die Seite bleibt bedienbar, das Ergebnis kommt nach (Seite 4, OnPageBackgroundTaskCompleted). |
codeunit 50110 "ABC Visit Reminder Job"
{
TableNo = "Job Queue Entry";
trigger OnRun()
var
Days: Integer;
begin
if not Evaluate(Days, Rec."Parameter String") then
Days := 180;
SendReminders(Days);
end;
local procedure SendReminders(Days: Integer)
begin
// ...
end;
}
In Hintergrundsitzungen gibt es keine Oberfläche. Confirm und Page.RunModal führen dort zu Fehlern, Message wird nur protokolliert. Mit GuiAllowed() prüfst du, ob ein Benutzer vor dem Bildschirm sitzt.
15Rezepte für häufige Aufgaben
Eigenes Feld vom Verkaufskopf in gebuchte Belege und Posten bringen
- Gebuchte Belege: Lege das Feld mit derselben Feldnummer und demselben Typ per Table Extension auch in „Sales Invoice Header“, „Sales Shipment Header“ usw. an. Die Buchung kopiert mit
TransferFields, dein Feld wandert automatisch mit. - Posten: Der Weg führt über die Buch.-Blattzeile. Du brauchst das Feld in „Gen. Journal Line“ und „Cust. Ledger Entry“ sowie zwei Subscriber:
[EventSubscriber(ObjectType::Table, Database::"Gen. Journal Line", 'OnAfterCopyGenJnlLineFromSalesHeader', '', false, false)]
local procedure CopyFromSalesHeader(SalesHeader: Record "Sales Header"; var GenJournalLine: Record "Gen. Journal Line")
begin
GenJournalLine."ABC Projektcode" := SalesHeader."ABC Projektcode";
end;
[EventSubscriber(ObjectType::Table, Database::"Cust. Ledger Entry", 'OnAfterCopyCustLedgerEntryFromGenJnlLine', '', false, false)]
local procedure CopyFromGenJnlLine(var CustLedgerEntry: Record "Cust. Ledger Entry"; GenJournalLine: Record "Gen. Journal Line")
begin
CustLedgerEntry."ABC Projektcode" := GenJournalLine."ABC Projektcode";
end;
Früher waren das zwei Zeilen in Codeunit 80 und Codeunit 12. Das Muster „Tabelle A kopiert sich aus Tabelle B, danach kommt ein OnAfterCopy…From…-Event“ findest du im ganzen Standard.
Standardbericht durch eigenen ersetzen
[EventSubscriber(ObjectType::Codeunit, Codeunit::ReportManagement, 'OnAfterSubstituteReport', '', false, false)]
local procedure SubstituteReport(ReportId: Integer; var NewReportId: Integer)
begin
if ReportId = Report::"Customer - Top 10 List" then
NewReportId := Report::"ABC Customer Top 10";
end;
Vorbelegung beim Anlegen eines Datensatzes
Für eigene Felder in Standardtabellen nimmst du den Trigger OnAfterInsert der Table Extension oder ein OnAfterInit…-Event der Tabelle, falls vorhanden. Für Werte, die vom Debitor in den Beleg wandern, gibt es Events wie OnAfterCopySellToCustomerAddressFieldsFromCustomer im Verkaufskopf.
16Übung: Logik für die Besuchsverwaltung
Schritt 1. src/ABCIVisitType.Interface.al: das Interface aus Abschnitt 11.
Schritt 2. Vier Implementierungen.
src/ABCVisitOnSite.Codeunit.al: die Codeunit 50102 aus Abschnitt 11.
src/ABCVisitPhone.Codeunit.al
codeunit 50103 "ABC Visit Phone" implements "ABC IVisit Type"
{
procedure GetDefaultDuration(): Integer
begin
exit(15);
end;
procedure CheckVisit(Visit: Record "ABC Customer Visit")
begin
end;
}
src/ABCVisitDefault.Codeunit.al
codeunit 50104 "ABC Visit Default" implements "ABC IVisit Type"
{
procedure GetDefaultDuration(): Integer
begin
exit(0);
end;
procedure CheckVisit(Visit: Record "ABC Customer Visit")
begin
Visit.TestField(Description);
end;
}
Schritt 3. Ersetze src/ABCVisitType.Enum.al durch die Fassung aus Abschnitt 11, Schritt 3.
Schritt 4. Passe in src/ABCCustomerVisit.Table.al das Feld „Visit Type“ und den Trigger OnInsert an:
field(5; "Visit Type"; Enum "ABC Visit Type")
{
Caption = 'Visit Type';
trigger OnValidate()
var
VisitTypeHandler: Interface "ABC IVisit Type";
begin
VisitTypeHandler := "Visit Type";
if "Duration (Minutes)" = 0 then
"Duration (Minutes)" := VisitTypeHandler.GetDefaultDuration();
end;
}
...
trigger OnInsert()
var
VisitTypeHandler: Interface "ABC IVisit Type";
begin
TestField("Customer No.");
if "Visit Date" = 0D then
"Visit Date" := WorkDate();
VisitTypeHandler := "Visit Type";
VisitTypeHandler.CheckVisit(Rec);
UpdateLastVisit();
end;
Schritt 5. src/ABCVisitMgt.Codeunit.al: die Codeunit 50100 aus Abschnitt 8.
Schritt 6. src/ABCSalesPostChecks.Codeunit.al
codeunit 50101 "ABC Sales Post Checks"
{
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post", 'OnBeforePostSalesDoc', '', false, false)]
local procedure CheckCustomerClassOnBeforePostSalesDoc(var SalesHeader: Record "Sales Header")
var
Customer: Record Customer;
IsHandled: Boolean;
begin
if not (SalesHeader."Document Type" in [SalesHeader."Document Type"::Order, SalesHeader."Document Type"::Invoice]) then
exit;
OnBeforeCheckCustomerClass(SalesHeader, IsHandled);
if IsHandled then
exit;
Customer.Get(SalesHeader."Sell-to Customer No.");
if Customer."ABC Kundenklasse" = Customer."ABC Kundenklasse"::" " then
ThrowCustomerClassMissing(Customer);
end;
local procedure ThrowCustomerClassMissing(Customer: Record Customer)
var
ClassMissingErr: ErrorInfo;
ClassMissingTitleLbl: Label 'Customer class is missing';
ClassMissingMsg: Label 'Customer %1 has no customer class. Documents can only be posted for classified customers.', Comment = '%1 = Customer No.';
OpenCustomerLbl: Label 'Open customer card';
begin
ClassMissingErr.Title := ClassMissingTitleLbl;
ClassMissingErr.Message := StrSubstNo(ClassMissingMsg, Customer."No.");
ClassMissingErr.RecordId := Customer.RecordId();
ClassMissingErr.PageNo := Page::"Customer Card";
ClassMissingErr.AddNavigationAction(OpenCustomerLbl);
Error(ClassMissingErr);
end;
[IntegrationEvent(false, false)]
local procedure OnBeforeCheckCustomerClass(SalesHeader: Record "Sales Header"; var IsHandled: Boolean)
begin
end;
}
Schritt 7. Ein Subscriber auf dein eigenes Event: src/ABCVisitSubscribers.Codeunit.al
codeunit 50105 "ABC Visit Subscribers"
{
[EventSubscriber(ObjectType::Codeunit, Codeunit::"ABC Visit Mgt.", 'OnAfterCreateVisit', '', false, false)]
local procedure UpgradeClassOnAfterCreateVisit(Visit: Record "ABC Customer Visit")
var
Customer: Record Customer;
begin
if not Customer.Get(Visit."Customer No.") then
exit;
if Customer."ABC Kundenklasse" <> Customer."ABC Kundenklasse"::C then
exit;
Customer.CalcFields("ABC Anzahl Besuche");
if Customer."ABC Anzahl Besuche" < 5 then
exit;
Customer.Validate("ABC Kundenklasse", Customer."ABC Kundenklasse"::B);
Customer.Modify(true);
end;
}
Schritt 8. Damit CreateVisit auch aufgerufen wird, ergänze in der Page Extension der Debitorenkarte eine Aktion im Bereich addlast(Processing) und den passenden actionref:
action(ABCQuickPhoneVisit)
{
ApplicationArea = All;
Caption = 'Log Phone Call';
Image = Calls;
ToolTip = 'Record a phone call with this customer for today.';
trigger OnAction()
var
VisitMgt: Codeunit "ABC Visit Mgt.";
PhoneCallTxt: Label 'Phone call';
VisitCreatedMsg: Label 'Visit %1 was created.', Comment = '%1 = Entry No.';
EntryNo: Integer;
begin
EntryNo := VisitMgt.CreateVisit(Rec."No.", WorkDate(), Enum::"ABC Visit Type"::Phone, PhoneCallTxt);
Message(VisitCreatedMsg, EntryNo);
CurrPage.Update(false);
end;
}
Schritt 9. Testen.
- Veröffentliche mit F5.
- Lege auf der Besuchskarte einen Besuch an und wähle „Phone“. Die Dauer wird mit 15 vorbelegt. Wähle bei einem neuen Besuch „On Site“ ohne Verkäufercode. Beim Speichern kommt der Fehler aus
CheckVisit. - Klicke auf der Debitorenkarte „Log Phone Call“. Die Meldung nennt die neue Nummer.
- Buche eine Verkaufsrechnung für einen Debitor ohne Kundenklasse. Die Fehlermeldung hat einen Titel und die Schaltfläche „Open customer card“. Setze die Klasse und buche erneut.
- Setze einen Haltepunkt in
CheckCustomerClassOnBeforePostSalesDocund sieh dir in der Aufrufliste an, von wo im Standard dein Subscriber aufgerufen wird. - Öffne die Ereignisaufzeichnung, zeichne das Buchen einer Rechnung auf und suche
OnBeforePostSalesDocin der Liste. - Ergänze die neuen Texte in der deutschen XLIFF-Datei und committe.
[EventSubscriber…] vorübergehend aus.
17Typische Denkfehler
- „Ich abonniere OnAfterModifyEvent, das fängt alles ab.“ Es läuft bei jedem Schreibvorgang, auch temporär und in Massenläufen. Suche das fachlich passende Integration Event.
- „IsHandled ist der einfachste Weg.“ Es ist der Weg mit den meisten Nebenwirkungen. Erst prüfen, ob ein
OnAfter…-Event genügt. - „Mein Subscriber braucht ein Commit, damit die Daten sicher sind.“ Die Daten sind sicher, wenn die Transaktion des Standards endet. Dein Commit macht sie unsicher.
- „Ich benenne den Parameter im Subscriber um, das ist lesbarer.“ Dann wird er nicht mehr zugeordnet, und der Compiler meldet einen Fehler.
- „Alle Funktionen öffentlich, vielleicht braucht sie jemand.“ Jede öffentliche Funktion kannst du später nicht mehr gefahrlos ändern.
- „Die Reihenfolge der Subscriber ist bestimmt die Reihenfolge der Installation.“ Sie ist nicht festgelegt. Baue keine Logik darauf.
- „TryFunction um die Buchung, dann fange ich den Fehler ab.“ Bereits geschriebene Daten bleiben stehen. Nimm
Codeunit.Run. - „Es gibt kein Event, also kopiere ich die Codeunit.“ Erst nach einem Event in der Nähe suchen, dann eines beantragen, und nur als letzten Ausweg kopieren (Seite 1).
18Selbsttest
Was sind die zwei Teile eines Events?
Der Publisher, eine leere Funktion mit Attribut, die im Code aufgerufen wird, und der Subscriber, der sich per Attribut anmeldet und von der Plattform aufgerufen wird.
Wie werden die Parameter eines Subscribers dem Event zugeordnet?
Über Name und Typ. Weglassen ist erlaubt, Umbenennen nicht.
Warum prüfst du in einem Subscriber auf OnAfterInsertEvent zuerst Rec.IsTemporary()?
Weil Datenbank-Trigger-Events auch für temporäre Datensätze ausgelöst werden, bei denen deine Logik fast nie laufen soll.
Was bewirkt IsHandled := true, und welches Risiko trägst du damit?
Der Standard überspringt seinen folgenden Codeblock. Du bist für alles verantwortlich, was dort passiert wäre, auch für künftige Ergänzungen, und kollidierst möglicherweise mit anderen Apps.
Wie schaltest du einen Subscriber nur für die Dauer eines Vorgangs ein?
Codeunit mit EventSubscriberInstance = Manual, dann BindSubscription vor und UnbindSubscription nach dem Vorgang.
Welchen Vorteil hat ein Enum mit Interface gegenüber einem case?
Jeder Wert bringt seine Implementierung mit. Neue Werte, auch aus fremden Apps, funktionieren ohne Änderung am aufrufenden Code.
Wann nimmst du Codeunit.Run statt einer Try-Funktion?
Immer wenn der abgefangene Code in die Datenbank schreibt, weil nur Codeunit.Run die Änderungen bei einem Fehler zurückrollt.
Wie bringst du ein eigenes Feld vom Verkaufskopf in den Debitorenposten?
Feld in Buch.-Blattzeile und Debitorenposten anlegen und zwei Subscriber auf die OnAfterCopy…From…-Events schreiben.
19Zusammenfassung
Der Code selbst ist C/AL in neuer Schreibweise, ohne WITH und mit abgestufter Sichtbarkeit. Eingriffe in den Standard laufen über Event Subscriber, die du mit F12, AL: Find Event oder der Ereignisaufzeichnung findest. Eigene Events und Interfaces machen deine App für andere erweiterbar, manuelle Bindung ersetzt globale Schalter, und ErrorInfo liefert Fehlermeldungen, die dem Benutzer weiterhelfen.
Checkliste: Interface mit drei Implementierungen angelegt · Enum damit verbunden · Codeunit mit zwei eigenen Events · Subscriber auf die Verkaufsbuchung mit ErrorInfo · Subscriber auf das eigene Event · Aktion ruft die Codeunit auf · Subscriber im Debugger angehalten · Ereignisaufzeichnung benutzt · Stand committet.