HttpClient aufrufen, Zugangsdaten sicher ablegen und Dateien über Streams hoch- und herunterladen. Die Übung ergänzt die Besuchsverwaltung um einen JSON-Export, einen CSV-Import und einen Webaufruf.
1Warum DotNet und Dateisystem weg sind
In der Cloud teilen sich viele Kunden dieselben Server. Code, der beliebige .NET-Klassen laden oder auf die Festplatte des Servers schreiben dürfte, könnte andere Kunden stören oder ausspähen. Deshalb gilt bei "target": "Cloud":
- keine
DotNet-Variablen, - kein Datentyp
File, keine Pfade auf dem Server, - keine Automation- und OCX-Variablen (die sind ganz abgeschafft),
- kein Code, der auf dem PC des Benutzers läuft, denn der Client ist ein Browser.
Microsoft hat die häufigsten Anwendungsfälle als eigene AL-Datentypen und als Module der System Application nachgebaut.
Übersetzungstabelle
| NAV 2017 (DotNet oder alte Funktion) | Business Central | Abschnitt |
|---|---|---|
System.Text.StringBuilder | TextBuilder | 2 |
System.String-Methoden, STRPOS, COPYSTR, CONVERTSTR | Methoden am Typ Text | 2 |
System.Text.RegularExpressions.Regex | Codeunit Regex | 2 |
System.Collections.Generic.List, ArrayList | List of [T] | 3 |
System.Collections.Generic.Dictionary | Dictionary of [K, V] | 3 |
Newtonsoft.Json (JObject, JArray) | JsonObject, JsonArray, JsonToken, JsonValue | 4 |
System.Xml.XmlDocument, Codeunit 6224 „XML DOM Management“ | XmlDocument, XmlElement, XmlNode … | 5 |
System.Net.HttpWebRequest, System.Net.Http.HttpClient | HttpClient, HttpRequestMessage, HttpResponseMessage | 6 |
| Kennwörter in Tabellenfeldern, Service Password | SecretText, IsolatedStorage | 7 |
FILE, UPLOAD, DOWNLOAD, Codeunit 419 „File Management“ | InStream, OutStream, UploadIntoStream, DownloadFromStream | 8 |
| Tabelle 99008535 „TempBlob“ | Codeunit "Temp Blob" | 8 |
System.Convert (Base64) | Codeunit "Base64 Convert" | 10 |
System.IO.Compression | Codeunit "Data Compression" | 10 |
System.Security.Cryptography | Codeunit "Cryptography Management" | 10 |
| SMTP Mail (Codeunit 400), Outlook-Automation | Modul E-Mail: Codeunits "Email Message" und Email | 9 |
| Netzlaufwerk, FTP-Ordner | Azure Blob Storage, SharePoint, externer Dienst | 9 |
| Excel- und Word-Automation | Tabelle „Excel Buffer“, Excel- und Word-Layouts für Berichte | 11 |
| Client-Add-ins in .NET | Control Add-ins in JavaScript | 12 |
2Text
Unbegrenzter Text und Methoden
Eine Variable vom Typ Text ohne Längenangabe ist unbegrenzt. Die Grenze von 1024 Zeichen aus NAV 2017 gibt es für Variablen nicht mehr. Die alten Funktionen StrPos, CopyStr, StrLen, DelChr, ConvertStr, StrSubstNo funktionieren weiter. Dazu kommen Methoden direkt am Wert:
var
Input: Text;
Parts: List of [Text];
Part: Text;
begin
Input := ' Müller GmbH; Hamburg; DE ';
Input := Input.Trim(); // 'Müller GmbH; Hamburg; DE'
if Input.Contains('GmbH') then ...
if Input.StartsWith('Müller') then ...
if Input.EndsWith('DE') then ...
Message('%1', Input.IndexOf('Hamburg')); // Position, beginnt bei 1
Input := Input.Replace('GmbH', 'AG');
Message(Input.ToUpper());
Message(Input.Substring(1, 6)); // 'Müller'
Message('42'.PadLeft(6, '0')); // '000042'
Parts := Input.Split(';');
foreach Part in Parts do
Message(Part.Trim());
end;
| Methode | Ersetzt früher |
|---|---|
Contains, IndexOf, LastIndexOf, StartsWith, EndsWith | STRPOS und Vergleiche mit COPYSTR |
Substring, Remove | COPYSTR, DELSTR |
Replace | Eigene Schleifen oder DotNet String.Replace |
Split | SELECTSTR oder eigene Schleifen |
Trim, TrimStart, TrimEnd | DELCHR(…,'<>') |
ToLower, ToUpper | LOWERCASE, UPPERCASE |
PadLeft, PadRight | PADSTR und Tricks mit FORMAT |
Die Methoden ändern den Text nicht, sie geben einen neuen zurück. Input.Trim(); allein bewirkt nichts, du musst das Ergebnis zuweisen.
Text einem Feld Text[100] zu, gibt es einen Laufzeitfehler. Kürze bewusst mit CopyStr(Wert, 1, MaxStrLen(Rec.Description)). Der Analyzer warnt an solchen Stellen.
TextBuilder
StringBuilder : DotNet "'mscorlib'.System.Text.StringBuilder";
StringBuilder := StringBuilder.StringBuilder;
StringBuilder.Append('Zeile 1');
StringBuilder.AppendLine;
Result := StringBuilder.ToString;
var
Builder: TextBuilder;
Result: Text;
begin
Builder.Append('Zeile 1');
Builder.AppendLine();
Builder.AppendLine('Zeile 2');
Result := Builder.ToText();
end;
Verwende TextBuilder, sobald du in einer Schleife viele Teile aneinanderhängst. Text += … kopiert bei jedem Schritt den ganzen bisherigen Text und wird bei großen Mengen langsam.
Formatieren und Einlesen für Schnittstellen
Format(Today(), 0, 9); // '2025-03-01' (XML-Format, sprachunabhängig)
Format(1234.5, 0, 9); // '1234.5'
Format(CurrentDateTime(), 0, 9); // '2025-03-01T10:15:00Z'
Evaluate(VisitDate, '2025-03-01', 9);
Evaluate(Amount, '1234.5', 9);
Die Formatnummer 9 kennst du vielleicht schon. Sie ist für jede Schnittstelle Pflicht, weil Format und Evaluate ohne sie von der Sprache und Region des Benutzers abhängen. Ein Import, der mit deutschem Benutzer funktioniert, scheitert sonst beim englischen.
Reguläre Ausdrücke
var
Regex: Codeunit Regex;
begin
if not Regex.IsMatch(PostCode, '^\d{5}$') then
Error(InvalidPostCodeErr);
Cleaned := Regex.Replace(Input, '\s+', ' ');
end;
Die Codeunit Regex gehört zur System Application. Für Treffer und Gruppen gibt es die temporären Tabellen „Matches“ und „Groups“.
3Listen und Dictionaries
var
CustomerNos: List of [Code[20]];
VisitsPerCustomer: Dictionary of [Code[20], Integer];
CustomerNo: Code[20];
VisitCount: Integer;
begin
// Liste
CustomerNos.Add('10000');
CustomerNos.Add('20000');
if not CustomerNos.Contains('30000') then
CustomerNos.Add('30000');
Message('%1 Einträge, erster: %2', CustomerNos.Count(), CustomerNos.Get(1));
foreach CustomerNo in CustomerNos do
Message(CustomerNo);
// Dictionary: Besuche je Debitor zählen
if Visit.FindSet() then
repeat
if VisitsPerCustomer.Get(Visit."Customer No.", VisitCount) then
VisitsPerCustomer.Set(Visit."Customer No.", VisitCount + 1)
else
VisitsPerCustomer.Add(Visit."Customer No.", 1);
until Visit.Next() = 0;
foreach CustomerNo in VisitsPerCustomer.Keys() do
Message('%1: %2', CustomerNo, VisitsPerCustomer.Get(CustomerNo));
end;
| Typ | Wichtige Methoden |
|---|---|
List of [T] | Add, AddRange, Insert, Get, Set, Contains, IndexOf, Remove, RemoveAt, Count, Reverse, GetRange |
Dictionary of [K, V] | Add (Fehler, wenn der Schlüssel existiert), Set (legt an oder überschreibt), Get, ContainsKey, Remove, Keys, Values, Count |
- Indizes beginnen bei 1, anders als in .NET.
- Erlaubte Inhalte: einfache Typen wie Text, Code, Integer, Decimal, Date, Boolean, Guid sowie verschachtelte Listen und Dictionaries (
Dictionary of [Code[20], List of [Text]]). Records und Codeunits gehen nicht. - Referenztypen: Weist du eine Liste einer zweiten Variablen zu, zeigen beide auf dieselbe Liste. Dasselbe gilt für Dictionaries, die JSON- und XML-Typen und die HTTP-Typen. Eine Änderung über die eine Variable ist über die andere sichtbar.
- Liste oder temporäre Tabelle? Listen sind schneller und brauchen kein Objekt. Temporäre Tabellen nimmst du weiter, wenn du mehrere Felder pro Eintrag, Sortierung, Filter oder die Anzeige auf einer Seite brauchst.
4JSON
| Typ | Bedeutung |
|---|---|
JsonObject | Objekt mit benannten Eigenschaften: { "name": "…" } |
JsonArray | Liste: [ … ] |
JsonValue | Einzelner Wert: Text, Zahl, Wahrheitswert, null |
JsonToken | Oberbegriff. Ein Token ist eines der drei anderen und wird mit AsObject(), AsArray(), AsValue() umgewandelt. |
JSON erzeugen
var
Order: JsonObject;
Lines: JsonArray;
Line: JsonObject;
JsonText: Text;
begin
Order.Add('customerNo', '10000');
Order.Add('orderDate', Today());
Order.Add('amount', 1234.5);
Order.Add('rush', true);
Line.Add('itemNo', '1000');
Line.Add('quantity', 3);
Lines.Add(Line);
Order.Add('lines', Lines);
Order.WriteTo(JsonText);
end;
Ergebnis:
{"customerNo":"10000","orderDate":"2025-03-01","amount":1234.5,"rush":true,"lines":[{"itemNo":"1000","quantity":3}]}
Add nimmt Text, Zahlen, Wahrheitswerte, Datums- und Zeitwerte sowie andere JSON-Typen. Für Enums entscheidest du selbst: Wert.AsInteger() ist stabil, Format(Wert) liefert die Caption in der Sprache des Benutzers und taugt deshalb nicht für Schnittstellen.
JSON lesen
var
Order: JsonObject;
Token: JsonToken;
LineToken: JsonToken;
Line: JsonObject;
CustomerNo: Code[20];
Quantity: Decimal;
begin
if not Order.ReadFrom(JsonText) then
Error(InvalidJsonErr);
// einzelne Eigenschaft
if Order.Get('customerNo', Token) then
CustomerNo := CopyStr(Token.AsValue().AsCode(), 1, MaxStrLen(CustomerNo));
// verschachtelter Zugriff per Pfad
if Order.SelectToken('$.lines[0].itemNo', Token) then
Message(Token.AsValue().AsText());
// Array durchlaufen
if Order.Get('lines', Token) then
foreach LineToken in Token.AsArray() do begin
Line := LineToken.AsObject();
if Line.Get('quantity', Token) then
Quantity := Token.AsValue().AsDecimal();
end;
end;
GetundSelectTokengebenfalsezurück, wenn es die Eigenschaft nicht gibt. Prüfe das immer, externe Systeme liefern selten genau das, was die Dokumentation verspricht.JsonValuehat Umwandlungen für alle gängigen Typen:AsText,AsCode,AsInteger,AsDecimal,AsBoolean,AsDate,AsDateTime. MitIsNull()fängst dunullab, sonst gibt es einen Laufzeitfehler.- In neueren Versionen gibt es Kurzformen am Objekt wie
Order.GetText('customerNo'),GetInteger,GetObject,GetArray. Sie sparen den Umweg über das Token. ReadFromundWriteToarbeiten auch direkt mit Streams.
5XML
Für den Datenaustausch mit festem Format bleiben XMLports das bequemste Mittel (Seite 7). Für freies Lesen und Schreiben gibt es die XML-Typen.
XML lesen
var
Doc: XmlDocument;
Nodes: XmlNodeList;
Node: XmlNode;
Child: XmlNode;
Element: XmlElement;
Attribute: XmlAttribute;
begin
if not XmlDocument.ReadFrom(XmlText, Doc) then
Error(InvalidXmlErr);
if Doc.SelectNodes('//visit', Nodes) then
foreach Node in Nodes do begin
Element := Node.AsXmlElement();
if Element.Attributes().Get('entryNo', Attribute) then
Message(Attribute.Value());
if Element.SelectSingleNode('customerNo', Child) then
Message(Child.AsXmlElement().InnerText());
end;
end;
XML mit Namensräumen
var
NsMgr: XmlNamespaceManager;
begin
NsMgr.NameTable(Doc.NameTable());
NsMgr.AddNamespace('inv', 'urn:example:invoice:1.0');
Doc.SelectNodes('//inv:line', NsMgr, Nodes);
end;
Ohne Namespace-Manager findet XPath in Dokumenten mit Namensraum nichts. Das ist die häufigste Ursache für „SelectNodes liefert keine Treffer“.
XML erzeugen
var
Doc: XmlDocument;
Root: XmlElement;
VisitElement: XmlElement;
XmlText: Text;
begin
Doc := XmlDocument.Create();
Doc.SetDeclaration(XmlDeclaration.Create('1.0', 'utf-8', 'yes'));
Root := XmlElement.Create('visits');
Doc.Add(Root);
VisitElement := XmlElement.Create('visit');
VisitElement.SetAttribute('entryNo', Format(Visit."Entry No.", 0, 9));
VisitElement.Add(XmlElement.Create('customerNo', Visit."Customer No."));
VisitElement.Add(XmlElement.Create('visitDate', Format(Visit."Visit Date", 0, 9)));
Root.Add(VisitElement);
Doc.WriteTo(XmlText);
end;
Die Hilfstabelle „XML Buffer“ aus dem Standard gibt es weiterhin. Sie lädt ein Dokument in eine temporäre Tabelle, was bei einfachen Strukturen bequemer sein kann als XPath.
6Webdienste aufrufen mit HttpClient
HttpWebRequest : DotNet "'System'.System.Net.HttpWebRequest";
HttpWebResponse : DotNet "'System'.System.Net.HttpWebResponse";
StreamReader : DotNet "'mscorlib'.System.IO.StreamReader";
HttpWebRequest := HttpWebRequest.Create(Url);
HttpWebRequest.Method := 'GET';
HttpWebResponse := HttpWebRequest.GetResponse;
StreamReader := StreamReader.StreamReader(
HttpWebResponse.GetResponseStream);
ResponseText := StreamReader.ReadToEnd;
var
Client: HttpClient;
Response: HttpResponseMessage;
ResponseText: Text;
begin
if not Client.Get(Url, Response) then
Error(ConnectionErr);
if not Response.IsSuccessStatusCode() then
Error(HttpStatusErr,
Response.HttpStatusCode(),
Response.ReasonPhrase());
Response.Content.ReadAs(ResponseText);
end;
Die Typen
| Typ | Aufgabe |
|---|---|
HttpClient | Sendet Anfragen. Kurzformen Get, Post, Put, Delete, allgemein Send. |
HttpRequestMessage | Eine Anfrage mit Methode, Adresse, Kopfzeilen und Inhalt. |
HttpResponseMessage | Die Antwort mit Statuscode, Kopfzeilen und Inhalt. |
HttpContent | Der Inhalt von Anfrage oder Antwort, als Text oder Stream. |
HttpHeaders | Kopfzeilen. Es gibt getrennte für die Anfrage und für den Inhalt. |
POST mit JSON und Anmeldung
procedure SendVisit(Url: Text; Payload: JsonObject; AccessToken: SecretText): Boolean
var
Client: HttpClient;
Request: HttpRequestMessage;
Response: HttpResponseMessage;
Content: HttpContent;
ContentHeaders: HttpHeaders;
RequestHeaders: HttpHeaders;
PayloadText: Text;
begin
Payload.WriteTo(PayloadText);
Content.WriteFrom(PayloadText);
// Content-Type gehört zu den Kopfzeilen des Inhalts
Content.GetHeaders(ContentHeaders);
if ContentHeaders.Contains('Content-Type') then
ContentHeaders.Remove('Content-Type');
ContentHeaders.Add('Content-Type', 'application/json');
Request.Method('POST');
Request.SetRequestUri(Url);
Request.Content(Content);
// Authorization und Accept gehören zu den Kopfzeilen der Anfrage
Request.GetHeaders(RequestHeaders);
RequestHeaders.Add('Accept', 'application/json');
RequestHeaders.Add('Authorization', SecretStrSubstNo('Bearer %1', AccessToken));
Client.Timeout(30000);
if not Client.Send(Request, Response) then
exit(false);
exit(Response.IsSuccessStatusCode());
end;
- Zwei Arten von Kopfzeilen.
Content-Typean die Anfrage-Kopfzeilen zu hängen, führt zu einem Laufzeitfehler. Der Inhalt hat bereits einen Standardwert (text/plain), deshalb zuerst entfernen, dann neu setzen. - Zwei Arten von Fehlern. Gibt
SendoderGetfalsezurück, kam keine Verbindung zustande (Name nicht auflösbar, Zeitüberschreitung, blockiert). Kam eine Antwort, sagt dir erstIsSuccessStatusCode(), ob sie im Bereich 200 bis 299 liegt. - Basic-Anmeldung:
'Basic ' + Base64Convert.ToBase64(User + ':' + Password)mit der Codeunit"Base64 Convert". - OAuth: Die System Application enthält die Codeunit
OAuth2, die Tokens für die gängigen Abläufe beschafft, etwa mit Client-ID und Geheimnis. - Rest Client: Neuere Versionen bringen in der System Application ein Modul „Rest Client“ mit, das die oben gezeigten Handgriffe in wenigen Aufrufen bündelt. Die rohen Typen solltest du trotzdem kennen.
Einschränkungen in der Cloud
| Punkt | Bedeutung |
|---|---|
| Erlaubnis je App | In der Erweiterungsverwaltung gibt es je App unter „Konfigurieren“ den Schalter „HttpClient-Anforderungen zulassen“. In Sandboxes, vor allem in Kopien der Produktion, ist er zunächst aus. Dann scheitert der Aufruf, und Response.IsBlockedByEnvironment() liefert true. |
| Nur erreichbare Adressen | Der Server steht bei Microsoft. Ein Dienst im Firmennetz des Kunden ist von dort nicht erreichbar, außer er wird über das Internet veröffentlicht oder über einen Vermittler angebunden. |
| Zeitlimit | Standard und Obergrenze liegen bei rund 100 Sekunden. Lange Verarbeitungen muss der Dienst asynchron anbieten. |
| Verschlüsselung | Verwende HTTPS. Selbst signierte Zertifikate werden abgelehnt. |
| Transaktionen | Ein Webaufruf mitten in einer Schreibtransaktion hält Sperren, solange der Dienst antwortet. Rufe den Dienst vor dem Schreiben auf oder in einem eigenen Schritt über die Aufgabenwarteschlange. |
7Zugangsdaten sicher ablegen
Kennwörter und Schlüssel gehören weder in den Quelltext noch in Labels noch in normale Tabellenfelder. Tabellen lassen sich exportieren, per API lesen und landen in Sandbox-Kopien.
SecretText
Eine Variable vom Typ SecretText ist im Debugger nicht einsehbar und lässt sich nicht in normalen Text zurückverwandeln, außer mit einer bewusst gekennzeichneten Methode. HttpHeaders.Add, IsolatedStorage und SecretStrSubstNo nehmen sie direkt entgegen. Den Typ gibt es seit Version 23.
IsolatedStorage
procedure SaveApiKey(ApiKey: SecretText)
begin
IsolatedStorage.Set('ABC-ApiKey', ApiKey, DataScope::Company);
end;
procedure GetApiKey() ApiKey: SecretText
var
ApiKeyMissingErr: Label 'The API key has not been set up.';
begin
if not IsolatedStorage.Get('ABC-ApiKey', DataScope::Company, ApiKey) then
Error(ApiKeyMissingErr);
end;
| DataScope | Der Wert gilt für |
|---|---|
Module | die App, in allen Mandanten |
Company | die App im aktuellen Mandanten |
User | die App und den aktuellen Benutzer |
CompanyAndUser | die App, den Mandanten und den Benutzer |
- Nur deine App kann ihre Werte lesen. Andere Apps und Benutzer kommen nicht heran.
- Auf der Einrichtungsseite zeigst du ein Feld mit
ExtendedDatatype = Masked, das nicht an ein Tabellenfeld gebunden ist, sondern an eine Variable. ImOnValidateschreibst du den Wert in dieIsolatedStorage. - Das Attribut
[NonDebuggable]an einer Funktion verhindert, dass ihre Variablen im Debugger sichtbar sind. - Für AppSource-Apps mit eigenen, für alle Kunden gleichen Geheimnissen gibt es die Anbindung an Azure Key Vault. Für Kundenprojekte reicht
IsolatedStorage.
8Dateien ohne Dateisystem
Eine Datei ist in Business Central ein Strom von Bytes, der zwischen Browser, Arbeitsspeicher, Blob-Feld und Webdienst wandert. Die zwei Typen dafür kennst du schon: InStream zum Lesen und OutStream zum Schreiben.
Hochladen und zeilenweise lesen
ServerFile := FileMgt.UploadFile('Import','*.csv');
ImportFile.TEXTMODE(TRUE);
ImportFile.OPEN(ServerFile);
WHILE ImportFile.READ(Line) > 0 DO
ProcessLine(Line);
ImportFile.CLOSE;
ERASE(ServerFile);
var
InStr: InStream;
FileName: Text;
Line: Text;
begin
if not UploadIntoStream('Select file', '',
'CSV files (*.csv)|*.csv', FileName, InStr)
then
exit;
while not InStr.EOS() do begin
InStr.ReadText(Line);
ProcessLine(Line);
end;
end;
Die Codeunit „Temp Blob“
"Temp Blob" ist ein Zwischenspeicher im Arbeitsspeicher. Du schreibst über einen OutStream hinein und liest über einen InStream wieder heraus. Sie ersetzt die frühere Tabelle „TempBlob“ und jede temporäre Serverdatei.
var
TempBlob: Codeunit "Temp Blob";
OutStr: OutStream;
InStr: InStream;
FileName: Text;
begin
// schreiben
TempBlob.CreateOutStream(OutStr, TextEncoding::UTF8);
OutStr.WriteText('Kopfzeile');
OutStr.WriteText(); // Zeilenumbruch
OutStr.WriteText('Zweite Zeile');
// als Download anbieten
TempBlob.CreateInStream(InStr, TextEncoding::UTF8);
FileName := 'export.txt';
DownloadFromStream(InStr, '', '', '', FileName);
end;
Zeichenkodierung
Ohne Angabe verwenden Streams eine alte DOS-Kodierung, und Umlaute kommen falsch an. Gib die Kodierung immer an: TextEncoding::UTF8 für fast alles Moderne, TextEncoding::Windows für Dateien aus älteren Windows-Programmen. Der Stream aus UploadIntoStream hat keine Kodierungsangabe. Kopiere ihn deshalb in einen Temp Blob und lies von dort:
TempBlob.CreateOutStream(OutStr);
CopyStream(OutStr, UploadStream);
TempBlob.CreateInStream(TextStream, TextEncoding::UTF8);
Blob-Felder
// schreiben
Rec."Long Text".CreateOutStream(OutStr, TextEncoding::UTF8);
OutStr.WriteText(LongText);
Rec.Modify();
// lesen
Rec.CalcFields("Long Text");
if Rec."Long Text".HasValue() then begin
Rec."Long Text".CreateInStream(InStr, TextEncoding::UTF8);
InStr.Read(LongText);
end;
Wie früher brauchst du CalcFields, bevor du ein Blob-Feld liest. Bilder legst du besser in Media-Feldern ab, mit Rec.Picture.ImportStream(InStr, FileName).
Streams als Bindeglied
| Quelle oder Ziel | So bekommst du den Stream |
|---|---|
| Datei vom Benutzer | UploadIntoStream |
| Datei zum Benutzer | DownloadFromStream |
| Arbeitsspeicher | TempBlob.CreateInStream, CreateOutStream |
| Blob-Feld | Rec.Feld.CreateInStream, CreateOutStream |
| Webdienst | Response.Content.ReadAs(InStr), Content.WriteFrom(InStr) |
| JSON und XML | ReadFrom(InStr), WriteTo(OutStr) |
| XMLport | Xmlport.Import(Id, InStr), Xmlport.Export(Id, OutStr) |
| Bericht | Report.SaveAs(Id, Parameter, ReportFormat::Pdf, OutStr) |
| E-Mail-Anhang | EmailMessage.AddAttachment(Name, ContentType, InStr) |
| ZIP-Archiv | Codeunit "Data Compression" |
Mit CopyStream(OutStr, InStr) verbindest du zwei beliebige Enden. Ein Bericht als PDF in einen E-Mail-Anhang, eine Antwort eines Webdienstes in ein Blob-Feld, mehrere Exporte in ein ZIP zum Download: alles ohne eine einzige Datei auf dem Server.
CSV richtig einlesen
Zeilenweise lesen und mit Split trennen reicht für einfache Dateien. Sobald Werte in Anführungszeichen stehen und selbst das Trennzeichen oder Zeilenumbrüche enthalten, nimm einen XMLport mit Format = VariableText (Seite 7) oder die Standardtabelle „CSV Buffer“.
9Wohin mit Dateien und Nachrichten?
| Früher | Heute | Hinweis |
|---|---|---|
| Export in einen Ordner, den ein anderes Programm abholt | Azure Blob Storage oder Azure Files über die Module der System Application | Codeunit "ABS Blob Client" zum Hoch- und Herunterladen. |
| Ablage auf dem Fileserver | SharePoint oder OneDrive | Es gibt ein SharePoint-Modul und in neueren Versionen ein einheitliches Modul für externe Dateispeicher. |
| FTP und SFTP | Kein direkter Zugriff aus AL | Vermittler wie Azure Logic Apps, Power Automate oder eine Azure Function, die per HTTP angesprochen wird. |
| Import aus einem Ordner per NAS | Das andere System ruft eine API von Business Central auf (Seite 7), oder eine Aufgabe in der Warteschlange holt die Daten per HTTP ab | Die Richtung dreht sich oft um: Daten werden gebracht statt abgeholt. |
| SMTP Mail | Modul E-Mail | Der Kunde richtet E-Mail-Konten ein, dein Code ist vom Anbieter unabhängig. |
| Druck auf einen Netzwerkdrucker | Universal Print oder E-Mail-Drucker, sonst PDF im Browser | Der Server kennt die Drucker des Kunden nicht. |
E-Mail senden
var
EmailMessage: Codeunit "Email Message";
Email: Codeunit Email;
TempBlob: Codeunit "Temp Blob";
InStr: InStream;
begin
EmailMessage.Create('vertrieb@example.com', 'Besuchsübersicht', 'Anbei die aktuelle Liste.');
// ... TempBlob füllen ...
TempBlob.CreateInStream(InStr);
EmailMessage.AddAttachment('visits.json', 'application/json', InStr);
Email.Send(EmailMessage, Enum::"Email Scenario"::Default);
end;
Email.OpenInEditor zeigt dem Benutzer die Nachricht vor dem Senden, Email.Enqueue versendet im Hintergrund. Über Szenarien legt der Kunde fest, welches Konto für welchen Zweck verwendet wird.
10Nützliche Module des Standards
Bevor du etwas selbst baust, lohnt ein Blick in die System Application und die Base Application. Mit Strg+T suchst du in VS Code nach Objektnamen.
| Codeunit oder Modul | Wofür |
|---|---|
"Temp Blob", "Persistent Blob" | Zwischenspeicher im Arbeitsspeicher bzw. dauerhaft |
"Base64 Convert" | Base64 aus Text oder Stream und zurück |
"Data Compression" | ZIP-Archive erzeugen und entpacken, GZip |
"Cryptography Management" | Hashwerte (SHA-256 usw.), HMAC, Verschlüsselung, Signaturen |
Regex | Reguläre Ausdrücke |
"Type Helper" | Sammlung von Umwandlungen: Datumsformate, URL-Kodierung, Zeilenumbrüche, Zeitzonen |
Math | Mathematische Funktionen |
"Email Message", Email | |
OAuth2 | Tokens beschaffen |
"ABS Blob Client" und verwandte | Azure Blob Storage |
"File Management" | Gibt es weiter, aber nur noch mit streambasierten Funktionen wie BLOBImport und BLOBExport sowie Hilfen für Dateinamen |
"Excel Buffer" (Tabelle) | Excel-Dateien lesen und schreiben |
"CSV Buffer", "XML Buffer", "JSON Buffer" (Tabellen) | Dateien in temporäre Tabellen laden |
"Environment Information" | Produktion oder Sandbox? Online oder On-Premises? |
"No. Series" | Nummernserien, neu aufgebaut. Ersetzt „NoSeriesManagement“. |
"Barcode Font Provider", Image | Barcodes in Berichten, Bildbearbeitung |
"Feature Telemetry", Telemetry | Eigene Telemetrie (Seite 9) |
EnvironmentInformation.IsSandbox() und verwende dort eine Testadresse oder brich ab.
11Excel und Word
- Excel lesen und schreiben im Code: Die temporäre Tabelle „Excel Buffer“ gibt es weiterhin, jetzt streambasiert. Typische Aufrufe sind
OpenBookStream,ReadSheetzum Lesen sowieCreateNewBook,WriteSheet,CloseBookundSaveToStreamzum Schreiben. - Excel für Benutzer: Jede Liste lässt sich über „In Excel öffnen“ und „In Excel bearbeiten“ ohne Code exportieren. Für Auswertungen gibt es Berichte mit Excel-Layout (Seite 7). Viele früher programmierte Excel-Exporte sind damit überflüssig.
- Word: Word-Layouts für Berichte ersetzen die Word-Automation. Serienbriefe an Kontakte deckt der Standard mit Word-Vorlagen ab.
12Was auf dem Client lief
| Früher (Windows-Client) | Heute |
|---|---|
| .NET-Add-in auf einer Seite | Control Add-in: JavaScript, HTML und CSS, die im Browser laufen und mit AL über Events und Funktionen sprechen |
DotNet mit RunOnClient, z. B. lokaler Dateidialog, lokales Programm starten | Nicht möglich. Dateien über Upload und Download, Programme gar nicht |
| Waage, Scanner, Kartenleser über COM | Geräte, die als Tastatur arbeiten, funktionieren weiter. Sonst ein lokaler Dienst, den ein Control Add-in oder die Cloud per HTTP anspricht |
HYPERLINK | Hyperlink(Url) öffnet einen neuen Browser-Tab |
controladdin "ABC Map"
{
Scripts = 'addin/map.js';
StartupScript = 'addin/startup.js';
StyleSheets = 'addin/map.css';
RequestedHeight = 300;
HorizontalStretch = true;
event ControlReady();
event MarkerClicked(CustomerNo: Text);
procedure ShowAddress(Address: Text);
}
Das Add-in wird auf einer Seite mit usercontrol(Map; "ABC Map") eingebunden. Die Dateien liegen im Projekt und werden mit der App ausgeliefert. Für den Einstieg brauchst du das selten.
13Wenn nichts davon reicht
- Externer Dienst. Du schreibst die fehlende Funktion als Azure Function (in C#, also mit dem vollen .NET) und rufst sie mit
HttpClientauf. Das ist der übliche Weg für PDF-Bearbeitung, SFTP, besondere Dateiformate oder Bibliotheken von Drittanbietern. - Power Automate oder Logic Apps. Für Abläufe zwischen Systemen ohne eigenen Code. Business Central hat dafür einen fertigen Konnektor.
- On-Premises mit DotNet. Nur wenn sicher ist, dass die Lösung nie in die Cloud muss:
// nur mit "target": "OnPrem" in der app.json
dotnet
{
assembly(mscorlib)
{
type(System.IO.Path; SystemPath) { }
}
}
codeunit 50190 "ABC OnPrem Only"
{
procedure GetTempPath(): Text
var
Path: DotNet SystemPath;
begin
exit(Path.GetTempPath());
end;
}
"target": "OnPrem" lässt sich in keiner Online-Umgebung installieren. Lagere solchen Code wenigstens in eine eigene kleine App aus, damit der Rest deiner Lösung cloudfähig bleibt.
14Übung: Export, Import und ein Webaufruf
Schritt 1. src/ABCVisitExport.Codeunit.al
codeunit 50107 "ABC Visit Export"
{
procedure ExportToJson(var Visit: Record "ABC Customer Visit")
var
TempBlob: Codeunit "Temp Blob";
VisitArray: JsonArray;
OutStr: OutStream;
InStr: InStream;
FileName: Text;
NoVisitsErr: Label 'There are no visits to export.';
FileNameTok: Label 'visits.json', Locked = true;
begin
if not Visit.FindSet() then
Error(NoVisitsErr);
repeat
VisitArray.Add(VisitToJson(Visit));
until Visit.Next() = 0;
TempBlob.CreateOutStream(OutStr, TextEncoding::UTF8);
VisitArray.WriteTo(OutStr);
TempBlob.CreateInStream(InStr, TextEncoding::UTF8);
FileName := FileNameTok;
DownloadFromStream(InStr, '', '', '', FileName);
end;
local procedure VisitToJson(Visit: Record "ABC Customer Visit") Result: JsonObject
begin
Result.Add('entryNo', Visit."Entry No.");
Result.Add('customerNo', Visit."Customer No.");
Result.Add('visitDate', Visit."Visit Date");
Result.Add('visitType', Visit."Visit Type".AsInteger());
Result.Add('description', Visit.Description);
Result.Add('durationMinutes', Visit."Duration (Minutes)");
end;
}
Die eigene Funktion VisitToJson liefert bei jedem Aufruf ein neues Objekt. Würdest du stattdessen eine einzige JsonObject-Variable in der Schleife wiederverwenden, müsstest du wegen der Referenzsemantik aus Abschnitt 3 genau aufpassen, dass nicht jeder Eintrag des Arrays auf dasselbe Objekt zeigt.
Schritt 2. src/ABCVisitImport.Codeunit.al
codeunit 50108 "ABC Visit Import"
{
procedure ImportFromCsv()
var
TempBlob: Codeunit "Temp Blob";
VisitMgt: Codeunit "ABC Visit Mgt.";
UploadStream: InStream;
TextStream: InStream;
OutStr: OutStream;
Columns: List of [Text];
FileName: Text;
Line: Text;
VisitDate: Date;
VisitTypeNo: Integer;
LineNo: Integer;
Imported: Integer;
SelectFileLbl: Label 'Select the visit file';
FileFilterTok: Label 'CSV files (*.csv)|*.csv', Locked = true;
ColumnCountErr: Label 'Line %1 has fewer than 4 columns.', Comment = '%1 = Line No.';
InvalidDateErr: Label 'Line %1: %2 is not a valid date. Use the format YYYY-MM-DD.', Comment = '%1 = Line No., %2 = Value';
InvalidTypeErr: Label 'Line %1: %2 is not a valid visit type.', Comment = '%1 = Line No., %2 = Value';
ImportedMsg: Label '%1 visits were imported.', Comment = '%1 = Number of visits';
begin
if not UploadIntoStream(SelectFileLbl, '', FileFilterTok, FileName, UploadStream) then
exit;
TempBlob.CreateOutStream(OutStr);
CopyStream(OutStr, UploadStream);
TempBlob.CreateInStream(TextStream, TextEncoding::UTF8);
while not TextStream.EOS() do begin
TextStream.ReadText(Line);
LineNo += 1;
// Zeile 1 ist die Kopfzeile, leere Zeilen überspringen
if (LineNo > 1) and (Line.Trim() <> '') then begin
Columns := Line.Split(';');
if Columns.Count() < 4 then
Error(ColumnCountErr, LineNo);
if not Evaluate(VisitDate, Columns.Get(2).Trim(), 9) then
Error(InvalidDateErr, LineNo, Columns.Get(2));
if not Evaluate(VisitTypeNo, Columns.Get(3).Trim()) then
Error(InvalidTypeErr, LineNo, Columns.Get(3));
VisitMgt.CreateVisit(
CopyStr(Columns.Get(1).Trim(), 1, 20),
VisitDate,
Enum::"ABC Visit Type".FromInteger(VisitTypeNo),
CopyStr(Columns.Get(4).Trim(), 1, 100));
Imported += 1;
end;
end;
Message(ImportedMsg, Imported);
end;
}
Lege zum Testen eine Datei visits.csv an, gespeichert als UTF-8. Ersetze die Debitorennummern durch solche, die es in deiner Sandbox gibt:
CustomerNo;VisitDate;VisitType;Description
10000;2025-03-03;1;Rückruf wegen Angebot
20000;2025-03-04;1;Terminabsprache Messe
10000;2025-03-05;2;Gespräch am Messestand
Schritt 3. src/ABCHttpDemo.Codeunit.al
codeunit 50109 "ABC Http Demo"
{
procedure GetSampleTitle(): Text
var
Client: HttpClient;
Response: HttpResponseMessage;
Result: JsonObject;
Token: JsonToken;
ResponseText: Text;
UrlTok: Label 'https://jsonplaceholder.typicode.com/todos/1', Locked = true;
BlockedErr: Label 'Outgoing web requests are not allowed for this app. Enable "Allow HttpClient Requests" in Extension Management.';
ConnectionErr: Label 'The web service could not be reached.';
HttpStatusErr: Label 'The web service returned status %1 (%2).', Comment = '%1 = Status code, %2 = Reason';
InvalidResponseErr: Label 'The web service returned an unexpected response.';
begin
if not Client.Get(UrlTok, Response) then begin
if Response.IsBlockedByEnvironment() then
Error(BlockedErr);
Error(ConnectionErr);
end;
if not Response.IsSuccessStatusCode() then
Error(HttpStatusErr, Response.HttpStatusCode(), Response.ReasonPhrase());
Response.Content.ReadAs(ResponseText);
if not Result.ReadFrom(ResponseText) then
Error(InvalidResponseErr);
if not Result.Get('title', Token) then
Error(InvalidResponseErr);
exit(Token.AsValue().AsText());
end;
}
Die Adresse ist ein frei zugänglicher Testdienst, der ein kleines JSON-Objekt mit der Eigenschaft title liefert. Jede andere öffentliche JSON-Adresse geht ebenso, du musst dann nur den Namen der Eigenschaft anpassen.
Schritt 4. Ergänze in src/ABCCustomerVisits.Page.al im Abschnitt actions einen neuen Bereich vor area(Navigation):
area(Processing)
{
action(ExportJson)
{
Caption = 'Export as JSON';
Image = Export;
ToolTip = 'Download the selected visits as a JSON file.';
trigger OnAction()
var
Visit: Record "ABC Customer Visit";
VisitExport: Codeunit "ABC Visit Export";
begin
CurrPage.SetSelectionFilter(Visit);
VisitExport.ExportToJson(Visit);
end;
}
action(ImportCsv)
{
Caption = 'Import from CSV';
Image = Import;
ToolTip = 'Create visits from a CSV file.';
trigger OnAction()
var
VisitImport: Codeunit "ABC Visit Import";
begin
VisitImport.ImportFromCsv();
CurrPage.Update(false);
end;
}
action(TestWebCall)
{
Caption = 'Test Web Call';
Image = Web;
ToolTip = 'Call a sample web service and show the result.';
trigger OnAction()
var
HttpDemo: Codeunit "ABC Http Demo";
begin
Message(HttpDemo.GetSampleTitle());
end;
}
}
Und in area(Promoted) innerhalb der Gruppe Category_Process:
actionref(ExportJson_Promoted; ExportJson)
{
}
actionref(ImportCsv_Promoted; ImportCsv)
{
}
Schritt 5. Testen.
- Veröffentliche mit F5 und öffne die Besuchsliste.
- Markiere zwei Zeilen und wähle „Export as JSON“. Öffne die heruntergeladene Datei in VS Code und formatiere sie mit Umschalt+Alt+F.
- Importiere die CSV-Datei. Die Liste zeigt drei neue Besuche, die Dauer der Telefonate ist durch das Interface von Seite 5 mit 15 vorbelegt.
- Ändere in der CSV-Datei ein Datum auf
03.03.2025und importiere erneut. Du bekommst die Fehlermeldung mit Zeilennummer, und es wurde kein einziger Besuch angelegt, weil der Fehler die ganze Transaktion zurückrollt. - Ändere eine Besuchsart auf
0(vor Ort). Der Import scheitert an der Prüfung ausCheckVisit, weil der Verkäufercode fehlt. Deine Geschäftsregeln gelten also auch für den Import, weil sie in der Tabelle und nicht in der Seite stehen. - Wähle „Test Web Call“. Kommt die Meldung, dass Anfragen nicht erlaubt sind, öffne die Erweiterungsverwaltung, wähle bei deiner App „Konfigurieren“ und schalte „HttpClient-Anforderungen zulassen“ ein.
- Ergänze die neuen Texte in der deutschen XLIFF-Datei und committe.
15Typische Denkfehler
- „Ich schreibe die Datei kurz nach C:\Temp.“ Es gibt keinen Pfad. Nimm einen Temp Blob.
- „Format(Datum) reicht für die Schnittstelle.“ Ohne Formatnummer 9 hängt das Ergebnis von der Sprache des Benutzers ab.
- „Die Umlaute sind kaputt, das liegt an der Datei.“ Meist fehlt die Angabe
TextEncoding::UTF8am Stream. - „Content-Type setze ich bei den Kopfzeilen der Anfrage.“ Er gehört zu den Kopfzeilen des Inhalts.
- „Send hat true geliefert, also hat es geklappt.“ Das heißt nur, dass eine Antwort kam. Prüfe den Statuscode.
- „Der API-Schlüssel steht in der Einrichtungstabelle.“ Dort ist er für jeden mit Leserecht und in jeder Sandbox-Kopie sichtbar. Nimm
IsolatedStorage. - „Den Webdienst rufe ich im Buchungs-Subscriber auf.“ Dann hängen Sperren am Antwortverhalten eines fremden Systems. Trenne Aufruf und Buchung.
- „Ich kopiere die Liste in eine zweite Variable und ändere die Kopie.“ Beide Variablen zeigen auf dieselbe Liste.
- „Dafür brauche ich DotNet, also baue ich On-Premises.“ Prüfe zuerst die System Application und danach eine Azure Function.
16Selbsttest
Was ersetzt den DotNet-StringBuilder, und wann lohnt er sich?
TextBuilder. Er lohnt sich, wenn in einer Schleife viele Teile aneinandergehängt werden.
Bei welchem Index beginnt eine List in AL?
Bei 1.
Wie liest du den Wert der Eigenschaft name aus einem JsonObject?
Mit Get('name', Token) das Token holen, den Rückgabewert prüfen und dann Token.AsValue().AsText() aufrufen.
SelectNodes findet in einem XML-Dokument nichts, obwohl die Elemente vorhanden sind. Woran liegt es meistens?
Das Dokument verwendet einen Namensraum, und der XPath-Ausdruck wurde ohne XmlNamespaceManager ausgeführt.
Was unterscheidet den Rückgabewert von Client.Send von Response.IsSuccessStatusCode()?
Der erste sagt, ob überhaupt eine Antwort kam. Der zweite sagt, ob die Antwort einen Erfolgsstatus hat.
Wo legst du einen API-Schlüssel ab?
In der IsolatedStorage, im Code als SecretText weitergereicht.
Wie erzeugst du eine Textdatei und bietest sie dem Benutzer zum Download an?
In einen OutStream eines Temp Blob schreiben, daraus einen InStream erzeugen und DownloadFromStream aufrufen.
Der Kunde braucht einen SFTP-Upload. Wie löst du das für die Cloud?
Über einen Vermittler wie eine Azure Function, eine Logic App oder Power Automate, den Business Central per HTTP anspricht oder der die Daten über eine API abholt.
17Zusammenfassung
Für fast jede DotNet-Klasse, die du in NAV 2017 verwendet hast, gibt es einen eigenen AL-Typ oder ein Modul der System Application. Dateien sind Streams, die zwischen Browser, Temp Blob, Blob-Feld und Webdienst wandern. Schnittstellen laufen über HTTP und JSON statt über Ordner, Zugangsdaten liegen in der IsolatedStorage, und was AL nicht kann, erledigt ein externer Dienst.
Checkliste: Textmethoden und TextBuilder ausprobiert · Liste und Dictionary benutzt · JSON erzeugt und gelesen · Besuche als JSON heruntergeladen · CSV-Datei importiert und einen abgewiesenen Import gesehen · Webdienst aufgerufen und den Schalter in der Erweiterungsverwaltung gefunden · Stand committet.