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

Berechtigungen, Installation und Upgrade

Berechtigungssätze als AL-Objekte, Entitlements, Install- und Upgrade-Codeunits, Upgrade Tags und Datenumzug zwischen App-Versionen.

Stand November 2026 · Version 29

Autor: Elvis Schmidt, decoso GmbH & Co. KG

Lernziele dieser Seite Du kannst Berechtigungssätze als AL-Objekte schreiben und schichten, kennst den Unterschied zwischen Lizenz (Entitlement) und Berechtigung, schreibst Install- und Upgrade-Codeunits mit Upgrade Tags, weißt, welche Schemaänderungen nach der ersten Auslieferung noch erlaubt sind, und lieferst eine neue App-Version über das Admin Center aus.
Was in dieser Fassung korrigiert wurde NEU
Abschnitt 1 und 12: .bclicense statt .flf, Lizenzschlüssel „28+“. Abschnitt 1 und 7: Berechtigungen als Daten sind abgekündigt. Abschnitt 19 und 20: Upload über das Admin Center statt über die Erweiterungsverwaltung, Upgrade-Test angepasst, PowerShell 7 für Docker und On-Premises. Vorspann: Es werden die Codeunits 50112 bis 50115 vergeben (nicht bis 50114).

Neu vergebene Objekte auf dieser Seite: Berechtigungssätze 50100–50103, Permission Set Extension 50100, Codeunits 50112–50115, Tabelle 50101, Page 50104. Alle liegen im Bereich 50100–50149 der Haupt-App.

1Was sich gegenüber NAV 2017 ändert

ThemaNAV 2017Business Central heute
BerechtigungssätzeDaten in den Tabellen 2000000004 „Permission Set“ und 2000000005 „Permission“, gepflegt im Client, verteilt per XMLport oder RapidStartAL-Objekt permissionset, Teil der App, versioniert in Git. Kunden können zusätzlich eigene Sätze im Client anlegen.
Standardsätze erweiternStandardsatz direkt ändern oder kopierenpermissionsetextension, nur additiv
Berechtigungen als Daten NEUeinziger WegSeit Version 18 sind AL-Objekte der Standard. Das Daten-Modell ist abgekündigt. On-Premises entscheidet die Servereinstellung UsePermissionSetsFromExtensions; neue Projekte verwenden ausschließlich AL-Objekte.
Lizenz.flf-Datei mit Objektbereichen und ModulenOnline: Benutzerlizenz in Microsoft 365 plus entitlement-Objekte. On-Premises: .bclicense (Abschnitt 12).
BenutzergruppenUser GroupsSicherheitsgruppen aus Microsoft Entra ID; die alten Benutzergruppen sind entfernt.
DatenupgradeUpgrade Toolkit, Upgrade-Codeunits mit Funktionstypen, Start-NAVDataUpgradeInstall- und Upgrade-Codeunits in der App, laufen automatisch bei Installation und Versionswechsel
Feld löschen, Typ ändernim Designer mit „Force“ möglichnach der ersten Auslieferung verboten: ObsoleteState, neues Feld, Upgrade-Code
App einspielen NEUFOB-ImportUpload der .app im Admin Center (Abschnitt 19)

2Zwei Ebenen: Lizenz und Berechtigung

Ob ein Benutzer etwas darf, entscheiden zwei unabhängige Prüfungen. Beide müssen zustimmen.

EbeneFrageWo festgelegt
Lizenz (Entitlement)Was erlaubt die gekaufte Lizenz höchstens?Microsoft-Lizenz (Essentials, Premium, Team Member …), bei AppSource-Apps zusätzlich entitlement-Objekte
BerechtigungWas hat der Administrator diesem Benutzer zugeteilt?Berechtigungssätze am Benutzer oder an der Sicherheitsgruppe

Wirksam ist die Schnittmenge. Ein Team-Member-Benutzer mit SUPER darf trotzdem nur, was die Team-Member-Lizenz hergibt. Der Client zeigt das Ergebnis auf der Benutzerkarte über die Aktion „Effektive Berechtigungen“.

Für Per-Tenant-Extensions: Objekte im Bereich 50000–99999 sind ohne eigene Entitlements nutzbar. Du brauchst nur Berechtigungssätze. Entitlements schreibst du erst, wenn du über AppSource verkaufst (Abschnitt 10).

3Berechtigungsarten

Objektart im SatzMögliche RechteBedeutung
tabledataR, I, M, DLesen, Einfügen, Ändern, Löschen von Datensätzen
tableXTabellenobjekt ausführen (Tabelle direkt öffnen, Trigger)
page, report, codeunit, xmlport, queryXObjekt ausführen
systemXSystemfunktionen, zum Beispiel Designer oder Exporte

Großbuchstaben stehen für direkte Rechte, Kleinbuchstaben für indirekte. tabledata Customer = RM erlaubt Lesen und Ändern von überall. tabledata Customer = m erlaubt Ändern nur über ein Objekt, das seinerseits die Eigenschaft Permissions für diese Tabelle trägt (Abschnitt 8). Das Prinzip kennst du aus NAV als „Indirect“.

Rechte auf Feldebene gibt es nicht. Wer einzelne Felder schützen muss, lagert sie in eine eigene Tabelle aus.

4Das permissionset-Objekt

