GuiAllowed in Business Central - UI-Kontext richtig verstehen

Wer in Microsoft Dynamics 365 Business Central Extensions entwickelt, stößt früher oder später auf eine scheinbar einfache, aber extrem entscheidende Funktion: GuiAllowed.

Auf den ersten Blick wirkt sie trivial - ein Boolean, der sagt, ob UI erlaubt ist oder nicht. In der Praxis entscheidet GuiAllowed jedoch darüber, ob Code stabil, testbar und cloudfähig ist - oder ob er früher oder später in Job Queues, APIs oder Tests explodiert.

In diesem Artikel erklären wir:

• was GuiAllowed wirklich bedeutet
• wann es true und wann false ist
• warum Server Flow, APIs und Tests sich unterschiedlich verhalten
• und wie man saubere, zukunftssichere AL-Architektur baut

Was ist GuiAllowed eigentlich?

GuiAllowed ist eine globale Systemfunktion in AL:

GuiAllowed(): Boolean

Sie beantwortet eine einzige Frage:

Existiert aktuell eine Benutzeroberfläche, mit der dieser Code interagieren darf?

❗ Wichtig:

• GuiAllowed prüft nicht, ob ein User existiert
• GuiAllowed prüft nicht, ob jemand eingeloggt ist
• GuiAllowed prüft ausschließlich, ob der aktuelle Code in einem UI-Kontext läuft

Die wichtigste Grundregel

• GuiAllowed = TRUE, wenn Code durch eine UI-Aktion ausgelöst wird
• GuiAllowed = FALSE, wenn Code serverseitig, automatisiert oder headless läuft

Diese Regel erklärt 95 % aller echten Praxisfälle.

Wann ist GuiAllowed = TRUE?

Immer dann, wenn ein Benutzer direkt beteiligt ist:

• Page Actions (Buttons)
• Page Triggers (OnOpenPage, OnValidate, OnAction)
• Reports, die manuell gestartet werden
• Codeunits, die von Pages oder Reports aufgerufen werden
• AL Test Tool, wenn Tests manuell im Client gestartet werden

Beispiel:

action(PostDocument)
{
    trigger OnAction()
    begin
        if GuiAllowed then
            Message('Dokument wurde gebucht.');
    end;
}

In diesem Kontext ist GuiAllowed immer TRUE, da der Benutzer aktiv klickt.

Wann ist GuiAllowed = FALSE?

Immer dann, wenn kein UI existiert:

• Job Queue
• Web Services (OData, SOAP, API Pages)
• Power Automate / Server Flow
• Background Sessions
• Upgrade Codeunits
• Install Codeunits
• Serverseitig gestartete Tests
• Session.StartSession

Typisches Beispiel:

codeunit 50100 MyJobQueue
{
    trigger OnRun()
    begin
        // GuiAllowed = FALSE
    end;
}

Oder:

[ServiceEnabled]
procedure CreateOrder()
begin
    // GuiAllowed = FALSE
end;

Dein konkretes Beispiel: Test Tool vs. Server Flow

Hier zeigt sich GuiAllowed besonders deutlich - und oft überraschend.

🟢 Test über AL Test Tool (Client)

• Benutzer klickt auf „Run"
• UI ist vorhanden
• GuiAllowed = TRUE

🔴 Test über Server Flow / Pipeline

• Läuft vollständig headless
• Kein Client, kein UI
• GuiAllowed = FALSE

💡 Fazit:

Nicht der Test entscheidet - sondern der Ausführungskontext.

Typische Fehler - und warum sie teuer sind

❌ UI direkt in Business-Logik

procedure PostDocument()
begin
    Message('Gebucht!');
end;

• ✔️ Funktioniert auf Pages
• ❌ Crasht in Job Queue, API, Tests

✅ Korrektes Pattern

procedure PostDocument()
begin
    // reine Business-Logik
end;

procedure PostDocumentWithFeedback()
begin
    PostDocument();

    if GuiAllowed then
        Message('Gebucht!');
end;

Best Practice: UI und Logik strikt trennen

Die wichtigste Architektur-Regel in Business Central:

Business-Logik darf niemals UI voraussetzen

Warum?

• Code muss in Pages, Reports, APIs, Job Queues und Tests laufen
• UI ist optional - Logik nicht
• Cloud-Extensions müssen headless funktionieren

Typische sinnvolle Einsätze von GuiAllowed

• Message, Confirm, Dialog
• Progress-Anzeigen
• Unterschiedliches Verhalten für API vs. Page
• Logging statt UI-Feedback
• Tests ohne UI-Abhängigkeit

Beispiel:

if GuiAllowed then
    Confirm('Möchten Sie fortfahren?');

Kurzüberblick 🧠

Fazit

GuiAllowed ist kein Detail - es ist ein Architektur-Werkzeug.

Wer es richtig versteht:

• schreibt stabileren Code
• vermeidet Produktionsfehler
• baut testbare Extensions
• ist Cloud-ready
• und trennt sauber zwischen UI und Logik

Wenn dein Code nur mit GuiAllowed = TRUE funktioniert, ist er nicht fertig.

Saubere Business-Central-Extensions funktionieren immer -
und zeigen UI nur dann, wenn sie wirklich dürfen.