Hidden Gems in the System Application: UriBuilder

Without access to the full DotNet platform, we’re limited to the fraction of DotNet that has been wrapped, packaged and made available in System Application. Discoverability is quite low, so I’m going to highlight different codeunits. In this video, it’s the Uri functionality. Check out the video:

https://youtu.be/-OVCZUmyE9Q

In this video, Erik explores the URI and URI Builder codeunits available in the Business Central System Application — a hidden gem that provides .NET-style URI manipulation directly in AL code without needing direct .NET interop.

Why System App Hidden Gems Matter

When Business Central moved to the cloud, developers lost the ability to work with .NET directly. Microsoft’s servers don’t allow arbitrary .NET access, which is understandable from a security and hosting perspective. However, over the last seven years, Microsoft has been adding wrappers around various .NET classes into the System Application. Some of these have even been contributed by the community.

The problem? Discoverability is extremely low. Most developers don’t know what’s available in the System App. This video is part of a series aimed at surfacing these useful tools.

Understanding URIs vs URLs

Before diving into the code, it’s worth clarifying the difference between a URL and a URI. A URL (Universal Resource Locator) is something we all recognize:

https://hogarth.com/page/subfolder/test.html?param=3

A URI (Universal Resource Identifier) is a superset of URLs. The “I” means it can represent any protocol — not just HTTP. For example, an application like SolidWorks could define its own scheme: solidworks://some/resource. When working with web services and integrations, you constantly need to build, parse, and manipulate these identifiers.

The URI Builder Codeunit

The System App includes a codeunit called “Uri Builder” that wraps the .NET System.UriBuilder class. Here’s how you can use it to construct a URI programmatically:

var
    UriBuilder: Codeunit "Uri Builder";
    Uri: Codeunit Uri;
begin
    UriBuilder.Init('https://localhost');
    UriBuilder.SetScheme('https');
    UriBuilder.SetHost('hogarth.com');
    UriBuilder.SetPath('page/subpage/test.html');
    UriBuilder.SetQuery('param=123¶m2=hello¶m3=Peter');
    UriBuilder.GetUri(Uri);
    Message(Uri.GetAbsoluteUri());
end;

Important: You Must Initialize with a Valid URI

One gotcha Erik discovered during his live exploration: you can’t start with a blank initialization. The underlying .NET UriBuilder needs a valid URI to start from. Calling SetScheme on an uninitialized builder throws an error: “A .NET variable has not been instantiated.”

The solution is to initialize with a minimal valid URI like https://localhost, and then override the individual components (scheme, host, path, etc.) as needed.

Extracting Query Parameters

The real power shines when you need to extract information from a URI you’ve received — for example, from a web service callback or an external system. Rather than doing manual string splitting, you can use the builder’s GetQueryParameter method:

var
    UriBuilder: Codeunit "Uri Builder";
    Uri: Codeunit Uri;
    ParamValues: List of [Text];
    ParamValue: Text;
begin
    UriBuilder.Init('https://hogarth.com/page/subpage/test.html?param=123¶m2=hello¶m3=Peter');
    UriBuilder.GetQueryParameter('param2', ParamValues);
    ParamValue := ParamValues.Get(1);
    Message(ParamValue); // Outputs: hello
end;

Note that GetQueryParameter returns a List of [Text] rather than a single text value. This is because the URI specification allows multiple values for the same parameter name (e.g., ?color=red&color=blue), so the API needs to handle that case.

Additional Builder Methods

The URI Builder codeunit exposes several other useful methods:

  • SetPort — useful when working with web services on non-standard ports
  • SetFragment — for setting the hash/anchor portion of a URI
  • AddQueryParameter — adds additional query parameters to the existing query string
  • AddQueryFlag — adds a flag (parameter without a value) to the query string
  • AddODataQueryParameter — specifically designed for OData query syntax

The Uri Codeunit

Alongside the builder, there’s also a standalone “Uri” codeunit that provides methods like:

  • GetAbsoluteUri — returns the full URI as text
  • GetSegments — breaks the URI path into segments
  • IsWellFormedUriString — validates whether a string is a proper URI
  • EscapeDataString / UnescapeDataString — for URL encoding and decoding
  • IsBaseOf — compares whether one URI is a base of another

Behind the Scenes

If you look at the System App source code, you’ll find a “Uri Builder Implementation” codeunit that contains the actual .NET interop calls. It’s simply wrapping the System.UriBuilder class from .NET — but doing so in a way that’s safe and permitted in the Business Central cloud environment.

Conclusion

The URI Builder in the System Application is a practical tool for anyone working with web services, API integrations, or any scenario that involves constructing or parsing URIs. While you could achieve similar results with text splitting and concatenation, the builder provides a cleaner, more reliable approach — especially for extracting query parameters from complex URLs. It’s one of many hidden gems in the System App that developers should be aware of to avoid reinventing the wheel.

Picture of hougaard

hougaard