Edit

Share via

Adding and accessing resources in Business Central extensions

APPLIES TO: Business Central 2024 release wave 2, update 25.2 and later

This article describes how to package and use resources with your extensions. Resources are arbitrary files that can be included with your extension and accessed at runtime. For example, you can include sample data, images, or any other file that's used by your extension. Resources can only be accessed within the extension that includes them; it isn't possible for extensions to access resources that are packaged with other extensions.

Specifying resource folders

To package resources in an extension, you must declare which folders within your project contain resources to be packaged in the extension's manifest file (app.json). To do this, add the "resourceFolders" property to the manifest file. For example, the following code snippet specifies that files within the Resources folder should be packaged as resources:

"resourceFolders": ["Resources"]

You can specify multiple folders:

"resourceFolders": ["SampleImages", "ConfigurationFiles"]

Resource folders can contain subfolders as well. Files within these subfolders are also included as resources in the extension.

Accessing the resources from AL

Resources can be accessed from AL code at runtime. There are several methods that can be used to interact with resources:

Method Description
NavApp.GetResource(ResourceName: Text; var ResourceStream: Instream; (Optional) Encoding: TextEncoding) Used to read the content of resource files at runtime.
NavApp.GetResourceAsText(ResourceName: Text; (Optional) Encoding: TextEncoding): Text Used to read the content of resource files directly into a Text object.
NavApp.GetResourceAsJson(ResourceName: Text; (Optional) Encoding: TextEncoding): JsonObject Used to read the content of resource files directly into a JsonObject.
NavApp.ListResources((Optional) Filter: Text) Used to list available resources in an extension.

The ResourceName of a resource is the path to the resource from the folder specified in the resourceFolders attribute of the app.json file. For example, if you had the following project structure:

MyApp
    Resources/
        Images/
            SampleImage1.png
            SampleImage2.png
        Templates/
            Template1.txt
            Template2.png

You can access the content of the Template1.txt resource file with the following code:

procedure UsingResources()
var
    resourceStream: Instream;
    content: Text;
begin
    NavApp.GetResource('Templates/Template1.txt', resourceStream, TextEncoding::UTF8);
    resourceStream.Read(content);
end;

NavApp.ListResources can be used to iterate over a collection of resources. The Filter parameter of this method allows you to optionally specify what types of resources to list. If a filter is provided, only resources matching the pattern in the filter are listed. The filter can contain wildcards. For example, with the same project structure as before:

NavApp.ListResources(); // Will return ["Images/SampleImage1.png", "Images/SampleImage2.png", "Templates/Template1.txt", "Templates/Template2.png"]
NavApp.ListResources("Images") // Will return ["Images/SampleImage1.png", "Images/SampleImage2.png"]
NavApp.ListResources("*.png"); // Will return ["Images/SampleImage1.png", "Images/SampleImage2.png", "Templates/Template2.png"]

Limits on resources

The following limits are enforced on the resources that you can include in an extension:

Limit Value
Maximum size of any single resource file 16 MB
Maximum size of the total of all resource files 256 MB
Maximum number of resource files in an extension 256 files

These limits are subject to change in the future.

Limiting access to resources

An extension is only able to access its own resources. This means that if two apps declare resources with the same name, they're only able to access their own versions of the resource.

Resources are treated like code with regard to the Resource exposure policy setting for the application. If an application has allowDownloadingSource set to true, then any resources included with the extension is packaged into the .app file that is downloaded.

Get started with AL
Publishing and installing extensions
Resource exposure policy setting