permissionset 50101 "ABC Visit - Read"
{
    Caption = 'ABC Visits - Read';
    Assignable = true;
    IncludedPermissionSets = "ABC Visit - Objects";

    Permissions =
        tabledata "ABC Customer Visit" = R,
        tabledata "ABC Visit Setup" = R;
}
ElementErklärung
Objektnamehöchstens 20 Zeichen, weil er der früheren „Role ID“ entspricht. "ABC Visit - Objects" hat 19.
Captionhöchstens 30 Zeichen, wird übersetzt (XLIFF)
Assignabletrue: erscheint im Client und kann Benutzern zugewiesen werden. false: nur Baustein für andere Sätze.
IncludedPermissionSetsübernimmt alle Rechte der genannten Sätze
ExcludedPermissionSetszieht Rechte der genannten Sätze wieder ab. Ausschluss gewinnt gegen Einschluss.
PermissionsListe der Einzelrechte, durch Komma getrennt, am Ende ein Semikolon

Dateiname nach der Konvention aus Seite 2: src/ABCVisitRead.PermissionSet.al.

5Schichtenmodell: Objects → Read → Edit → Admin

Bewährt hat sich ein Aufbau in vier Sätzen. Jeder schließt den vorherigen ein, Rechte addieren sich.

permissionset 50100 "ABC Visit - Objects"
{
    Caption = 'ABC Visits - Objects';
    Assignable = false;

    Permissions =
        table "ABC Customer Visit" = X,
        table "ABC Visit Setup" = X,
        page "ABC Customer Visits" = X,
        page "ABC Customer Visit Card" = X,
        page "ABC Customer Visit FactBox" = X,
        page "ABC Visits API" = X,
        page "ABC Visit Setup" = X,
        report "ABC Customer Visits" = X,
        report "ABC Update Last Visit" = X,
        query "ABC Visits per Customer" = X,
        xmlport "ABC Visit Export" = X,
        codeunit "ABC Visit Statistics" = X,
        codeunit "ABC Visit Setup Mgt." = X;
}

permissionset 50102 "ABC Visit - Edit"
{
    Caption = 'ABC Visits - Edit';
    Assignable = true;
    IncludedPermissionSets = "ABC Visit - Read";

    Permissions =
        tabledata "ABC Customer Visit" = IMD,
        tabledata Customer = m;
}

permissionset 50103 "ABC Visit - Admin"
{
    Caption = 'ABC Visits - Admin';
    Assignable = true;
    IncludedPermissionSets = "ABC Visit - Edit";

    Permissions =
        tabledata "ABC Visit Setup" = IMD;
}
SatzZuweisbarInhaltFür wen
50100 ObjectsneinAusführungsrechte auf alle Objekte der Appnur Baustein
50101 ReadjaObjects + Lesen der DatenControlling, Geschäftsführung
50102 EditjaRead + Besuche pflegen, Debitor indirekt ändernVertrieb
50103 AdminjaEdit + Einrichtung pflegenKey User
Die Objektliste im Satz „Objects“ tippst du nicht ab. Lass sie mit dem Befehl aus Abschnitt 7 erzeugen und verteile die Datenrechte danach von Hand auf Read, Edit und Admin.

6permissionsetextension

permissionsetextension 50100 "ABC D365 Read Ext" extends "D365 READ"
{
    IncludedPermissionSets = "ABC Visit - Read";
}

Damit sieht jeder Benutzer mit dem Standardsatz D365 READ automatisch auch die Besuche. Eine Extension kann nur Rechte hinzufügen, nie wegnehmen.

Empfehlung: Hänge an Standardsätze höchstens Lese- und Ausführungsrechte. Schreibrechte, die still über einen Microsoft-Satz mitkommen, findet später kein Prüfer. Schreibrechte gehören in eigene, bewusst zugewiesene Sätze.

7Sätze erzeugen und aufzeichnen

In VS Code

Strg+Umschalt+P → AL: Generate permission set containing current extension objects. Der Befehl schreibt einen Satz mit allen Objekten der App. Nimm das Ergebnis als Vorlage für „Objects“.

Code-Analyse

PerTenantExtensionCop und AppSourceCop melden Tabellen, die in keinem Berechtigungssatz der App vorkommen. Die Analyzer schaltest du auf Seite 9 ein.

Im Client aufzeichnen

Auf der Seite „Berechtigungssätze“ einen Satz öffnen, Aufzeichnung starten, den Geschäftsvorgang in einem zweiten Browserfenster durchspielen, Aufzeichnung beenden. Der Client trägt die berührten Tabellen ein. Das ist der schnellste Weg, um herauszufinden, welche Standardtabellen ein Ablauf braucht.

Altbestände aus NAV NEU

Berechtigungssätze, die als Daten in einer alten Datenbank liegen, wandelt das Microsoft-Skript Convert-PermissionSets.psm1 (GitHub, microsoft/BCTech, Ordner samples/PermissionSetConversion) in AL-Dateien um:

Import-Module -Name "C:\Tools\Convert-PermissionSets.psm1"
Convert-PermissionSets -DatabaseServer localhost -DatabaseName "BC_Datenbank" -Destination "C:\Temp\PermissionSets"

Je Satz entsteht eine Datei name.permissionset.al. Die Regel für das Ergebnis: Hast du einem Microsoft-Satz nur Rechte hinzugefügt, wird daraus eine permissionsetextension. Hast du Rechte entfernt oder geändert, wird daraus ein eigener permissionset.

