All your Base64 are belong to AL

In this video, I look at how to use the base64 codeunit to transfer data in and out of Microsoft Dynamics 365 Business Central.

https://www.youtube.com/watch?v=e7y98biSCiU

Documentation for the Base64 Codeunit can be found here:

https://github.com/microsoft/ALAppExtensions/tree/master/Modules/System/Base64%20Convert

In this video, Erik explores how to move data in and out of Business Central using Base64 encoding — covering conversions between binary blob data, Base64 text strings, and JavaScript control add-ins. He demonstrates the full round-trip: taking a Base64 string, storing it as binary in a Blob field, then reading it back out and displaying it as an image via JavaScript.

Why Base64 Matters

Base64 encoding has been around for a long time, and one of the most common places you’ll encounter it — even if you don’t realize it — is in email. The email protocol is very old and, at its core, operates on 7-bit pure text. So how do you send a binary attachment or fancy HTML images? Through Base64 encoding. The encoded data fits within that 7-bit limitation, allowing binary content to be transported as text.

In Business Central, Base64 is the key to crossing barriers between binary data and text-based interfaces like web services, JavaScript control add-ins, and APIs. You can only expose primitive data types (like text) through web services — you can’t expose a stream directly. Base64 gives you a way to encode binary data as text, pass it across that barrier, and decode it on the other side.

The Demo Setup

Erik starts with a table that has a Blob field and a Base64 text field, along with a JavaScript control add-in for rendering HTML and images:

table 58400 "base64 Blob Demo"
{
    fields
    {
        field(1; PKEY; Integer)
        {

        }
        field(2; BLOB; Blob)
        {
            Subtype = Bitmap;
        }
        field(3; base64; Text[2000])
        {

        }
    }
    keys
    {
        key(PK; PKEY)
        { }
    }
}

The JavaScript control add-in is defined to support rendering HTML and adding images:

controladdin HTML
{
    StartupScript = 'startup.js';
    Scripts = 'scripts.js';
    HorizontalStretch = true;
    VerticalStretch = true;
    RequestedHeight = 400;
    event ControlReady();
    procedure Render(HTML: Text);
    procedure AddImage(b64txt: Text);
}

Converting Base64 to Binary (From Base64)

The first step is taking a Base64 string and converting it into binary data stored in a Blob field. In the page’s OnValidate trigger for the Base64 field, Erik uses the built-in "Base64 Convert" codeunit:

trigger OnValidate()
var
    convert: Codeunit "Base64 Convert";
    OutS: OutStream;
    InS: InStream;
begin
    Rec.BLOB.CreateOutStream(OutS);
    convert.FromBase64(Rec.base64, OutS);
    Rec.CalcFields(Blob);
    Rec.Blob.CreateInStream(InS);
    CurrPage.HTML.AddImage(convert.ToBase64(InS));
end;

The key points here:

  • To write data into a Blob, you need an OutStream — create it with CreateOutStream
  • FromBase64 takes the Base64 text string and writes the decoded binary data into the OutStream
  • To read data from a Blob, you need an InStream — create it with CreateInStream (after calling CalcFields)
  • ToBase64 reads from the InStream and returns a Base64-encoded text string

Converting Binary to Base64 (To Base64)

The second half of the round-trip reads the binary data back from the Blob field, converts it to Base64, and passes it to the JavaScript control add-in to display as an image. This demonstrates crossing the barrier in the other direction — from binary back to text.

A practical real-world example Erik mentions: exposing a web service where a caller supplies an invoice number, Business Central runs a report to PDF (which goes into a stream), converts that stream to a Base64 string, and returns it through the web service. The caller then decodes the Base64 to get the PDF file.

The JavaScript Side

On the JavaScript side, there are two approaches shown for handling Base64 data. The first is the practical approach for images — using an inline data URI:

function AddImage(b64txt)
{
    var image = new Image();
    image.src = 'data:image/png;base64,' + b64txt;
    HTMLContainer.appendChild(image);
}

HTML supports inline images where you supply the image data directly as a Base64 string using the data: URI scheme. This avoids the complexity of manually decoding the PNG format, creating a canvas, and drawing pixels.

The second approach demonstrates working with raw binary data in JavaScript, useful when you’re not dealing with images:

function SomethingBinary(b64txt)
{
    var raw = window.atob(b64txt);
    var len = raw.length;
    var a = new Uint8Array(new ArrayBuffer(len));
    for(var i = 0; i < len; i++)
    {
        a[i] = raw.charCodeAt(i);
    }
}

Here, window.atob() (ASCII to Binary) decodes the Base64 string, and the data is then placed into a Uint8Array backed by an ArrayBuffer — the closest thing JavaScript has to raw binary data representation.

A Note on Version 17 and the Explicit Rec Prefix

Erik notes that this demo runs on Business Central version 17, which introduced warnings about the implicit with statement. In earlier versions, you could reference fields directly without the Rec. prefix. Starting in version 17, Microsoft began encouraging explicit references (e.g., Rec.BLOB instead of just BLOB) to avoid ambiguity about whether you're referencing a field on the record or a function supplied by an extension. In version 17 it's optional with warnings; in later versions it becomes an error.

The Full Round-Trip Summary

Here's what happens in the demo end-to-end:

  1. A Base64 string is typed into the text field (simulating data received from an external source like a web service)
  2. The Base64 string is decoded and stored as binary data in the Blob field using FromBase64 and an OutStream
  3. The binary data is read back from the Blob field using an InStream and converted back to Base64 using ToBase64
  4. The Base64 string is passed to JavaScript, which renders it as an inline image on the page

The mystery Base64 data in the demo? It's a small PNG image of an "X" — as Erik reveals when the image renders on screen.

Conclusion

Base64 is the essential bridge for moving binary data across text-only boundaries in Business Central. Whether you're receiving files from web services, returning reports as PDFs through APIs, or passing image data to JavaScript control add-ins, the "Base64 Convert" codeunit (with its FromBase64 and ToBase64 functions) makes it straightforward. The underlying implementation is straight .NET, making it lightning fast — Erik reports moving megabytes of data through Base64 encoding with no performance issues. It's a robust, reliable pattern you'll use repeatedly when integrating Business Central with external systems.

Picture of hougaard

hougaard