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
| Thema | NAV 2017 | Business Central heute |
|---|---|---|
| Berechtigungssätze | Daten in den Tabellen 2000000004 „Permission Set“ und 2000000005 „Permission“, gepflegt im Client, verteilt per XMLport oder RapidStart | AL-Objekt permissionset, Teil der App, versioniert in Git. Kunden können zusätzlich eigene Sätze im Client anlegen. |
| Standardsätze erweitern | Standardsatz direkt ändern oder kopieren | permissionsetextension, nur additiv |
| Berechtigungen als Daten NEU | einziger Weg | Seit 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 Modulen | Online: Benutzerlizenz in Microsoft 365 plus entitlement-Objekte. On-Premises: .bclicense (Abschnitt 12). |
| Benutzergruppen | User Groups | Sicherheitsgruppen aus Microsoft Entra ID; die alten Benutzergruppen sind entfernt. |
| Datenupgrade | Upgrade Toolkit, Upgrade-Codeunits mit Funktionstypen, Start-NAVDataUpgrade | Install- und Upgrade-Codeunits in der App, laufen automatisch bei Installation und Versionswechsel |
| Feld löschen, Typ ändern | im Designer mit „Force“ möglich | nach der ersten Auslieferung verboten: ObsoleteState, neues Feld, Upgrade-Code |
| App einspielen NEU | FOB-Import | Upload 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.
| Ebene | Frage | Wo festgelegt |
|---|---|---|
| Lizenz (Entitlement) | Was erlaubt die gekaufte Lizenz höchstens? | Microsoft-Lizenz (Essentials, Premium, Team Member …), bei AppSource-Apps zusätzlich entitlement-Objekte |
| Berechtigung | Was 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“.
3Berechtigungsarten
| Objektart im Satz | Mögliche Rechte | Bedeutung |
|---|---|---|
tabledata | R, I, M, D | Lesen, Einfügen, Ändern, Löschen von Datensätzen |
table | X | Tabellenobjekt ausführen (Tabelle direkt öffnen, Trigger) |
page, report, codeunit, xmlport, query | X | Objekt ausführen |
system | X | Systemfunktionen, 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;
}
| Element | Erklärung |
|---|---|
| Objektname | höchstens 20 Zeichen, weil er der früheren „Role ID“ entspricht. "ABC Visit - Objects" hat 19. |
Caption | höchstens 30 Zeichen, wird übersetzt (XLIFF) |
Assignable | true: erscheint im Client und kann Benutzern zugewiesen werden. false: nur Baustein für andere Sätze. |
IncludedPermissionSets | übernimmt alle Rechte der genannten Sätze |
ExcludedPermissionSets | zieht Rechte der genannten Sätze wieder ab. Ausschluss gewinnt gegen Einschluss. |
Permissions | Liste 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;
}
| Satz | Zuweisbar | Inhalt | Für wen |
|---|---|---|---|
| 50100 Objects | nein | Ausführungsrechte auf alle Objekte der App | nur Baustein |
| 50101 Read | ja | Objects + Lesen der Daten | Controlling, Geschäftsführung |
| 50102 Edit | ja | Read + Besuche pflegen, Debitor indirekt ändern | Vertrieb |
| 50103 Admin | ja | Edit + Einrichtung pflegen | Key User |
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.
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.
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
| Weg | Wann |
|---|---|
| Benutzerkarte | Einzelfälle, Testbenutzer |
| Sicherheitsgruppen (Microsoft Entra ID) | empfohlen: Gruppe einmal mit Sätzen versehen, Mitgliedschaft pflegt die IT in Entra |
| Lizenzkonfiguration | Standardsätze, die neue Benutzer je Lizenztyp automatisch bekommen |
| Eigene Sätze des Kunden | Kunde 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:
| Wert | Verhalten |
|---|---|
Validated | Standard für Variablen im Code: Zugriff auf Datensätze außerhalb des Filters erzeugt einen Fehler. |
Filtered | Datensätze außerhalb des Filters existieren für den Code nicht. Vorsicht bei Summen. |
Ignored | Filter wird übergangen. Nur für Systemlogik. |
Disallowed | Fehler, 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
| Wunsch | Warum es nicht geht | Lösung |
|---|---|---|
| Einzelne Felder verbergen | Rechte gelten je Tabelle | Felder 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 Werte | Prüfung im Code, Genehmigungsworkflows |
| Schutz vor fremdem Code | Jede App läuft mit den Rechten des angemeldeten Benutzers | Access = Internal, local, keine öffentlichen Prozeduren ohne Prüfung |
| Rechte je Mandant in einem Satz | Der Mandant wird bei der Zuweisung gewählt, nicht im Satz | Zuweisung 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.
| Punkt | Stand |
|---|---|
| Dateiformat | Seit Version 22 wird .flf nicht mehr importiert. Das Format heißt .bclicense. |
| Import | weiterhin 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 Rights | Wer 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–99999 | in Sandbox-Containern mit der mitgelieferten Lizenz möglich |
Import-NAVServerLicense -ServerInstance BC -LicenseFile "C:\Lizenz\kunde.bclicense"
Restart-NAVServerInstance -ServerInstance BC
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:
| Situation | Was läuft |
|---|---|
| App wird zum ersten Mal installiert | Install-Codeunit |
| Gleiche Version wird nach Deinstallation wieder installiert | Install-Codeunit (Daten sind noch vorhanden) |
| Höhere Version ersetzt installierte Version | Upgrade-Codeunit, nicht die Install-Codeunit |
| Neuer Mandant wird angelegt | weder 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;
}
| Trigger | Läuft |
|---|---|
OnInstallAppPerCompany | einmal je vorhandenem Mandanten |
OnInstallAppPerDatabase | einmal 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. | Trigger | Zweck |
|---|---|---|
| 1 | OnCheckPreconditionsPerCompany / …PerDatabase | prüfen, ob das Upgrade möglich ist |
| 2 | OnUpgradePerCompany / …PerDatabase | die eigentliche Datenumstellung |
| 3 | OnValidateUpgradePerCompany / …PerDatabase | Ergebnis 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;
}
| Baustein | Aufgabe |
|---|---|
HasUpgradeTag | Schritt schon gelaufen? Dann sofort raus. |
SetUpgradeTag | nach erfolgreichem Schritt den Merker setzen |
OnGetPerCompanyUpgradeTags | meldet alle Tags der App an. Neue Mandanten und Erstinstallationen bekommen sie sofort gesetzt, weil es dort nichts umzustellen gibt. |
SetAllUpgradeTags | setzt 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:
| Änderung | Erlaubt? |
|---|---|
| Tabelle, Feld, Schlüssel hinzufügen | ja |
| Text- oder Code-Feld verlängern | ja |
| Enum-Wert hinzufügen | ja |
| Feld oder Tabelle löschen | nein |
| Feld oder Tabelle umbenennen | nein |
| Datentyp ändern, Feld verkürzen | nein |
| Primärschlüssel ändern | nein |
| Enum-Wert löschen oder Ordinalwert ändern | nein |
Der Weg für „verbotene“ Änderungen
- Neues Feld mit dem gewünschten Typ und Namen anlegen.
- Altes Feld mit
ObsoleteState = Pendingmarkieren. Wer es noch verwendet, bekommt eine Warnung. - Upgrade-Code kopiert die Werte vom alten ins neue Feld, abgesichert durch einen Upgrade Tag.
- In einer späteren Version
ObsoleteState = Removedsetzen. 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;
| Methode | Wirkung |
|---|---|
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
Die Wege im Überblick
| Weg | Einsatz | Stand |
|---|---|---|
VS Code, F5 / Strg+F5 | nur 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 Produktion | empfohlener Weg |
Admin Center API (ab Version 2.29, Endpunkt …/apps/pteInstall) | automatisierte Auslieferung | empfohlener Weg für Pipelines |
| Erweiterungsverwaltung im Client, „Erweiterung hochladen“ | bisheriger manueller Weg | abgekündigt, Entfall mit Version 30 geplant |
Automation API, extensionUpload | bisheriger Weg vieler Pipelines | abgekü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
- Admin Center öffnen:
https://businesscentral.dynamics.com/<Tenant>/admin. - Umgebung wählen, „Manage Apps“ öffnen.
- „Install Extension“ wählen und die
.app-Datei hochladen. Derselbe Befehl dient für neue Apps und für neue Versionen vorhandener Apps. - Zeitplan wählen (Deployment schedule): sofort, im nächsten Update-Fenster der Umgebung oder mit dem nächsten Minor- bzw. Major-Update.
- Bei Updates den Sync-Modus wählen. Für ausgelieferte Apps immer den additiven Modus, nie Force Sync.
- 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
SUPERhat, 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
- 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.
- Kontrollieren, dass in der Kopie die alte Version 1.0.0.0 installiert ist („Manage Apps“).
- Version 1.1.0.0 über „Install Extension“ hochladen, Zeitplan „sofort“, Sync-Modus additiv.
- 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.
- Daten prüfen: Sind die Werte umgestellt? Ist die Einrichtung in jedem Mandanten vorhanden?
- Als Benutzer ohne
SUPERanmelden und die neuen Funktionen durchspielen. - 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.
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:
| Datei | Objekt |
|---|---|
src/ABCInstall.Codeunit.al | codeunit 50112 "ABC Install" |
src/ABCUpgrade.Codeunit.al | codeunit 50113 "ABC Upgrade" |
src/ABCUpgradeTags.Codeunit.al | codeunit 50114 "ABC Upgrade Tags" |
src/ABCVisitSetupMgt.Codeunit.al | codeunit 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
AL: Generate permission set containing current extension objectsausführen.- Ergebnis zu
src/ABCVisitObjects.PermissionSet.alumbauen (nur X-Rechte,Assignable = false). - 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:
| Englisch | Deutsch |
|---|---|
| Visit Setup | Besuchseinrichtung |
| Default Visit Type | Standardbesuchsart |
| Visit Interval | Besuchsintervall |
| Completed | Erledigt |
| ABC Visits - Read / Edit / Admin | ABC Besuche - Lesen / Bearbeiten / Admin |
Schritt 6: Testen und einchecken
- Upgrade nach Abschnitt 20 testen.
- Testbenutzer nur mit „ABC Visit - Edit“ und einem Basissatz anlegen, Besuch erfassen, Debitor prüfen.
- Einchecken:
git add .
git commit -m "Version 1.1: Einrichtung, Feld Completed, Berechtigungssaetze, Upgrade-Code"
git push
22Fallen, Selbsttest, Zusammenfassung
Typische Fallen
| Falle | Folge | Abhilfe |
|---|---|---|
| Nur als SUPER getestet | Berechtigungsfehler beim ersten echten Benutzer | Testbenutzer mit den eigenen Sätzen |
| Indirektes Recht nur im Satz oder nur am Objekt | Fehler im Trigger | beides setzen |
| Einrichtung nur in der Install-Codeunit angelegt | neue Mandanten haben keinen Einrichtungssatz | GetSetup legt bei Bedarf an |
| Upgrade-Schritt ohne Tag | läuft bei jedem Versionswechsel erneut | HasUpgradeTag / SetUpgradeTag |
| Tags bei Erstinstallation nicht gesetzt | Upgrade-Code läuft später über frische Daten | SetAllUpgradeTags und OnGetPerCompanyUpgradeTags |
Message oder Confirm im Install-/Upgrade-Code | Installation bricht ab | keine Oberfläche in diesen Codeunits |
ForceSync nach der Auslieferung | Datenverlust beim Kunden | Synchronize und Obsolete-Weg |
Schreibrechte an D365 READ gehängt | unbemerkte Rechteausweitung | nur Lese- und Ausführungsrechte erweitern |
| Upload teils im Client, teils im Admin Center | widersprüchliche Anzeige geplanter Installationen | je Umgebung ein Weg, künftig Admin Center |
Pipeline nutzt noch extensionUpload | Auslieferung bricht nach Entfernung des Endpunkts | auf Admin Center API umstellen, AL-Go aktualisieren |
| On-Premises-Upgrade mit altem Lizenzschlüssel | Kompatibilitätswarnung, gesperrte Objekte | frischen „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.