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

Code und Events

Events statt Codeänderung: Publisher, Subscriber und Codeunits in AL, gegenübergestellt mit der Arbeitsweise in C/AL.

Stand November 2026 · Version 29

Autor: Elvis Schmidt, decoso GmbH & Co. KG

Lernziele dieser Seite. Du kennst danach die Unterschiede zwischen C/AL und AL im Code, kannst Events des Standards abonnieren, eigene Events veröffentlichen, Subscriber gezielt ein- und ausschalten, Interfaces mit Enums verbinden und Fehler mit 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.FINDSETCustomer.FindSet()PascalCase und Klammern, auch ohne Parameter.
IF … THEN BEGIN … END ELSEif … then begin … end elseSchlü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::CustomerDatabase::Customer
Option-VariableEnum "…"Seite 3.
WITH Cust DOEntfälltAbschnitt 2.
Funktion mit Local=Yeslocal procedureAbschnitt 3.
Rückgabewert über EXIT(Wert)exit(Wert) oder benannter Rückgabewertprocedure Calc() Result: Decimal
Ein Funktionsname, eine FunktionÜberladung erlaubtGleicher Name mit unterschiedlichen Parametern.
FOR i := 1 TO …Zusätzlich foreach … in …Für Listen, Enums, JSON (Seite 6).
Text mit fester LängeText ohne Länge ist unbegrenztDazu Methoden wie .Contains(), .Replace(), .Split() (Seite 6).
DokumentationstriggerKommentare //, /* */ und /// für XML-Dokumentation///-Kommentare erscheinen in IntelliSense.

Ein typisches Stück Code im Vergleich

C/AL
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;
AL
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

SprachmittelBeispiel
Mehrere Variablen in einer ZeileFromDate, ToDate: Date;
Benannter Rückgabewertprocedure GetName() Result: Text
Bedingter OperatorStyle := IsLate ? 'Attention' : 'Standard';
thisthis.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 using machst 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:

FormFrüherHeute
Ausdrückliches WITHWITH SalesHeader DO …Nicht mehr erlaubt. Variable ausschreiben.
Stillschweigendes WITH auf Seiten"No." meinte automatisch Rec."No."Rec."No." schreiben.
Stillschweigendes WITH in Codeunits mit TableNoFelder ohne Rec.Rec. schreiben.
In Tabellen und Table ExtensionsFelder 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üsselwortSichtbar fürWann verwenden
local procedureNur das eigene ObjektStandard für alles, was niemand sonst braucht.
internal procedureAlle Objekte der eigenen AppHilfsfunktionen, die du in der App mehrfach nutzt, die aber kein fremder Code aufrufen soll.
protected procedureDas Objekt und seine ErweiterungenIn Tabellen, Seiten und Berichten, wenn Extensions darauf zugreifen sollen.
procedure (ohne Zusatz)Alle, auch andere AppsDeine öffentliche Schnittstelle. Bewusst klein halten.
protected varGlobale Variablen für Erweiterungen sichtbarSelten.

Dazu kommt die Objekteigenschaft Access = Internal;, die ein ganzes Objekt vor anderen Apps verbirgt.

Warum das wichtig ist. Jede öffentliche Funktion ist ein Versprechen an andere Apps. Änderst du später ihre Parameter, kompilieren abhängige Apps nicht mehr. In NAV 2017 gab es diesen Gedanken nicht, weil alles in einer Datenbank lag. Gewöhne dir 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;
}
EigenschaftBedeutung
SubtypeNormal, Test, TestRunner (Seite 9), Install, Upgrade (Seite 8).
TableNoDie Codeunit bekommt einen Datensatz als Rec übergeben, wie früher. Nötig für Codeunit.Run(…, Rec) und für die Aufgabenwarteschlange.
SingleInstanceEine Instanz pro Sitzung, globale Variablen behalten ihren Wert. Wie früher, nützlich für Zwischenspeicher und Schalter.
EventSubscriberInstanceStaticAutomatic (Standard) oder Manual (Abschnitt 9).
AccessPublic oder Internal.
Permissions, InherentPermissionsRechte, 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

ArtWoherBeispiele
Integration EventsVon Microsoft oder anderen Entwicklern im Code platziertOnBeforePostSalesDoc, OnAfterCopySellToCustomerAddressFieldsFromCustomer
Business EventsWie Integration Events, mit dem Versprechen, dass sich die Signatur nicht ändertIm Standard selten
Internal EventsNur innerhalb derselben App abonnierbarFür dich als Subscriber nicht nutzbar
Datenbank-Trigger-EventsAutomatisch für jede Tabelle vorhandenOnBeforeInsertEvent, OnAfterModifyEvent, OnAfterValidateEvent
Seiten-Trigger-EventsAutomatisch für jede Seite vorhandenOnOpenPageEvent, 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 var sein, 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