Nie nur als SUPER testen. Lege in der Sandbox einen zweiten Benutzer an, der ausschließlich deine Sätze plus einen Basissatz hat, und spiele jeden Ablauf damit durch. Fast alle Berechtigungsfehler beim Kunden entstehen, weil der Entwickler immer SUPER war.

8Indirekte und inhärente Rechte

Indirekte Rechte

Die Besuchstabelle aktualisiert im OnInsert-Trigger das Feld „ABC Letzter Besuch“ am Debitor. Der Vertrieb soll Debitoren aber nicht frei ändern dürfen. Dafür braucht es zwei Dinge gleichzeitig:

table 50100 "ABC Customer Visit"
{
    Permissions = tabledata Customer = rm;
    // ...
}

und im Berechtigungssatz den Kleinbuchstaben: tabledata Customer = m. Fehlt eines von beiden, scheitert der Trigger mit einem Berechtigungsfehler.

Inhärente Berechtigungen

Für eigene Tabellen, die jeder Benutzer ohnehin braucht (Einrichtung, Puffer, Protokolle), kannst du Rechte direkt am Objekt vergeben. Ein Berechtigungssatz ist dann dafür nicht mehr nötig.

table 50101 "ABC Visit Setup"
{
    InherentPermissions = R;
    InherentEntitlements = R;
    // ...
}

codeunit 50115 "ABC Visit Setup Mgt."
{
    [InherentPermissions(PermissionObjectType::TableData, Database::"ABC Visit Setup", 'i')]
    procedure GetSetup(var VisitSetup: Record "ABC Visit Setup")
    begin
        if VisitSetup.Get() then
            exit;
        VisitSetup.Init();
        VisitSetup.Insert();
    end;
}

Das Attribut an der Prozedur hebt die Rechte nur für die Dauer dieser einen Prozedur an. Es wirkt nur auf Tabellen der eigenen App. Setze es sparsam ein: Jedes inhärente Recht ist ein Recht, das der Administrator nicht mehr entziehen kann.

9Zuweisung und Sicherheitsfilter

WegWann
BenutzerkarteEinzelfälle, Testbenutzer
Sicherheitsgruppen (Microsoft Entra ID)empfohlen: Gruppe einmal mit Sätzen versehen, Mitgliedschaft pflegt die IT in Entra
LizenzkonfigurationStandardsätze, die neue Benutzer je Lizenztyp automatisch bekommen
Eigene Sätze des KundenKunde kopiert oder kombiniert deine Sätze im Client
Seite „Microsoft Entra-Anwendungen“Dienstkonten für API-Zugriffe (Seite 7). Nie SUPER, sondern ein passender Satz.

Sicherheitsfilter

An einer Berechtigungszeile kann der Administrator einen Filter hinterlegen, zum Beispiel nur Debitoren eines Verkäufers. Im Client wirkt der Filter automatisch. Im Code bestimmt die Eigenschaft SecurityFiltering an der Record-Variablen das Verhalten:

WertVerhalten
ValidatedStandard für Variablen im Code: Zugriff auf Datensätze außerhalb des Filters erzeugt einen Fehler.
FilteredDatensätze außerhalb des Filters existieren für den Code nicht. Vorsicht bei Summen.
IgnoredFilter wird übergangen. Nur für Systemlogik.
DisallowedFehler, sobald überhaupt ein Sicherheitsfilter gesetzt ist.
var
    [SecurityFiltering(SecurityFilter::Filtered)]
    Customer: Record Customer;

10Entitlements – nur für AppSource

Wer über AppSource verkauft und die Lizenzierung über Microsoft abwickelt, beschreibt mit entitlement-Objekten, was welcher Plan freischaltet.

entitlement "ABC Visit Premium"
{
    Type = PerUserServicePlan;
    Id = '00000000-0000-0000-0000-000000000000'; // Plan-ID aus dem Partner Center
    ObjectEntitlements = "ABC Visit - Admin";
}

entitlement "ABC Visit Unlicensed"
{
    Type = Unlicensed;
    ObjectEntitlements = "ABC Visit - Read";
}

Entitlements haben keine Objektnummer. ObjectEntitlements verweist auf Berechtigungssätze, die damit eine zweite Rolle bekommen: Sie beschreiben die Obergrenze der Lizenz. Für Per-Tenant-Extensions lässt du dieses Kapitel aus.

11Was Berechtigungen nicht können

WunschWarum es nicht gehtLösung
Einzelne Felder verbergenRechte gelten je TabelleFelder in eigene Tabelle auslagern. Ausblenden auf der Page ist nur Kosmetik: API, Excel-Export und Analysemodus zeigen das Feld trotzdem.
Fachliche Regeln („nur bis 5.000 € freigeben“)Berechtigungen kennen keine WertePrüfung im Code, Genehmigungsworkflows
Schutz vor fremdem CodeJede App läuft mit den Rechten des angemeldeten BenutzersAccess = Internal, local, keine öffentlichen Prozeduren ohne Prüfung
Rechte je Mandant in einem SatzDer Mandant wird bei der Zuweisung gewählt, nicht im SatzZuweisung mit Mandantenangabe an Benutzer oder Gruppe

12Lizenzdatei On-Premises NEU

Online gibt es keine Lizenzdatei. On-Premises und in Docker-Containern gibt es sie weiterhin, aber in anderer Form als in NAV 2017.

