If you’ve spent any time in AL development, you’ve probably reinvented a wheel or two. Written a quick parser for a date string, wrestled with URL encoding for an API call, or built a little helper to compare dates safely. The "Type Helper" Codeunit (ID 10, namespace System.Reflection) exists specifically to handle this kind of utility work—and it’s surprisingly comprehensive.

This post walks through useful procedures grouped by category, with practical AL examples for each.

You can find the full code for the example on GitHub.

What Is the Type Helper Codeunit?

"Type Helper" is a base application Codeunit that provides a broad set of utility methods covering:

• String and character checks
• Date, time, and timezone formatting and conversion
• URL/HTML encoding
• Record and field reflection
• Option field helpers
• Stream reading
• Amount/currency format strings

It’s not flashy, but it saves real time. Before writing your own utility procedure, check here first.

String Utilities

IsNumeric

procedure IsNumeric(Text: Text): Boolean

Returns true if a text value can be parsed as a Decimal.

var
    TypeHelper: Codeunit "Type Helper";
    Result1, Result2: Boolean;
    Value1, Value2: Text;
begin
    Value1 := '42.5';
    Value2 := 'hello';

    Result1 := TypeHelper.IsNumeric(Value1);   // true
    Result2 := TypeHelper.IsNumeric(Value2);  // false
    Message('IsNumeric(''' + Value1 + '''): %1\IsNumeric(''' + Value2 + '''): %2', Result1, Result2);
end;

Useful for validating user input or imported data before calling Evaluate.

IsPhoneNumber

procedure IsPhoneNumber(Input: Text): Boolean

Validates that a string contains only digits, spaces, parentheses, dashes, and +. It uses a regex under the hood.

var
    TypeHelper: Codeunit "Type Helper";
    Value1, Value2: Text;
begin
    Value1 := '+1 (555) 123-4567';
    Value2 := 'not-a-phone';

    Message('IsPhoneNumber(''' + Value1 + '''): %1\IsPhoneNumber(''' + Value2 + '''): %2',
        TypeHelper.IsPhoneNumber(Value1), TypeHelper.IsPhoneNumber(Value2));
end;

IsLatinLetter / IsDigit / IsUpper

procedure IsLatinLetter(ch: Char): Boolean
procedure IsDigit(ch: Char): Boolean
procedure IsUpper(ch: Char): Boolean

Character-level checks. Handy when parsing text character by character.

var
    TypeHelper: Codeunit "Type Helper";
    ch: Char;
begin
    ch := 'A';
    if TypeHelper.IsLatinLetter(ch) then
        Message('It is a letter.');

    ch := '3';
    if TypeHelper.IsDigit(ch) then
        Message('It is a digit.');
end;

TextDistance

procedure TextDistance(Text1: Text; Text2: Text): Integer

Calculates the Levenshtein distance (I didn’t know what this was before digging into this Codeunit) between two strings—the minimum number of single-character edits to get from one string to the other. Useful for fuzzy matching or detecting near-duplicates.

var
    TypeHelper: Codeunit "Type Helper";
    Distance: Integer;
begin
    Distance := TypeHelper.TextDistance('Business', 'Busines');  // 1
    Distance := TypeHelper.TextDistance('Hello', 'World');       // 4
end;

Note: Strings are limited to ~1024 characters.

NewLine / CRLFSeparator / LFSeparator

procedure NewLine(): Text
procedure CRLFSeparator(): Text[2]
procedure LFSeparator(): Text[1]

Returns the system newline string, a carriage-return + line-feed pair, or just a line feed. Avoid hardcoding character codes.

var
    TypeHelper: Codeunit "Type Helper";
    Msg: Text;
begin
    Msg := 'Line one' + TypeHelper.CRLFSeparator() + 'Line two';
    Message(Msg);
end;

Date and Time

FormatDateWithCurrentCulture

procedure FormatDateWithCurrentCulture(DateToFormat: Date): Text

The simplest way to format a Date using the current user’s locale. Great for displaying dates in messages or reports.

var
    TypeHelper: Codeunit "Type Helper";
    FormattedDate: Text;
begin
    FormattedDate := TypeHelper.FormatDateWithCurrentCulture(WorkDate());
    Message(FormattedDate);
end;

FormatDate (overloads)

procedure FormatDate(DateToFormat: Date; LanguageId: Integer): Text
procedure FormatDate(DateToFormat: Date; Format: Text; CultureName: Text): Text

Two overloads let you format with a specific language ID or a custom format string and culture name.

var
    TypeHelper: Codeunit "Type Helper";
begin
    // Format using a language ID (e.g., 1033 = en-US)
    Message(TypeHelper.FormatDate(WorkDate(), 1033));

    // Format using a .NET format string and culture name
    Message(TypeHelper.FormatDate(WorkDate(), 'MMMM dd, yyyy', 'en-US'));
end;

CompareDateTime

procedure CompareDateTime(DateTimeA: DateTime; DateTimeB: DateTime): Integer

Compares two DateTime values with a built-in millisecond-level tolerance that accounts for SQL precision rounding. Returns 1, 0, or -1.

var
    TypeHelper: Codeunit "Type Helper";
    StartDateTime: DateTime;
    EndDateTime: DateTime;
    Result: Integer;
begin
    StartDateTime := CreateDateTime(WorkDate(), 080000T);
    EndDateTime := CreateDateTime(WorkDate(), 170000T);

    Result := TypeHelper.CompareDateTime(StartDateTime, EndDateTime);
    Message('CompareDateTime result: %1 (negative means first is earlier)', Result);
end;

Don’t compare DateTime values directly with = when they come from the database—use this instead.

AddHoursToDateTime

procedure AddHoursToDateTime(SourceDateTime: DateTime; NoOfHours: Integer): DateTime

Adds a number of hours to a DateTime value.

var
    TypeHelper: Codeunit "Type Helper";
    NewDT: DateTime;
begin
    NewDT := TypeHelper.AddHoursToDateTime(CurrentDateTime, 8);
end;

GetHMSFromTime

procedure GetHMSFromTime(var Hour: Integer; var Minute: Integer; var Second: Integer; TimeSource: Time)

Breaks a Time value into its hour, minute, and second components.

var
    TypeHelper: Codeunit "Type Helper";
    H: Integer;
    M: Integer;
    S: Integer;
    CurrentTime: Time;
begin
    CurrentTime := Time;
    TypeHelper.GetHMSFromTime(H, M, S, CurrentTime);
    Message('Current time -> H:%1 M:%2 S:%3', H, M, S);
end;

EvaluateUnixTimestamp

procedure EvaluateUnixTimestamp(Timestamp: BigInteger): DateTime

Converts a Unix epoch timestamp (BigInteger, seconds since Jan 1 1970) to a DateTime, adjusting for the user’s timezone offset.

var
    TypeHelper: Codeunit "Type Helper";
    ResultDT: DateTime;
    TimeStamp: BigInteger;
begin
    TimeStamp := 1740657600;
    ResultDT := TypeHelper.EvaluateUnixTimestamp(TimeStamp);
    Message('EvaluateUnixTimestamp(' + Format(TimeStamp, 9) + '): %1', ResultDT);
end;

GetCurrUTCDateTime / GetCurrUTCDateTimeAsText / GetCurrUTCDateTimeISO8601

procedure GetCurrUTCDateTime(): DateTime
procedure GetCurrUTCDateTimeAsText(): Text
procedure GetCurrUTCDateTimeISO8601(): Text

Three shortcuts for getting the current UTC time in different formats.

var
    TypeHelper: Codeunit "Type Helper";
begin
    // DateTime value
    MyDT := TypeHelper.GetCurrUTCDateTime();

    // RFC 1123 text: "Thu, 27 Feb 2026 14:30:00 GMT"
    MyText := TypeHelper.GetCurrUTCDateTimeAsText();

    // ISO 8601: "2026-02-27T14:30:00Z"
    MyText := TypeHelper.GetCurrUTCDateTimeISO8601();
end;

GetCurrUTCDateTimeISO8601 is especially useful when building API payloads.

Timezone Conversions

GetUserTimezoneOffset

procedure GetUserTimezoneOffset(var Duration: Duration): Boolean

Returns the current user’s UTC offset as a Duration. Returns false if the user has no timezone set.

var
    TypeHelper: Codeunit "Type Helper";
    Offset: Duration;
begin
    if TypeHelper.GetUserTimezoneOffset(Offset) then
        Message('Offset in ms: %1', Offset);
end;

Type Conversion and Formatting

Evaluate

procedure Evaluate(var Variable: Variant; String: Text; Format: Text; CultureName: Text): Boolean

The general-purpose type evaluator. Pass in a Variant of the target type, a text string, an optional format, and an optional culture name.

var
    TypeHelper: Codeunit "Type Helper";
    Value: Variant;
    ParsedDate: Date;
    Ok: Boolean;
begin
    ParsedDate := 0D;
    Value := ParsedDate;
    Ok := TypeHelper.Evaluate(Value, '02/27/2026', 'MM/dd/yyyy', 'en-US');
    if Ok then
        ParsedDate := Value;
end;

FormatDecimal

procedure FormatDecimal(Decimal: Decimal; DataFormat: Text; DataFormattingCulture: Text): Text

Formats a Decimal with a .NET format string and culture name. Useful for building API payloads or localized output.

var
    TypeHelper: Codeunit "Type Helper";
    Formatted: Text;
begin
    Formatted := TypeHelper.FormatDecimal(1234.56, 'N2', 'en-US');  // "1,234.56"
    Formatted := TypeHelper.FormatDecimal(1234.56, 'N2', 'de-DE');  // "1.234,56"
end;

IntToHex

procedure IntToHex(IntValue: Integer): Text

Converts an integer to its hexadecimal representation.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message(TypeHelper.IntToHex(255));   // "FF"
    Message(TypeHelper.IntToHex(4096));  // "1000"
end;

Maximum / Minimum

procedure Maximum(Value1: Decimal; Value2: Decimal): Decimal
procedure Minimum(Value1: Decimal; Value2: Decimal): Decimal

Returns the larger or smaller of two Decimal values.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message('%1', TypeHelper.Maximum(10.0, 25.5));  // 25.5
    Message('%1', TypeHelper.Minimum(10.0, 25.5));  // 10
end;

Web and URL Encoding

These are essential any time you’re calling external APIs or generating web links in AL.

UrlEncode / UrlDecode

procedure UrlEncode(var Value: Text): Text
procedure UrlEncode(var Value: SecretText): SecretText
procedure UrlDecode(var Value: Text): Text

var
    TypeHelper: Codeunit "Type Helper";
    Encoded: Text;
begin
    Encoded := 'search term with spaces';
    TypeHelper.UrlEncode(Encoded);
    Message(Encoded);  // "search+term+with+spaces"
end;

There’s also an overload that accepts and returns SecretText for encoding credentials without exposing the raw value.

HtmlEncode / HtmlDecode

procedure HtmlEncode(var Value: Text): Text
procedure HtmlDecode(var Value: Text): Text

Encodes characters like <, >, & for safe HTML output, or decodes them back.

var
    TypeHelper: Codeunit "Type Helper";
    SafeHtml: Text;
begin
    SafeHtml := '<script>alert("xss")</script>';
    TypeHelper.HtmlEncode(SafeHtml);
    Message(SafeHtml);  // "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
end;

UriEscapeDataString / UriGetAuthority

procedure UriEscapeDataString(Value: Text): Text
procedure UriGetAuthority(Value: Text): Text

UriEscapeDataString percent-encodes a value (RFC 3986). UriGetAuthority extracts the scheme + host from a URL.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message(TypeHelper.UriEscapeDataString('hello world'));  // "hello%20world"
    Message(TypeHelper.UriGetAuthority('https://api.example.com/v1/items'));
    // "https://api.example.com"
end;

Option Field Helpers

GetOptionNo

procedure GetOptionNo(Value: Text; OptionString: Text): Integer

Looks up the integer index of an option value string within an option set string. Returns -1 if not found.

var
    TypeHelper: Codeunit "Type Helper";
    Idx: Integer;
begin
    Idx := TypeHelper.GetOptionNo('Posted', 'Open,Released,Posted,Canceled');
    // Returns 2
end;

GetNumberOfOptions

procedure GetNumberOfOptions(OptionString: Text): Integer

Counts how many comma-separated options are in an option string.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message('%1', TypeHelper.GetNumberOfOptions('Open,Released,Posted'));  // 2 (counts commas)
end;

Watch out: this counts commas, so it returns n - 1 for n options. Adjust accordingly.

Record and Field Reflection

GetField / GetFieldLength

procedure GetField(TableNo: Integer; FieldNo: Integer; var Field: Record Field): Boolean
procedure GetFieldLength(TableNo: Integer; FieldNo: Integer): Integer

GetField retrieves field metadata from the Field virtual table and returns false if the field doesn’t exist or is obsolete (ObsoleteState = Removed). GetFieldLength returns the declared length of a text field.

var
    TypeHelper: Codeunit "Type Helper";
    FieldRec: Record Field;
begin
    if TypeHelper.GetField(Database::Customer, Customer.FieldNo(Name), FieldRec) then
        Message('Max length: %1', TypeHelper.GetFieldLength(Database::Customer, Customer.FieldNo(Name)));
end;

SortRecordRef

procedure SortRecordRef(var RecRef: RecordRef; CommaSeparatedFieldsToSort: Text; Ascending: Boolean)

Applies a sort order to a RecordRef using a comma-separated list of field names.

var
    TypeHelper: Codeunit "Type Helper";
    RecRef: RecordRef;
begin
    RecRef.Open(Database::Customer);
    TypeHelper.SortRecordRef(RecRef, '"No."', true);  // ascending by No.
    if RecRef.FindSet() then
        repeat
            // ...
        until RecRef.Next() = 0;
end;

GetKeyAsString

procedure GetKeyAsString(RecordVariant: Variant; KeyIndex: Integer): Text

Returns the key fields of a record as a comma-separated string. Useful for logging or telemetry.

var
    Cust: Record Customer;
    TypeHelper: Codeunit "Type Helper";
    KeyText: Text;
begin
    if Cust.FindFirst() then begin
        KeyText := TypeHelper.GetKeyAsString(Cust, 1);
        Message('GetKeyAsString: %1', KeyText);
    end;
end;

Stream Reading

ReadAsTextWithSeparator / TryReadAsTextWithSeparator

procedure ReadAsTextWithSeparator(InStream: InStream; LineSeparator: Text): Text
[TryFunction]
procedure TryReadAsTextWithSeparator(InStream: InStream; LineSeparator: Text; var Content: Text): Boolean

Reads an InStream into a Text value, using a specified line separator. TryReadAsTextWithSeparator wraps the call in a [TryFunction] for error-safe reading.

var
    TempBlob: Codeunit "Temp Blob";
    TypeHelper: Codeunit "Type Helper";
    FileContent: Text;
    IStream: InStream;
    OStream: OutStream;
begin
    TempBlob.CreateOutStream(OStream);
    OStream.WriteText('Line 1');
    OStream.WriteText(TypeHelper.CRLFSeparator());
    OStream.WriteText('Line 2');
    OStream.WriteText(TypeHelper.CRLFSeparator());
    OStream.WriteText('Line 3');

    TempBlob.CreateInStream(IStream);
    FileContent := TypeHelper.ReadAsTextWithSeparator(IStream, TypeHelper.CRLFSeparator());
    Message('ReadAsTextWithSeparator:\%1', FileContent);
end;

Amount and Currency Formatting

GetAmountFormatLCYWithUserLocale

procedure GetAmountFormatLCYWithUserLocale(): Text
procedure GetAmountFormatLCYWithUserLocale(DecimalPlaces: Integer): Text

Returns a BC format string for displaying amounts in the local currency, formatted for the current user’s locale. Pass an optional decimal places count.

var
    TypeHelper: Codeunit "Type Helper";
    AmtFormat: Text;
begin
    AmtFormat := TypeHelper.GetAmountFormatLCYWithUserLocale();
    Message(Format(1234.56, 0, AmtFormat));
end;

GetXMLAmountFormatWithTwoDecimalPlaces / GetXMLDateFormat

procedure GetXMLAmountFormatWithTwoDecimalPlaces(): Text
procedure GetXMLDateFormat(): Text

Return BC format strings suitable for XML output—two decimal places for amounts and the standard XML date format.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message(Format(Today, 0, TypeHelper.GetXMLDateFormat()));        // e.g., "2026-02-27"
    Message(Format(12345.6, 0, TypeHelper.GetXMLAmountFormatWithTwoDecimalPlaces()));  // "12345.60"
end;

Wrapping Up

The "Type Helper" codeunit is one of the most useful utility libraries in BC’s base application—and one of the most underused. Before writing your own string parser, encoding helper, or date workaround, it’s worth skimming the procedure list. There’s a good chance something here already does exactly what you need.

A few things to keep in mind:

• LanguageIDToCultureName and GetCultureName are obsolete as of v26—Use Codeunit 43 Language instead.
• UrlEncodeSecret is obsolete as of v27—Use the SecretText overload of UrlEncode instead.

Learn more: Codeunit “Type Helper” – Microsoft Learn

Note: The code and information discussed in this article are for informational and demonstration purposes only. Always test in a sandbox environment before deploying to production. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2.

If you’re building a Business Central extension, you probably already benefit from the built-in telemetry that the platform sends to Azure Application Insights—long running AL methods, long running operations (SQL), web service calls, report generation times, and more. But what about the things that are specific to your extension? Maybe you need to know when a critical integration call fails, how often users trigger a particular workflow, or which branch of a complex calculation is being hit in production.

That’s where custom telemetry events come in. With a single LogMessage call in your AL code, you can send your own trace signals to Azure Application Insights, giving you visibility into exactly what your extension is doing in the real world. This article walks through how it works, when to use it, and the recommended approach that will save you headaches down the road.

You can find the full code for the example on GitHub.

Telemetry vs. Traditional Event Logging

Before exploring the how, it’s worth understanding the distinction. Traditional event logging—like writing to the Windows event log on a Business Central Server instance—focuses on infrastructure: server errors, deployment issues, performance counters. Telemetry is different. It’s about collecting data on what users are doing inside the application and how your code is behaving in production environments.

Azure Application Insights is the recommended destination for telemetry in Business Central. It works for both online and on-premises deployments, and it gives you powerful querying capabilities through Kusto Query Language (KQL) as well as some other community driven tools such as Waldo’s BC Telemetry Buddy.

Where Telemetry Gets Sent

When you emit a custom telemetry event from your extension, there are two possible destinations:

• Extension publisher’s Application Insights — the Azure Application Insights resource configured in your extension’s app.json file.
• Environment Application Insights — the resource configured by the admin on the Business Central environment itself.

You control which destination receives your events through the TelemetryScope parameter:

• TelemetryScope::ExtensionPublisher — sends the event only to the Application Insights resource defined in your extension’s app.json.
• TelemetryScope::All — sends the event to both the extension’s resource and the environment’s resource.

This scoping is useful. If you’re an ISV, you might want some internal diagnostics to stay in your own Application Insights resource (ExtensionPublisher), while other events—like feature usage or error conditions that an admin should know about—go to both destinations (All).

It’s worth noting that having an Application Insights resource configured in your app.json is not required to use custom telemetry. If you only use TelemetryScope::All, the events will be sent to the environment’s resource (if one is configured).

The LogMessage Method

The core of custom telemetry is Session.LogMessage. There are two overloads—one that accepts a Dictionary of custom dimensions, and one that lets you pass dimension name/value pairs directly as parameters.

Dictionary overload:

Session.LogMessage(
    EventId: String,
    Message: String,
    Verbosity: Verbosity,
    DataClassification: DataClassification,
    TelemetryScope: TelemetryScope,
    CustomDimensions: Dictionary of [Text, Text]
)

Dimension overload (up to two dimensions):

Session.LogMessage(
    EventId: String,
    Message: String,
    Verbosity: Verbosity,
    DataClassification: DataClassification,
    TelemetryScope: TelemetryScope,
    Dimension1: String, Value1: String
    [, Dimension2: String] [, Value2: String]
)

Both methods can be called from any AL object—Codeunits, pages, reports, triggers, or methods. Let’s break down the parameters.

Understanding the Parameters

A couple of these deserve extra emphasis:

• DataClassification: For privacy reasons, only events with DataClassification::SystemMetadata are sent to Azure Application Insights. If you use any other classification, the event won’t be transmitted. This is by design—it prevents customer data from accidentally leaking into telemetry resources.
• Verbosity: For on-premises deployments, the Diagnostic Trace Level setting on the Business Central Server instance controls which severity levels are sent. If the trace level is set to Warning, then Normal and Verbose signals won’t reach Application Insights.

A Practical Example

Let’s say your extension integrates with an external API and you want to log both successful calls and failures. Here’s how you might structure that:

codeunit 50100 "DVLPR API Integration"
{
    procedure CallExternalApi(Endpoint: Text): Boolean
    var
        Client: HttpClient;
        Response: HttpResponseMessage;
        Dimensions: Dictionary of [Text, Text];
        Success: Boolean;
    begin
        Success := Client.Get(Endpoint, Response);

        Dimensions.Add('Endpoint', Endpoint);
        Dimensions.Add('HttpStatusCode', Format(Response.HttpStatusCode()));
        Dimensions.Add('Success', Format(Success and Response.IsSuccessStatusCode()));

        if Success and Response.IsSuccessStatusCode() then begin
            LogMessage(
                'DVLPR-1001',
                'External API called successfully',
                Verbosity::Normal,
                DataClassification::SystemMetadata,
                TelemetryScope::ExtensionPublisher,
                Dimensions
            );
            exit(true);
        end;

        LogMessage(
            'DVLPR-1002',
            'External API call failed',
            Verbosity::Error,
            DataClassification::SystemMetadata,
            TelemetryScope::All,
            Dimensions
        );
        exit(false);
    end;
}

A few things to notice:

• The success event uses TelemetryScope::ExtensionPublisher because it’s routine operational data the ISV cares about.
• The failure event uses TelemetryScope::All because the environment admin might also want to know about failures.
• Each event has a unique EventId (DVLPR-1001 and DVLPR-1002), which makes it easy to find specific events in Application Insights.
• The Endpoint dimension is included in both calls so you can filter and group by endpoint in KQL queries.

For simpler scenarios, you can skip the dictionary and use the dimension overload:

LogMessage(
    'DVLPR-2001',
    'Order import completed',
    Verbosity::Normal,
    DataClassification::SystemMetadata,
    TelemetryScope::ExtensionPublisher,
    'OrderCount', Format(OrderCount),
    'DurationMs', Format(Duration)
);

This is convenient when you only need one or two dimensions.

What Shows Up in Application Insights

When your event arrives in Azure Application Insights, it lands in the traces table. The Message and Verbosity appear as general dimensions. Everything else appears as custom dimensions.

One important detail: Similar to EventIds, Business Central automatically prefixes your custom dimension keys with al. So if you define a dimension called OrderCount in your AL code, it appears as alOrderCount in Application Insights. Because of this, use PascalCasing for your dimension names—OrderCount, not order_count or order count. This keeps your custom dimensions consistent with how built-in Business Central telemetry dimensions are named.

You also get a set of default dimensions for free on every event, including:

• alObjectId / alObjectName / alObjectType — which object emitted the event.
• extensionName / extensionId / extensionVersion — which extension the event came from.
• environmentName / environmentType — which environment it happened in.
• companyName — which company was active.
• clientType — what type of client triggered the code (Web, Background, API, etc.).

These built-in dimensions are incredibly useful for filtering. You don’t need to add them yourself.

Recommended Approach

The Business Central team treats telemetry event definitions as an API—and you should too. Here are the key practices to follow:

• Use unique EventIds. Every LogMessage call in your code should have a distinct EventId. This makes it trivial to pinpoint where in the code a particular event was emitted. Use a prefix unique to your extension (e.g., DVLPR-, CONTOSO-).
• Follow the “Object ActionInPastTense” pattern for messages. Instead of "Calling API", write "External API called" or "Order import completed". This reads naturally in a KQL query ordered by timestamp. Consider including key dimension values in the message itself so you can scan events without opening custom dimensions every time.
• Don’t use spaces in dimension names. Spaces make KQL queries harder to write. Stick to PascalCase: OrderCount, not Order Count.
• Treat dimension changes as breaking changes. Once your extension is in production and people have built alerts or Power BI reports on your telemetry, renaming or removing a dimension will break their work. Add new dimensions freely, but be cautious about changing existing ones.
• Keep DataClassification as SystemMetadata. Events with any other classification won’t be sent. Review your LogMessage calls to make sure you’re not accidentally including personal or customer data in dimension values.
• Make events actionable. Before adding a telemetry event, ask yourself: “What can someone do with this information?” If the answer isn’t clear, reconsider whether the event is worth adding.
• Don’t over-instrument. Telemetry costs money (Application Insights charges by data volume) and adds overhead. Focus on events that provide diagnostic or usage value. High-frequency loops are not good candidates for telemetry.

Feature Telemetry Module

It’s worth mentioning the Feature Telemetry module from the System Application. This module provides a higher-level abstraction over Session.LogMessage and is particularly useful for tracking feature usage. Instead of calling LogMessage directly, you call FeatureTelemetry.LogUsage or FeatureTelemetry.LogError, and the module handles the event structure for you.

If your primary goal is tracking which features in your extension are being used (and which aren’t), the Feature Telemetry module is often a better fit than raw LogMessage calls. You can learn more about it in the Microsoft documentation on Using Feature telemetry.

Wrapping Up

Custom telemetry events give you a direct window into how your extension behaves in production. With LogMessage, you can emit targeted signals from anywhere in your AL code, control where those signals land through telemetry scoping, and attach rich custom dimensions that make analysis in Application Insights straightforward.

The investment is minimal—a handful of well-placed LogMessage calls—but the payoff is significant. You get real production diagnostics, usage patterns, and error tracking without needing access to the customer’s environment. Start with your most critical code paths (integrations, complex calculations, error handlers) and expand from there.

Learn more:

• Instrumenting an application for telemetry (Microsoft Learn)
• Creating custom telemetry events for Azure Application Insights (Microsoft Learn)
• Using Feature telemetry (Microsoft Learn)

Note: The code and information discussed in this article are for informational and demonstration purposes only. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online. Custom telemetry events via LogMessage are available from Business Central 2020 release wave 2 and later. Always test in a sandbox first.

If you’ve ever worked on a Business Central extension that needs to support multiple “flavors” of the same operation—different shipping providers, different document formats, different pricing strategies—you’ve probably felt the pain of tightly coupled code. Interfaces in AL solve that problem by letting you define a contract (a set of methods) and then swap implementations without touching the calling code.

Interfaces were introduced in Business Central 2020 release wave 1 and have quickly become an important pattern for building extensible, maintainable AL solutions. If you haven’t used them yet, this article walks through what they are, why they matter, and how to build with them.

You can find the full code for the example on GitHub.

What Is an Interface?

An interface is a named object that declares one or more procedure signatures—but contains no implementation. It defines what a Codeunit must do, not how it does it.

interface IDocumentValidator
{
    procedure Validate(var RecRef: RecordRef): Boolean;
}

Any Codeunit that claims to implement IDocumentValidator must provide a concrete body for Validate. The AL compiler enforces this at build time—if a method is missing, you get an error.

Key characteristics:

• An interface contains only procedure declarations (no variables, no triggers, no logic).
• It cannot be instantiated or called directly.
• It acts as a contract between the code that calls a behavior and the code that provides it.

Why You Should Care

• Loose coupling: Your calling code depends on the interface, not on a specific Codeunit. You can swap implementations without modifying callers.
• Extensibility without events: Partners and ISVs can add new behavior by implementing the interface and extending the enum—no event subscriptions needed.
• Polymorphism: You can declare a variable as an interface type and call methods on it. At runtime, the actual implementation executes based on which Codeunit was selected.
• Testability: You can create a “mock” Codeunit that implements the interface for testing purposes.

How It Works: The Three-Part Pattern

Interfaces in AL rely on three cooperating objects:

1. The interface – declares the method signatures.
2. One or more Codeunits – each implements the interface with concrete logic.
3. An enum – ties enum values to specific implementations.

This trio is the standard pattern. The enum is the dispatch mechanism. When you assign an enum value, Business Central knows which Codeunit to run.

Example: A Discount Calculator

Let’s say you want to support multiple discount strategies. Start with the interface:

interface IDiscountCalculator
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal;
}

Then create two implementations:

Codeunit 50100 "DVLPR Standard Discount" implements IDiscountCalculator
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal
    begin
        exit(SalesLine."Line Amount" * 0.05); // flat 5%
    end;
}

Codeunit 50101 "DVLPR Volume Discount" implements IDiscountCalculator
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal
    begin
        if SalesLine.Quantity >= 100 then
            exit(SalesLine."Line Amount" * 0.15)
        else
            exit(SalesLine."Line Amount" * 0.05);
    end;
}

Wire them up through an enum:

enum 50160 "DVLPR Discount Strategy" implements IDiscountCalculator
{
    Extensible = true;

    value(0; Standard)
    {
        Implementation = IDiscountCalculator = "DVLPR Standard Discount";
    }
    value(1; Volume)
    {
        Implementation = IDiscountCalculator = "DVLPR Volume Discount";
    }
}

Now your calling code never needs to know which strategy is active:

procedure ApplyDiscount(Strategy: Enum "DVLPR Discount Strategy"; var SalesLine: Record "Sales Line")
var
    Calculator: Interface IDiscountCalculator;
begin
    Calculator := Strategy;
    SalesLine."Line Discount Amount" := Calculator.CalculateDiscount(SalesLine);
end;

If a partner wants to add a “Loyalty” discount strategy later, they just create a new Codeunit that implements IDiscountCalculator, add an enumextension value, and they’re done. No modifications to your calling code.

Using Existing Interfaces in Business Central

Microsoft already ships several interfaces in the base application and system application. A practical way to get comfortable with interfaces is to implement one that already exists.

For example, the E-Document module defines an E-Document interface. To use it:

1. Find the interface: Use the AL Explorer in VS Code to browse available interfaces.
2. Create a Codeunit that implements the interface.
3. Use the “Implement Interface” quick action in VS Code—hover over the interface name and let the tooling generate empty stubs for all required methods.
4. Extend the corresponding enum with your new value and implementation mapping.

This is a great way to learn the pattern because the plumbing is already in place—you just supply the logic.

Snippet Support

VS Code has a built-in snippet for interfaces. Type tinterface in an AL file and the AL Language extension generates the basic structure for you. This is a quick way to scaffold a new interface and avoid syntax mistakes.

Implementing Multiple Interfaces

A single Codeunit can implement more than one interface:

Codeunit 50164 "DVLPR Multi Provider" implements IDiscountCalculator, IShippingProvider
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal
    begin
        // discount logic
    end;

    procedure GetShippingRate(Length: Decimal; Width: Decimal; Height: Decimal; Weight: Decimal): Decimal
    begin
        // shipping logic
    end;
}

Be careful with method name collisions. If two interfaces define a method with the same name and signature, the compiler expects a single implementation to satisfy both. If the signatures differ, you’ll get a compile error. The analyzer rules AL0587 and AL0675 help catch these situations.

Type Testing and Casting

Business Central supports type testing and casting operators for interface variables, which allows you to check at runtime whether an interface variable holds a specific implementation:

var
    Calculator: Interface IDiscountCalculator;
begin
    if Calculator is "DVLPR Volume Discount" then
        Message('Volume discount is active');
end;

This is useful when you need conditional logic based on the underlying implementation, though use it sparingly—heavy use of is checks can undermine the polymorphism that interfaces are meant to provide.

Lists and Dictionaries of Interfaces

Starting with Business Central 2025 release wave 1 (runtime 15.0), you can create List and Dictionary collections of interface types:

var    
    MyCircle: Codeunit Circle;
    MySquare: Codeunit Square;
    Shape: Interface IShape;
    Shapes: List of [Interface IShape];    
begin
    Shapes.Add(MyCircle);
    Shapes.Add(MySquare);

    foreach Shape in Shapes do
        Message('Area: %1', Shape.GetArea());
end;

This opens up patterns like maintaining a registry of handlers or processing a collection of implementations in sequence.

Extending Interfaces

Starting with Business Central 2024 release wave 2, interfaces support the extends keyword. This lets you create a new interface that inherits all methods from one or more existing interfaces and adds its own on top. It’s particularly useful for ISVs and partners who want to build on each other’s interfaces without modifying the originals.

The syntax looks like this:

interface IExtendedInterface extends IBaseInterface
{
    procedure AdditionalMethod();
}

Any Codeunit that implements the extended interface must provide concrete implementations for all methods—both those defined in the base interface(s) and any new methods declared in the extension.

A good real-world example is the "Price Calculation" interface in the base application. This interface is the backbone of the extensible pricing system in Business Central. It declares methods like Init, ApplyDiscount, ApplyPrice, GetLine, and others that a pricing handler must implement. The "Price Calculation Handler" enum maps each value to a Codeunit that implements the interface, which is how Business Central decides which pricing engine runs at runtime.

If you needed to extend this pattern—say you wanted a pricing handler that also supports contract-specific pricing—you could define a new interface that extends the original:

interface IContractPriceCalculation extends "Price Calculation"
{
    procedure SetContractNo(ContractNo: Code[20]);
    procedure GetContractDiscount(): Decimal;
}

A Codeunit implementing IContractPriceCalculation would need to provide all the methods from "Price Calculation" plus the two new ones. This means existing code that works with "Price Calculation" continues to work unchanged, while new code can take advantage of the extended contract.

You can also extend multiple interfaces at once:

interface ICombined extends IFirst, ISecond
{
    procedure CombinedMethod();
}

Codeunit 50160 DVLPRCombines implements ICombined
{
    // Must implement IFirst, ISecond, ICombined 
}

Gotchas and Recommended Approach

• Don’t add methods to published interfaces. Once your interface is in production, adding a method breaks every existing implementation. The AppSourceCop rule AS0066 catches this. Use interface extensions (BC 2024 wave 2+) or versioning instead.
• Keep interfaces small and focused. A few related methods per interface is better than one giant interface that tries to cover everything.
• Use meaningful names. Prefix with I (like IAddressProvider) to make interface types immediately recognizable.
• Be aware of circular references. Interfaces, enums, and implementing Codeunits can create circular dependency chains. Rule AL0852 flags this.
• Avoid naming conflicts with built-in procedures. Rule AL0616 catches this, but it’s easy to trip over.
• Document expected behavior. The interface definition alone tells the compiler what methods exist, but not how they should behave. Use XML documentation comments or a companion doc to describe expectations (pre/post conditions, expected error handling, etc.).
• Set Extensible = true on enums when you want partners to add implementations via enum extensions.

Wrapping Up

Interfaces are a powerful pattern available in AL today. They let you design systems where behavior can be extended and swapped without modifying existing code—a core requirement for any healthy extension ecosystem.

The pattern is straightforward: define an interface, implement it in Codeunits, wire it through an enum, and call it polymorphically. Once you see it in action, you’ll find yourself reaching for it any time you need pluggable behavior.

Learn more:

• Interfaces in AL (Microsoft Learn)
• Implement interfaces in Dynamics 365 Business Central (Training module)

You can find the full code for the example on GitHub.

Note: The code and information discussed in this article are for informational and demonstration purposes only. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online. Interfaces are available from Business Central 2020 release wave 1 and later. Always test in a sandbox first.