{"title":"Adding and accessing resources in Business Central extensions","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-app-resources/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-app-resources, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-app-resources","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Describes how to package, share, and access resources, such as sample data, images, and schemas, across Business Central extensions.","date":"2026-08-25","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Adding and accessing resources in Business Central extensions","slug":"adding-and-accessing-resources-in-business-central-extensions","at":0,"chars":10597},{"level":2,"title":"Specifying resource folders","slug":"specifying-resource-folders","at":667,"chars":1087},{"level":2,"title":"Accessing the resources from AL","slug":"accessing-the-resources-from-al","at":1754,"chars":2535},{"level":2,"title":"Sharing resources with other apps","slug":"sharing-resources-with-other-apps","at":4289,"chars":4744},{"level":3,"title":"Access another app's public resources from AL","slug":"access-another-apps-public-resources-from-al","at":5540,"chars":3493},{"level":2,"title":"Limits on resources","slug":"limits-on-resources","at":9033,"chars":499},{"level":2,"title":"Limiting access to resources","slug":"limiting-access-to-resources","at":9532,"chars":824},{"level":2,"title":"Related information","slug":"related-information","at":10356,"chars":241}],"text":"# Adding and accessing resources in Business Central extensions\n> APPLIES TO: Business Central 2024 release wave 2, update 25.2 and later\nThis article describes how to package and use resources with your extensions. Resources are arbitrary files that you can include with your extension and access at runtime. For example, you can include sample data, images, or any other file that's used by your extension. By default, you can only access resources within the extension that includes them. Starting with runtime version 18.0, an extension can also expose selected resources as public, so that other extensions can read them. See #sharing-resources-with-other-apps.\n## Specifying resource folders\nTo 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:\n```json\n\"resourceFolders\": [\"Resources\"]\n```\nYou can specify multiple folders:\n```json\n\"resourceFolders\": [\"SampleImages\", \"ConfigurationFiles\"]\n```\nResource folders can contain subfolders as well. Files within these subfolders are also included as resources in the extension.\nResources that you declare with resourceFolders are private. Only the extension that packages them can read them at runtime. If you want other extensions to be able to read a resource, declare it as public instead, as described in #sharing-resources-with-other-apps.\nEvery folder listed in resourceFolders must exist relative to the project. If a folder doesn't exist, the compiler raises an error and the build fails.\n## Accessing the resources from AL\nYou can access resources from AL code at runtime. Several methods are available to interact with resources. The methods in the following table operate on the calling extension itself. They can access both private resources from resourceFolders and public resources from publicResourceFolders:\nMethod|Description\nmethods-auto/navapp/navapp-getresource-string-instream-textencoding-method `(ResourceName: Text; var ResourceStream: InStream; (Optional) Encoding: TextEncoding)`|Reads the content of resource files at runtime.\nmethods-auto/navapp/navapp-getresourceastext-string-textencoding-method `(ResourceName: Text; (Optional) Encoding: TextEncoding): Text`|Used to read the content of resource files directly into a Text object.\nmethods-auto/navapp/navapp-getresourceasjson-string-textencoding-method `(ResourceName: Text; (Optional) Encoding: TextEncoding): JsonObject`|Used to read the content of resource files directly into a JsonObject.\nmethods-auto/navapp/navapp-listresources-string-method `((Optional) Filter: Text)`|Used to list available resources in an extension.\nThe 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:\n```\nMyApp\n    Resources/\n        Images/\n            SampleImage1.png\n            SampleImage2.png\n        Templates/\n            Template1.txt\n            Template2.png\n```\nYou can access the content of the Template1.txt resource file with the following code:\n```al\nprocedure UsingResources()\nvar\n    resourceStream: InStream;\n    content: Text;\nbegin\n    NavApp.GetResource('Templates/Template1.txt', resourceStream, TextEncoding::UTF8);\n    resourceStream.Read(content);\nend;\n```\nNavApp.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:\n```al\nNavApp.ListResources(); // Will return [\"Images/SampleImage1.png\", \"Images/SampleImage2.png\", \"Templates/Template1.txt\", \"Templates/Template2.png\"]\nNavApp.ListResources('Images'); // Will return [\"Images/SampleImage1.png\", \"Images/SampleImage2.png\"]\nNavApp.ListResources('*.png'); // Will return [\"Images/SampleImage1.png\", \"Images/SampleImage2.png\", \"Templates/Template2.png\"]\n```\n## Sharing resources with other apps\n> APPLIES TO: Business Central 2026 release wave 2 and later\nBy default, a resource is private, so only its own extension can read it. If you want another extension to read one of your resources, declare the folder that contains it in the `\"publicResourceFolders\"` property of the manifest file (app.json) instead of, or in addition to, `\"resourceFolders\"`. For example:\n```json\n{\n  \"resourceFolders\": [\n    \"Resources\"\n  ],\n  \"publicResourceFolders\": [\n    \"PublicResources\"\n  ]\n}\n```\nPublic resource folders follow the same rules as private resource folders: they can contain subfolders, and every listed folder must exist relative to the project or the build fails. A resource name is the relative path from the resource folder, and it must be unique across both resourceFolders and publicResourceFolders. Declaring the same name as both private and public causes a build error.\nWhen you build an extension that has public resources, the compiler lists every packaged public resource in both the ALC console output and the Output window in Visual Studio Code, so that you can confirm what you're sharing:\n```text\nPublic resources included in the package (2):\n  schemas/customer.json\n  templates/invoice.txt\n```\n### Access another app's public resources from AL\nTo read a public resource that belongs to a different extension, use the app ID overloads of the resource methods and pass the target extension's app ID as the AppId parameter. The app ID is the id value from the target extension's app.json file. These overloads can only access resources that the target extension declared public:\nMethod|Description\nmethods-auto/navapp/navapp-getresource-string-guid-instream-textencoding-method `(ResourceName: Text; AppId: Guid; var ResourceStream: InStream; (Optional) Encoding: TextEncoding)`|Reads the content of a public resource from another extension into an InStream.\nmethods-auto/navapp/navapp-getresourceastext-string-guid-textencoding-method `(ResourceName: Text; AppId: Guid; (Optional) Encoding: TextEncoding): Text`|Reads the content of a public resource from another extension directly into a Text value.\nmethods-auto/navapp/navapp-getresourceasjson-string-guid-textencoding-method `(ResourceName: Text; AppId: Guid; (Optional) Encoding: TextEncoding): JsonObject`|Reads the content of a public resource from another extension directly into a JsonObject.\nmethods-auto/navapp/navapp-listresources-guid-string-method `(AppId: Guid; (Optional) Filter: Text): List of [Text]`|Lists the public resources of another extension. Unlike the single-argument NavApp.ListResources, this overload always returns public resources only, even when AppId is the ID of the calling extension itself.\nmethods-auto/navapp/navapp-listappswithpublicresources-method `((Optional) Filter: Text): List of [Guid]`|Returns the app IDs of every installed extension that has at least one public resource matching Filter. Use this method to discover providers before calling the other methods.\nThe following example reads a JSON schema that another extension, identified by its app ID, publishes as a public resource:\n```al\nprocedure GetSupplierPricingSchema(): JsonObject\nvar\n    SupplierAppId: Guid;\nbegin\n    SupplierAppId := '00001111-aaaa-2222-bbbb-3333cccc4444';\n    exit(NavApp.GetResourceAsJson('schemas/pricing.json', SupplierAppId, TextEncoding::UTF8));\nend;\n```\nYou can also discover which installed extensions publish a matching public resource, and then enumerate what each of them offers:\n```al\nprocedure ProcessAllPricingSchemas()\nvar\n    ProviderAppIds: List of [Guid];\n    ProviderAppId: Guid;\n    ResourceNames: List of [Text];\n    ResourceName: Text;\n    Schema: JsonObject;\nbegin\n    ProviderAppIds := NavApp.ListAppsWithPublicResources('schemas/*.json');\n    foreach ProviderAppId in ProviderAppIds do begin\n        ResourceNames := NavApp.ListResources(ProviderAppId, 'schemas/*.json');\n        foreach ResourceName in ResourceNames do begin\n            Schema := NavApp.GetResourceAsJson(ResourceName, ProviderAppId);\n            ProcessPricingSchema(ProviderAppId, ResourceName, Schema);\n        end;\n    end;\nend;\n```\nKeep the following behaviors in mind when you work with public resources:\n `NavApp.ListResources()` without an AppId returns the calling extension's own resources, both private and public. `NavApp.ListResources(AppId)` always returns public resources only, even when AppId is the calling extension's own app ID.\n If you try to retrieve a resource by app ID that either doesn't exist or is private to the target extension, you get the same not-found error in both cases. This behavior prevents an extension from using error messages to determine whether a private resource exists.\n## Limits on resources\nThe following limits are enforced on the resources that you can include in an extension:\nLimit|Value\nMaximum size of any single resource file|16 MB\nMaximum size of all files in one resource folder|128 MB\nMaximum number of files in one resource folder|256 files\nThese limits are subject to change in the future.\n> NOTE\n> Before version 26.3, embedded resources can't be retrieved in runtime packages. The only way around that is to publish the regular package to the database.\n## Limiting access to resources\nBy default, an extension can only access its own resources. If two apps declare private resources with the same name, each app can only access its own version of the resource. Starting with runtime version 18.0, an extension can opt in to sharing specific resources by declaring them public, as described in #sharing-resources-with-other-apps. Resources that stay in resourceFolders remain private and can't be accessed by other extensions, regardless of the public resource capability.\nResources are treated like code with regard to the Resource exposure policy<devenv-security-settings-and-ip-protection> 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.\n## Related information\nGet started with AL<devenv-get-started>\ndevenv-how-publish-and-install-an-extension-v2\nResource exposure policy setting<devenv-security-settings-and-ip-protection>\ndevenv-json-files\nmethods-auto/navapp/navapp-data-type"}