PunktStand
DateiformatSeit Version 22 wird .flf nicht mehr importiert. Das Format heißt .bclicense.
Importweiterhin per PowerShell: Import-NAVServerLicense, danach Dienst neu starten
Schlüsselversion „28+“Seit 1. Oktober 2026 gibt es ab Version 28 keine versionsgebundenen Schlüssel mehr. Für jede neue Hauptversion muss ein frischer „28+“-Schlüssel heruntergeladen werden. Das Download-Datum bestimmt, welche Objekte freigeschaltet sind. Ein zu alter Schlüssel führt zu einer Kompatibilitätswarnung.
Dual Use RightsWer On-Premises über ein Online-Abonnement betreibt, muss den Schlüssel seit 5. Juni 2026 alle sechs Monate erneuern. Ein abgelaufener Schlüssel legt die Umgebung still.
Entwicklung im Bereich 50000–99999in Sandbox-Containern mit der mitgelieferten Lizenz möglich
Import-NAVServerLicense -ServerInstance BC -LicenseFile "C:\Lizenz\kunde.bclicense"
Restart-NAVServerInstance -ServerInstance BC
Für On-Premises-Kunden gehört „aktuellen 28+-Schlüssel herunterladen“ als fester Punkt auf jede Upgrade-Checkliste, und zwar erst nach Erscheinen der Zielversion.

13Lebenszyklus und Datenversion

Von Seite 1 kennst du die Schritte Publish, Sync, Install, Upgrade, Uninstall, Unpublish. Für diese Seite ist wichtig, welcher Code wann läuft:

SituationWas läuft
App wird zum ersten Mal installiertInstall-Codeunit
Gleiche Version wird nach Deinstallation wieder installiertInstall-Codeunit (Daten sind noch vorhanden)
Höhere Version ersetzt installierte VersionUpgrade-Codeunit, nicht die Install-Codeunit
Neuer Mandant wird angelegtweder noch. Einrichtung muss beim ersten Zugriff entstehen (siehe GetSetup in Abschnitt 8).

Die Plattform merkt sich zu jeder App zwei Versionen: AppVersion (der Code, der gerade installiert wird) und DataVersion (die Version, mit der die Daten zuletzt geschrieben wurden). Bei einer echten Erstinstallation ist die Datenversion 0.0.0.0.

var
    AppInfo: ModuleInfo;
begin
    NavApp.GetCurrentModuleInfo(AppInfo);
    if AppInfo.DataVersion() = Version.Create(0, 0, 0, 0) then
        // echte Erstinstallation
    else
        // Wiederinstallation, Daten existieren bereits
end;

14Install-Codeunit

codeunit 50112 "ABC Install"
{
    Subtype = Install;
    Access = Internal;

    trigger OnInstallAppPerCompany()
    var
        VisitSetup: Record "ABC Visit Setup";
        VisitSetupMgt: Codeunit "ABC Visit Setup Mgt.";
        UpgradeTag: Codeunit "Upgrade Tag";
        AppInfo: ModuleInfo;
    begin
        VisitSetupMgt.GetSetup(VisitSetup);

        NavApp.GetCurrentModuleInfo(AppInfo);
        if AppInfo.DataVersion() = Version.Create(0, 0, 0, 0) then
            UpgradeTag.SetAllUpgradeTags();
    end;

    trigger OnInstallAppPerDatabase()
    begin
        // mandantenübergreifende Einrichtung, selten nötig
    end;
}
TriggerLäuft
OnInstallAppPerCompanyeinmal je vorhandenem Mandanten
OnInstallAppPerDatabaseeinmal je Umgebung, für Tabellen mit DataPerCompany = false

Regeln für Install-Code: Er muss mehrfach laufen können, ohne Schaden anzurichten. Er zeigt keine Dialoge (Message, Confirm, Seiten), weil kein Benutzer davor sitzt. Ein Fehler bricht die gesamte Installation ab.

SetAllUpgradeTags() bei der Erstinstallation ist der Grund, warum eine frisch installierte Version 1.1 später nicht noch einmal den Upgrade-Code von 1.0 auf 1.1 ausführt (Abschnitt 16).

15Upgrade-Codeunit

codeunit 50113 "ABC Upgrade"
{
    Subtype = Upgrade;
    Access = Internal;

    trigger OnCheckPreconditionsPerCompany()
    begin
        // Abbruch per Error, wenn die Daten nicht upgradefähig sind
    end;

    trigger OnUpgradePerCompany()
    begin
        UpgradeVisitCompleted();
    end;

    trigger OnValidateUpgradePerCompany()
    begin
        // Ergebnis prüfen; Error macht das gesamte Upgrade rückgängig
    end;

    local procedure UpgradeVisitCompleted()
    var
        UpgradeTag: Codeunit "Upgrade Tag";
        UpgradeTags: Codeunit "ABC Upgrade Tags";
    begin
        if UpgradeTag.HasUpgradeTag(UpgradeTags.GetVisitCompletedTag()) then
            exit;

        SetCompletedOnPastVisits();

        UpgradeTag.SetUpgradeTag(UpgradeTags.GetVisitCompletedTag());
    end;

    local procedure SetCompletedOnPastVisits()
    var
        CustomerVisit: Record "ABC Customer Visit";
    begin
        CustomerVisit.SetFilter("Visit Date", '<%1', Today());
        CustomerVisit.ModifyAll(Completed, true);
    end;
}

Reihenfolge der Trigger

Nr.TriggerZweck
1OnCheckPreconditionsPerCompany / …PerDatabaseprüfen, ob das Upgrade möglich ist
2OnUpgradePerCompany / …PerDatabasedie eigentliche Datenumstellung
3OnValidateUpgradePerCompany / …PerDatabaseErgebnis prüfen