WegSo geht es
Quelltext lesenMit 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 CodeAL: Find Event (Umschalt+Alt+E) zeigt eine durchsuchbare Liste aller Events und fügt den fertigen Subscriber mit allen Parametern ein.
Schnipselteventsub erzeugt das Gerüst. IntelliSense schlägt danach Objekt, Event und Parameter vor.
EreignisaufzeichnungIm 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;
EventParameter
OnBeforeInsertEvent, OnAfterInsertEventvar Rec; RunTrigger: Boolean
OnBeforeModifyEvent, OnAfterModifyEventvar Rec; var xRec; RunTrigger: Boolean
OnBeforeDeleteEvent, OnAfterDeleteEventvar Rec; RunTrigger: Boolean
OnBeforeRenameEvent, OnAfterRenameEventvar Rec; var xRec; RunTrigger: Boolean
OnBeforeValidateEvent, OnAfterValidateEventvar Rec; var xRec; CurrFieldNo: Integer, Feldname als Element
Drei Fallen bei Datenbank-Events.
  • Sie laufen auch für temporäre Datensätze. Prüfe fast immer zuerst Rec.IsTemporary().
  • Sie laufen auch bei Insert(false) und Modify(false). Der Parameter RunTrigger sagt dir, ob die Tabellentrigger ausgeführt werden. Die Trigger in einer Table Extension laufen dagegen nur bei true.
  • xRec in OnAfterModifyEvent enthä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 mit Rec.
Ein Subscriber auf 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 Commit im 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;
Mit Vorsicht verwenden. Wer 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;
}
PunktErklä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 RumpfEin Publisher enthält nie Code.
localDer Publisher darf lokal sein. Abonnieren können ihn andere trotzdem, nur aufrufen nicht.
var oder nichtvar, wenn Subscriber den Wert ändern dürfen. Ohne var bekommen sie eine Kopie.
BenennungOnBefore… 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.
Events sind Schnittstellen. Ein veröffentlichtes Event zu entfernen oder Parameter zu ändern, bricht jeden Subscriber. Parameter hinzufügen ist unkritisch, weil Subscriber Parameter weglassen dürfen. Gib lieber von Anfang an den ganzen Datensatz mit als einzelne Felder.

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. UnbindSubscription ist 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 1Heute (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, MakeTextFilter- und Eingabehilfen in Codeunits der System Application
DefaultRoleCenterProfile 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.

Früher: CASE über Option
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.

Heute: Interface am Enum
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';
    }
}
  • Implementation legt je Wert die Codeunit fest.
  • DefaultImplementation gilt für alle Werte ohne eigene Angabe, hier für „Trade Show“ und für Werte aus Erweiterungen, die keine Implementierung mitbringen.
  • Eine enumextension gibt bei ihrem neuen Wert ebenfalls Implementation = … 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.

Auch Interfaces sind Versprechen. Fügst du einem veröffentlichten Interface eine Funktion hinzu, kompiliert keine fremde Implementierung mehr. Halte Interfaces klein und lege für neue Anforderungen lieber ein zweites Interface an.

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;
BestandteilWirkung
Title, MessageÜberschrift und Text für den Benutzer.
DetailedMessageTechnischer Zusatz, der beim Kopieren der Fehlerdetails und in der Telemetrie erscheint.
RecordId, PageNo, AddNavigationActionSchaltflä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.
CustomDimensionsSchlüssel-Wert-Paare, die an die Aktion und die Telemetrie weitergegeben werden.
CollectibleFehler 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.

TryFunction und Datenbank. Eine Try-Funktion rollt Datenbankänderungen bei einem Fehler nicht zurück. Schreibe innerhalb von Try-Funktionen deshalb nicht in die Datenbank. Für alles, was bucht oder speichert, nimmst du das Muster mit 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 Commit schließt sie, ein Fehler rollt sie zurück.
  • Kein Commit in 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.
  • LockTable gibt es weiter. Feiner steuerst du das Sperrverhalten beim Lesen mit Rec.ReadIsolation (Seite 9).

14Hintergrundverarbeitung ohne NAS

MittelWofürHinweis
Aufgabenwarteschlange (Job Queue)Wiederkehrende und zeitgesteuerte AufgabenWie in NAV 2017, läuft aber ohne NAS direkt auf dem Server. Deine Codeunit braucht TableNo = "Job Queue Entry".
TaskScheduler.CreateTaskEinmalige Aufgabe zu einem späteren ZeitpunktÜbersteht Server-Neustarts. Die Aufgabenwarteschlange baut darauf auf.
StartSessionSofortige Verarbeitung in einer eigenen SitzungKeine Garantie bei Server-Neustart, begrenzte Anzahl gleichzeitiger Sitzungen.
Page Background TaskLangsame Berechnung für die Anzeige auf einer SeiteNur 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

  1. 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.
  2. 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.

  1. Veröffentliche mit F5.
  2. 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.
  3. Klicke auf der Debitorenkarte „Log Phone Call“. Die Meldung nennt die neue Nummer.
  4. 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.
  5. Setze einen Haltepunkt in CheckCustomerClassOnBeforePostSalesDoc und sieh dir in der Aufrufliste an, von wo im Standard dein Subscriber aufgerufen wird.
  6. Öffne die Ereignisaufzeichnung, zeichne das Buchen einer Rechnung auf und suche OnBeforePostSalesDoc in der Liste.
  7. Ergänze die neuen Texte in der deutschen XLIFF-Datei und committe.
Hinweis zur Sandbox. Nach dieser Übung lassen sich Verkaufsaufträge und -rechnungen nur noch für Debitoren mit Kundenklasse buchen. Das ist der Zweck der Übung. Wenn es dich bei späteren Tests stört, kommentiere das Attribut [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.

Code-Review für deine erste Extension?Wir schauen drauf, bevor sie zum Kunden geht.

Erstgespräch vereinbaren

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