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

Ersatz für DotNet und Dateisystem

Was in der Cloud an die Stelle von DotNet-Variablen und Dateizugriffen tritt und wie du alten Code darauf umstellst.

Stand November 2026 · Version 29

Autor: Elvis Schmidt, decoso GmbH & Co. KG

Lernziele dieser Seite. Du weißt danach, welcher AL-Typ welche DotNet-Klasse ersetzt, kannst Texte, Listen, JSON und XML ohne DotNet verarbeiten, Webdienste mit 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 CentralAbschnitt
System.Text.StringBuilderTextBuilder2
System.String-Methoden, STRPOS, COPYSTR, CONVERTSTRMethoden am Typ Text2
System.Text.RegularExpressions.RegexCodeunit Regex2
System.Collections.Generic.List, ArrayListList of [T]3
System.Collections.Generic.DictionaryDictionary of [K, V]3
Newtonsoft.Json (JObject, JArray)JsonObject, JsonArray, JsonToken, JsonValue4
System.Xml.XmlDocument, Codeunit 6224 „XML DOM Management“XmlDocument, XmlElement, XmlNode …5
System.Net.HttpWebRequest, System.Net.Http.HttpClientHttpClient, HttpRequestMessage, HttpResponseMessage6
Kennwörter in Tabellenfeldern, Service PasswordSecretText, IsolatedStorage7
FILE, UPLOAD, DOWNLOAD, Codeunit 419 „File Management“InStream, OutStream, UploadIntoStream, DownloadFromStream8
Tabelle 99008535 „TempBlob“Codeunit "Temp Blob"8
System.Convert (Base64)Codeunit "Base64 Convert"10
System.IO.CompressionCodeunit "Data Compression"10
System.Security.CryptographyCodeunit "Cryptography Management"10
SMTP Mail (Codeunit 400), Outlook-AutomationModul E-Mail: Codeunits "Email Message" und Email9
Netzlaufwerk, FTP-OrdnerAzure Blob Storage, SharePoint, externer Dienst9
Excel- und Word-AutomationTabelle „Excel Buffer“, Excel- und Word-Layouts für Berichte11
Client-Add-ins in .NETControl Add-ins in JavaScript12

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;
MethodeErsetzt früher
Contains, IndexOf, LastIndexOf, StartsWith, EndsWithSTRPOS und Vergleiche mit COPYSTR
Substring, RemoveCOPYSTR, DELSTR
ReplaceEigene Schleifen oder DotNet String.Replace
SplitSELECTSTR oder eigene Schleifen
Trim, TrimStart, TrimEndDELCHR(…,'<>')
ToLower, ToUpperLOWERCASE, UPPERCASE
PadLeft, PadRightPADSTR 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.

Überlauf bei Zuweisungen. Weist du einen langen 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

NAV 2017
StringBuilder : DotNet "'mscorlib'.System.Text.StringBuilder";

StringBuilder := StringBuilder.StringBuilder;
StringBuilder.Append('Zeile 1');
StringBuilder.AppendLine;
Result := StringBuilder.ToString;
Business Central
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;
TypWichtige 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

TypBedeutung
JsonObjectObjekt mit benannten Eigenschaften: { "name": "…" }
JsonArrayListe: [ … ]
JsonValueEinzelner Wert: Text, Zahl, Wahrheitswert, null
JsonTokenOberbegriff. 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;
  • Get und SelectToken geben false zurück, wenn es die Eigenschaft nicht gibt. Prüfe das immer, externe Systeme liefern selten genau das, was die Dokumentation verspricht.
  • JsonValue hat Umwandlungen für alle gängigen Typen: AsText, AsCode, AsInteger, AsDecimal, AsBoolean, AsDate, AsDateTime. Mit IsNull() fängst du null ab, 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.
  • ReadFrom und WriteTo arbeiten 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

NAV 2017
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;
Business Central
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

TypAufgabe
HttpClientSendet Anfragen. Kurzformen Get, Post, Put, Delete, allgemein Send.
HttpRequestMessageEine Anfrage mit Methode, Adresse, Kopfzeilen und Inhalt.
HttpResponseMessageDie Antwort mit Statuscode, Kopfzeilen und Inhalt.
HttpContentDer Inhalt von Anfrage oder Antwort, als Text oder Stream.
HttpHeadersKopfzeilen. 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-Type an 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 Send oder Get false zurück, kam keine Verbindung zustande (Name nicht auflösbar, Zeitüberschreitung, blockiert). Kam eine Antwort, sagt dir erst IsSuccessStatusCode(), 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

PunktBedeutung
Erlaubnis je AppIn 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 AdressenDer 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.
ZeitlimitStandard und Obergrenze liegen bei rund 100 Sekunden. Lange Verarbeitungen muss der Dienst asynchron anbieten.
VerschlüsselungVerwende HTTPS. Selbst signierte Zertifikate werden abgelehnt.
TransaktionenEin 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;
DataScopeDer Wert gilt für
Moduledie App, in allen Mandanten
Companydie App im aktuellen Mandanten
Userdie App und den aktuellen Benutzer
CompanyAndUserdie 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. Im OnValidate schreibst du den Wert in die IsolatedStorage.
  • 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

NAV 2017
ServerFile := FileMgt.UploadFile('Import','*.csv');
ImportFile.TEXTMODE(TRUE);
ImportFile.OPEN(ServerFile);
WHILE ImportFile.READ(Line) > 0 DO
  ProcessLine(Line);