Ein Fehler in irgendeinem Trigger rollt das Upgrade zurück, die alte Version bleibt installiert. Gibt es mehrere Upgrade-Codeunits in einer App, ist ihre Reihenfolge nicht garantiert. Eine Codeunit mit klar benannten lokalen Prozeduren je Umstellungsschritt ist deshalb übersichtlicher als viele kleine.

ModifyAll ohne zweiten Parameter ruft weder OnModify noch Validierung auf. Im Upgrade ist das meist gewollt: Die Daten waren schon gültig, sie bekommen nur eine neue Form. Bei großen Tabellen nimmst du DataTransfer (Abschnitt 18).

16Upgrade Tags

Früher verglich man im Upgrade-Code Versionsnummern („wenn alte Version kleiner 1.1, dann …“). Das bricht, sobald Hotfixes, übersprungene Versionen oder Wiederholungen ins Spiel kommen. Ein Upgrade Tag ist ein Merker in der Datenbank: „Dieser Schritt ist in diesem Mandanten erledigt.“

codeunit 50114 "ABC Upgrade Tags"
{
    Access = Internal;

    procedure GetVisitCompletedTag(): Code[250]
    begin
        exit('ABC-0001-VisitCompleted-20261114');
    end;

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Upgrade Tag", 'OnGetPerCompanyUpgradeTags', '', false, false)]
    local procedure RegisterPerCompanyTags(var PerCompanyUpgradeTags: List of [Code[250]])
    begin
        PerCompanyUpgradeTags.Add(GetVisitCompletedTag());
    end;
}
BausteinAufgabe
HasUpgradeTagSchritt schon gelaufen? Dann sofort raus.
SetUpgradeTagnach erfolgreichem Schritt den Merker setzen
OnGetPerCompanyUpgradeTagsmeldet alle Tags der App an. Neue Mandanten und Erstinstallationen bekommen sie sofort gesetzt, weil es dort nichts umzustellen gibt.
SetAllUpgradeTagssetzt alle angemeldeten Tags, Aufruf in der Install-Codeunit

Namensschema für Tags: Präfix, laufende Nummer oder Ticket, sprechender Name, Datum. Ein einmal ausgelieferter Tag wird nie umbenannt, sonst läuft der Schritt beim nächsten Upgrade erneut.

17Schemaänderungen und Obsolete

Sobald eine Version beim Kunden installiert ist, gelten diese Regeln für jede Folgeversion:

ÄnderungErlaubt?
Tabelle, Feld, Schlüssel hinzufügenja
Text- oder Code-Feld verlängernja
Enum-Wert hinzufügenja
Feld oder Tabelle löschennein
Feld oder Tabelle umbenennennein
Datentyp ändern, Feld verkürzennein
Primärschlüssel ändernnein
Enum-Wert löschen oder Ordinalwert ändernnein

Der Weg für „verbotene“ Änderungen

  1. Neues Feld mit dem gewünschten Typ und Namen anlegen.
  2. Altes Feld mit ObsoleteState = Pending markieren. Wer es noch verwendet, bekommt eine Warnung.
  3. Upgrade-Code kopiert die Werte vom alten ins neue Feld, abgesichert durch einen Upgrade Tag.
  4. In einer späteren Version ObsoleteState = Removed setzen. Das Feld bleibt in der Datenbank, ist im Code aber nicht mehr ansprechbar.
field(10; "Visit Note"; Text[50])
{
    Caption = 'Visit Note';
    DataClassification = CustomerContent;
    ObsoleteState = Pending;
    ObsoleteReason = 'Replaced by field "Visit Note Long" (Text[250]).';
    ObsoleteTag = '1.1';
}
field(11; "Visit Note Long"; Text[250])
{
    Caption = 'Visit Note';
    DataClassification = CustomerContent;
}

ObsoleteTag nennt die Version, in der die Markierung gesetzt wurde, nicht die Version der Entfernung. So hält es auch Microsoft (siehe Korrektur auf Seite 10).

schemaUpdateMode: ForceSync und Recreate aus Seite 2 umgehen diese Regeln und löschen dabei Daten. Sie sind Werkzeuge für die Entwicklung vor der ersten Auslieferung. Danach bleibt launch.json auf Synchronize.

18DataTransfer

DataTransfer kopiert Daten als ein einziger SQL-Befehl. Bei Tabellen mit Millionen Zeilen dauert das Sekunden statt Stunden. Der Datentyp ist nur in Install- und Upgrade-Codeunits erlaubt.

local procedure CopyVisitNote()
var
    CustomerVisit: Record "ABC Customer Visit";
    VisitTransfer: DataTransfer;
begin
    VisitTransfer.SetTables(Database::"ABC Customer Visit", Database::"ABC Customer Visit");
    VisitTransfer.AddFieldValue(CustomerVisit.FieldNo("Visit Note"), CustomerVisit.FieldNo("Visit Note Long"));
    VisitTransfer.CopyFields();
end;

local procedure SetCompletedFast()
var
    CustomerVisit: Record "ABC Customer Visit";
    VisitTransfer: DataTransfer;
begin
    VisitTransfer.SetTables(Database::"ABC Customer Visit", Database::"ABC Customer Visit");
    VisitTransfer.AddConstantValue(true, CustomerVisit.FieldNo(Completed));
    VisitTransfer.AddSourceFilter(CustomerVisit.FieldNo("Visit Date"), '<%1', Today());
    VisitTransfer.CopyFields();
end;
MethodeWirkung
SetTables(Quelle, Ziel)legt Quell- und Zieltabelle fest
AddFieldValue(QuellFeld, ZielFeld)Feldwert übernehmen
AddConstantValue(Wert, ZielFeld)festen Wert schreiben
AddSourceFilter(Feld, Filter, Werte)nur passende Zeilen
AddJoin(QuellFeld, ZielFeld)Zuordnung der Zeilen bei verschiedenen Tabellen
CopyFields()bestehende Zeilen im Ziel ändern (SQL UPDATE)
CopyRows()neue Zeilen im Ziel anlegen (SQL INSERT)

Preis der Geschwindigkeit: keine Trigger, keine Events, keine Validierung, keine Änderungsprotokollierung. Für wenige tausend Zeilen ist eine normale Schleife oder ModifyAll die einfachere Wahl.

19Auslieferung über das Admin Center NEU

Korrektur zur früheren Fassung: Dort stand der Upload über die Seite „Erweiterungsverwaltung“ im Client als normaler Weg. Dieser Weg wird abgelöst. Die Installation von PTEs über die Erweiterungsverwaltung soll mit Version 30 (2027 Release Wave 1) entfallen. Die Seite bleibt nach heutigem Plan nur zur Anzeige installierter Erweiterungen.

Die Wege im Überblick

WegEinsatzStand
VS Code, F5 / Strg+F5nur Entwicklung in der Sandbox. Die App gilt als „Dev“-Erweiterung und kann bei Umgebungsupdates entfernt werden.bleibt
Admin Center, Seite „Manage Apps“manuelle Auslieferung in Sandbox und Produktionempfohlener Weg
Admin Center API (ab Version 2.29, Endpunkt …/apps/pteInstall)automatisierte Auslieferungempfohlener Weg für Pipelines
Erweiterungsverwaltung im Client, „Erweiterung hochladen“bisheriger manueller Wegabgekündigt, Entfall mit Version 30 geplant
Automation API, extensionUploadbisheriger Weg vieler Pipelinesabgekündigt, Entfernung für 2027 Release Wave 1 geplant
AL-Go, Workflow „Publish To Environment“Standardweg aus GitHub (Seite 10)AL-Go-Systemdateien aktuell halten, damit der neue Endpunkt genutzt wird

Ablauf im Admin Center

  1. Admin Center öffnen: https://businesscentral.dynamics.com/<Tenant>/admin.
  2. Umgebung wählen, „Manage Apps“ öffnen.
  3. „Install Extension“ wählen und die .app-Datei hochladen. Derselbe Befehl dient für neue Apps und für neue Versionen vorhandener Apps.
  4. Zeitplan wählen (Deployment schedule): sofort, im nächsten Update-Fenster der Umgebung oder mit dem nächsten Minor- bzw. Major-Update.
  5. Bei Updates den Sync-Modus wählen. Für ausgelieferte Apps immer den additiven Modus, nie Force Sync.
  6. Nach erfolgreicher Prüfung und Installation erscheint die neue Version in der App-Liste.

Was sich dadurch praktisch ändert

  • Wer darf ausliefern: Zugriff auf das Admin Center setzt eine Entra-Rolle voraus, mindestens „Dynamics 365 Business Central Administrator“ oder „Dynamics 365 Administrator“. Ein Benutzer, der nur im Client SUPER hat, kann künftig keine PTE mehr einspielen. Kläre das rechtzeitig mit der IT des Kunden.
  • Nicht mischen: In der Übergangszeit funktionieren beide Wege. Eine im Admin Center geplante Installation ist in der Erweiterungsverwaltung erst nach Erfolg sichtbar, und umgekehrt. Verwende je Umgebung nur einen Weg.
  • Deinstallation: Auch das Deinstallieren von PTEs ist im Admin Center möglich.
  • On-Premises und Docker: Hier gibt es kein Admin Center. Dort bleibt es bei PowerShell (Abschnitt 20).

Die Rechte D365 EXTENSION MGT. und EXTEN. MGT. - ADMIN im Client brauchst du weiterhin für das Veröffentlichen aus VS Code und für Dienstkonten von Pipelines.

20Upgrade testen NEU

Ein Upgrade testest du nie in einer leeren Sandbox. Ohne alte Daten läuft der Upgrade-Code ins Leere, und Schemafehler fallen nicht auf.

Online: Sandbox mit Echtdatenstand

  1. Im Admin Center die Produktionsumgebung als Sandbox kopieren. Die Warnung aus Seite 2 gilt: Die Kopie enthält echte Daten, Aufgabenwarteschlangen und Schnittstellen vorher prüfen.
  2. Kontrollieren, dass in der Kopie die alte Version 1.0.0.0 installiert ist („Manage Apps“).
  3. Version 1.1.0.0 über „Install Extension“ hochladen, Zeitplan „sofort“, Sync-Modus additiv.
  4. Ergebnis in der App-Liste prüfen. Schlägt das Upgrade fehl, bleibt 1.0.0.0 installiert und die Fehlermeldung steht im Vorgangsprotokoll der Umgebung.
  5. Daten prüfen: Sind die Werte umgestellt? Ist die Einrichtung in jedem Mandanten vorhanden?
  6. Als Benutzer ohne SUPER anmelden und die neuen Funktionen durchspielen.
  7. Den Upload ein zweites Mal mit einer Version 1.1.0.1 wiederholen. Der Upgrade-Schritt darf dank Tag nicht erneut laufen.