ImportFile.CLOSE;
ERASE(ServerFile);
Business Central
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 ZielSo bekommst du den Stream
Datei vom BenutzerUploadIntoStream
Datei zum BenutzerDownloadFromStream
ArbeitsspeicherTempBlob.CreateInStream, CreateOutStream
Blob-FeldRec.Feld.CreateInStream, CreateOutStream
WebdienstResponse.Content.ReadAs(InStr), Content.WriteFrom(InStr)
JSON und XMLReadFrom(InStr), WriteTo(OutStr)
XMLportXmlport.Import(Id, InStr), Xmlport.Export(Id, OutStr)
BerichtReport.SaveAs(Id, Parameter, ReportFormat::Pdf, OutStr)
E-Mail-AnhangEmailMessage.AddAttachment(Name, ContentType, InStr)
ZIP-ArchivCodeunit "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.

Einschränkungen im Browser. Du kannst weder den Speicherort beim Benutzer bestimmen noch eine Datei unbemerkt von seinem PC lesen. Jeder Upload braucht einen Dialog. In Hintergrundsitzungen gibt es weder Upload noch Download. Mehrere Downloads hintereinander blockiert der Browser oft, packe sie in ein ZIP.

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üherHeuteHinweis
Export in einen Ordner, den ein anderes Programm abholtAzure Blob Storage oder Azure Files über die Module der System ApplicationCodeunit "ABS Blob Client" zum Hoch- und Herunterladen.
Ablage auf dem FileserverSharePoint oder OneDriveEs gibt ein SharePoint-Modul und in neueren Versionen ein einheitliches Modul für externe Dateispeicher.
FTP und SFTPKein direkter Zugriff aus ALVermittler wie Azure Logic Apps, Power Automate oder eine Azure Function, die per HTTP angesprochen wird.
Import aus einem Ordner per NASDas andere System ruft eine API von Business Central auf (Seite 7), oder eine Aufgabe in der Warteschlange holt die Daten per HTTP abDie Richtung dreht sich oft um: Daten werden gebracht statt abgeholt.
SMTP MailModul E-MailDer Kunde richtet E-Mail-Konten ein, dein Code ist vom Anbieter unabhängig.
Druck auf einen NetzwerkdruckerUniversal Print oder E-Mail-Drucker, sonst PDF im BrowserDer 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 ModulWofü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
RegexReguläre Ausdrücke
"Type Helper"Sammlung von Umwandlungen: Datumsformate, URL-Kodierung, Zeilenumbrüche, Zeitzonen
MathMathematische Funktionen
"Email Message", EmailE-Mail
OAuth2Tokens beschaffen
"ABS Blob Client" und verwandteAzure 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", ImageBarcodes in Berichten, Bildbearbeitung
"Feature Telemetry", TelemetryEigene Telemetrie (Seite 9)
Sandbox erkennen. Schnittstellen sollten in einer Sandbox nicht versehentlich das Produktivsystem der Gegenseite ansprechen. Prüfe mit 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, ReadSheet zum Lesen sowie CreateNewBook, WriteSheet, CloseBook und SaveToStream zum 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 SeiteControl 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 startenNicht möglich. Dateien über Upload und Download, Programme gar nicht
Waage, Scanner, Kartenleser über COMGeräte, die als Tastatur arbeiten, funktionieren weiter. Sonst ein lokaler Dienst, den ein Control Add-in oder die Cloud per HTTP anspricht
HYPERLINKHyperlink(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

  1. Externer Dienst. Du schreibst die fehlende Funktion als Azure Function (in C#, also mit dem vollen .NET) und rufst sie mit HttpClient auf. Das ist der übliche Weg für PDF-Bearbeitung, SFTP, besondere Dateiformate oder Bibliotheken von Drittanbietern.
  2. Power Automate oder Logic Apps. Für Abläufe zwischen Systemen ohne eigenen Code. Business Central hat dafür einen fertigen Konnektor.
  3. 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;
}
Sackgasse. Eine App mit "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.

  1. Veröffentliche mit F5 und öffne die Besuchsliste.
  2. Markiere zwei Zeilen und wähle „Export as JSON“. Öffne die heruntergeladene Datei in VS Code und formatiere sie mit Umschalt+Alt+F.
  3. Importiere die CSV-Datei. Die Liste zeigt drei neue Besuche, die Dauer der Telefonate ist durch das Interface von Seite 5 mit 15 vorbelegt.
  4. Ändere in der CSV-Datei ein Datum auf 03.03.2025 und importiere erneut. Du bekommst die Fehlermeldung mit Zeilennummer, und es wurde kein einziger Besuch angelegt, weil der Fehler die ganze Transaktion zurückrollt.
  5. Ändere eine Besuchsart auf 0 (vor Ort). Der Import scheitert an der Prüfung aus CheckVisit, 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.
  6. 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.
  7. 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::UTF8 am 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.

DotNet-Code, der in die Cloud muss?Wir stellen ihn mit dir um.

Erstgespräch vereinbaren

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

Fehler melden

Anliegen

Du hast etwas gefunden, das nicht stimmt oder veraltet ist? Schreib uns, was dir aufgefallen ist. Wir prüfen jede Meldung.

Lieber sprechen? Ruf an: +49 176 46 733 299