Docker: wiederholbar mit BcContainerHelper

# alte Version einspielen
Publish-BcContainerApp -containerName bcdev `
    -appFile "C:\Repos\abc-kundenapp\release\ABC_ABC Kundenapp_1.0.0.0.app" `
    -skipVerification -sync -install

# Testdaten anlegen (im Client oder per Konfigurationspaket)

# neue Version als Upgrade einspielen
Publish-BcContainerApp -containerName bcdev `
    -appFile "C:\Repos\abc-kundenapp\app\ABC_ABC Kundenapp_1.1.0.0.app" `
    -skipVerification -sync -upgrade

Das entspricht den klassischen Schritten Publish-NAVApp, Sync-NAVApp und Start-NAVAppDataUpgrade, die On-Premises weiterhin gelten.

PowerShell 7: Ab Version 26 laufen die Verwaltungs-Cmdlets des Servers unter PowerShell 7 (pwsh), nicht mehr unter Windows PowerShell 5.1. Alte Skripte mit Import-Module …NavAdminTool.ps1 aus der 5.1-Konsole scheitern dort. BcContainerHelper selbst aktuell halten (Update-Module BcContainerHelper) und aus einer PowerShell-7-Konsole starten.

Aus VS Code

Veröffentlichst du aus VS Code eine höhere Version über eine installierte, läuft der Upgrade-Code. Bei gleicher Versionsnummer läuft er nicht, es sei denn, in launch.json steht "forceUpgrade": true. Das ist für die schnelle Fehlersuche im Upgrade-Code praktisch, ersetzt aber nicht den Test mit der gebauten .app-Datei.

21Übung: Version 1.1 der Besuchsverwaltung

Ausgangslage: Version 1.0.0.0 ist in der Sandbox installiert und enthält Besuche. Du baust Version 1.1.0.0 mit Einrichtung, Feld „Completed“, Berechtigungssätzen und Upgrade-Code.

Schritt 1: Einrichtungstabelle und Seite

src/ABCVisitSetup.Table.al

table 50101 "ABC Visit Setup"
{
    Caption = 'Visit Setup';
    DataClassification = CustomerContent;
    InherentPermissions = R;
    InherentEntitlements = R;

    fields
    {
        field(1; "Primary Key"; Code[10])
        {
            Caption = 'Primary Key';
            AllowInCustomizations = Never;
        }
        field(10; "Default Visit Type"; Enum "ABC Visit Type")
        {
            Caption = 'Default Visit Type';
            ToolTip = 'Specifies the visit type that is suggested for new visits.';
        }
        field(20; "Visit Interval"; DateFormula)
        {
            Caption = 'Visit Interval';
            ToolTip = 'Specifies after which period a customer should be visited again.';
        }
    }

    keys
    {
        key(PK; "Primary Key")
        {
            Clustered = true;
        }
    }
}

src/ABCVisitSetup.Page.al

page 50104 "ABC Visit Setup"
{
    Caption = 'Visit Setup';
    PageType = Card;
    SourceTable = "ABC Visit Setup";
    ApplicationArea = All;
    UsageCategory = Administration;
    InsertAllowed = false;
    DeleteAllowed = false;

    layout
    {
        area(Content)
        {
            group(General)
            {
                Caption = 'General';
                field("Default Visit Type"; Rec."Default Visit Type") { }
                field("Visit Interval"; Rec."Visit Interval") { }
            }
        }
    }

    trigger OnOpenPage()
    var
        VisitSetupMgt: Codeunit "ABC Visit Setup Mgt.";
    begin
        VisitSetupMgt.GetSetup(Rec);
    end;
}

Schritt 2: Neues Feld in der Besuchstabelle

In src/ABCCustomerVisit.Table.al ergänzen. Die Feldnummer 20 ist angenommen; nimm die nächste freie in deiner Tabelle.

field(20; Completed; Boolean)
{
    Caption = 'Completed';
    DataClassification = CustomerContent;
    ToolTip = 'Specifies whether the visit has taken place.';
}

Zusätzlich oben in der Tabelle: Permissions = tabledata Customer = rm; und das Feld auf Liste und Karte einfügen.

Schritt 3: Codeunits

Lege die vier Codeunits aus den Abschnitten 8, 14, 15 und 16 an:

DateiObjekt
src/ABCInstall.Codeunit.alcodeunit 50112 "ABC Install"
src/ABCUpgrade.Codeunit.alcodeunit 50113 "ABC Upgrade"
src/ABCUpgradeTags.Codeunit.alcodeunit 50114 "ABC Upgrade Tags"
src/ABCVisitSetupMgt.Codeunit.alcodeunit 50115 "ABC Visit Setup Mgt."

Ergänze in OnUpgradePerCompany der Upgrade-Codeunit vor UpgradeVisitCompleted() den Aufruf von GetSetup, damit auch Bestandsmandanten einen Einrichtungssatz bekommen.

Schritt 4: Berechtigungssätze

  1. AL: Generate permission set containing current extension objects ausführen.
  2. Ergebnis zu src/ABCVisitObjects.PermissionSet.al umbauen (nur X-Rechte, Assignable = false).
  3. Read, Edit, Admin und die Permission Set Extension aus den Abschnitten 4 bis 6 anlegen.

Schritt 5: Version erhöhen und bauen

In app.json: "version": "1.1.0.0". Dann Strg+Umschalt+B. Die deutschen Texte in der .de-DE.xlf nachziehen:

EnglischDeutsch
Visit SetupBesuchseinrichtung
Default Visit TypeStandardbesuchsart
Visit IntervalBesuchsintervall
CompletedErledigt
ABC Visits - Read / Edit / AdminABC Besuche - Lesen / Bearbeiten / Admin

Schritt 6: Testen und einchecken

  1. Upgrade nach Abschnitt 20 testen.
  2. Testbenutzer nur mit „ABC Visit - Edit“ und einem Basissatz anlegen, Besuch erfassen, Debitor prüfen.
  3. Einchecken:
git add .
git commit -m "Version 1.1: Einrichtung, Feld Completed, Berechtigungssaetze, Upgrade-Code"
git push

22Fallen, Selbsttest, Zusammenfassung

Typische Fallen

FalleFolgeAbhilfe
Nur als SUPER getestetBerechtigungsfehler beim ersten echten BenutzerTestbenutzer mit den eigenen Sätzen
Indirektes Recht nur im Satz oder nur am ObjektFehler im Triggerbeides setzen
Einrichtung nur in der Install-Codeunit angelegtneue Mandanten haben keinen EinrichtungssatzGetSetup legt bei Bedarf an
Upgrade-Schritt ohne Tagläuft bei jedem Versionswechsel erneutHasUpgradeTag / SetUpgradeTag
Tags bei Erstinstallation nicht gesetztUpgrade-Code läuft später über frische DatenSetAllUpgradeTags und OnGetPerCompanyUpgradeTags
Message oder Confirm im Install-/Upgrade-CodeInstallation bricht abkeine Oberfläche in diesen Codeunits
ForceSync nach der AuslieferungDatenverlust beim KundenSynchronize und Obsolete-Weg
Schreibrechte an D365 READ gehängtunbemerkte Rechteausweitungnur Lese- und Ausführungsrechte erweitern
Upload teils im Client, teils im Admin Centerwidersprüchliche Anzeige geplanter Installationenje Umgebung ein Weg, künftig Admin Center
Pipeline nutzt noch extensionUploadAuslieferung bricht nach Entfernung des Endpunktsauf Admin Center API umstellen, AL-Go aktualisieren
On-Premises-Upgrade mit altem LizenzschlüsselKompatibilitätswarnung, gesperrte Objektefrischen „28+“-Schlüssel laden

Selbsttest

1. Ein Benutzer hat SUPER, aber eine Team-Member-Lizenz. Darf er Verkaufsaufträge buchen?

Nein. Wirksam ist die Schnittmenge aus Lizenz und Berechtigung, und die Lizenz erlaubt es nicht.

2. Was bedeutet tabledata Customer = m?

Indirektes Änderungsrecht: Ändern nur über ein Objekt, das Permissions = tabledata Customer = m trägt.

3. Warum ist „Objects“ nicht zuweisbar?

Der Satz enthält nur Ausführungsrechte und ist ein Baustein. Ohne Datenrechte nützt er einem Benutzer nichts, und er würde die Auswahlliste unnötig füllen.

4. Welche Codeunit läuft, wenn 1.1 über 1.0 installiert wird?

Nur die Upgrade-Codeunit. Die Install-Codeunit läuft bei Erstinstallation und Wiederinstallation derselben Version.

5. Wozu dient OnGetPerCompanyUpgradeTags?

Der Subscriber meldet die Tags der App an, damit neue Mandanten und Erstinstallationen sie sofort als erledigt erhalten.

6. Du willst ein Feld von Text[50] auf Text[250] bringen. Was tust du?

Verlängern ist erlaubt, also einfach die Länge erhöhen. Der Obsolete-Weg wäre nötig bei Verkürzung oder Typwechsel.

7. Wann lohnt DataTransfer, und was kostet es?

Bei sehr großen Tabellen im Upgrade. Es laufen keine Trigger, Events oder Validierungen.

8. Wo lädt man eine PTE künftig hoch, und wer darf das?

Im Admin Center unter „Manage Apps“ → „Install Extension“. Nötig ist eine Entra-Administratorrolle für Business Central oder Dynamics 365.

9. Welche Lizenzdatei importierst du in eine On-Premises-Installation der Version 28?

Eine .bclicense-Datei mit aktuellem „28+“-Schlüssel, per Import-NAVServerLicense.

Zusammenfassung

  • Berechtigungssätze sind AL-Objekte und gehören in die App. Das Daten-Modell ist abgekündigt.
  • Wirksam ist die Schnittmenge aus Lizenz und Berechtigung.
  • Vier Schichten (Objects, Read, Edit, Admin) decken fast jede App ab.
  • Indirekte Rechte brauchen Objekt-Eigenschaft und Kleinbuchstaben im Satz.
  • Install-Code läuft bei Installation, Upgrade-Code bei Versionswechsel. Beide sind wiederholbar und ohne Oberfläche.
  • Upgrade Tags statt Versionsvergleich.
  • Nach der ersten Auslieferung: nur hinzufügen, nie löschen oder umbenennen. Der Rest geht über Obsolete.
  • Ausgeliefert wird über das Admin Center oder dessen API, nicht mehr über die Erweiterungsverwaltung.

Quellen (Stand November 2026)

Upgrade-Code und Datenumzug prüfen lassen?Besser vorher als im Go-Live.

So läuft eine Migration ab

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