JSON Files

Straipsnis
12/23/2022
20 min. skaityti

When you start a new AL project, two JSON files; the app.json file and the launch.json file are generated automatically. The app.json file contains information about the extension that you're building, such as publisher information and specifies the minimum version of base application objects that the extension is built on. Often, the app.json file is referred as the manifest. The launch.json file contains information about the server that the extension launches on.

Note

For information about data migration and creating a migration.json file, see The Migration.json File.

Important

The rad.json and the snapshots.json files should not be modified.

App.json file

The following table describes the settings in the app.json file. To see an example app.json file, go to Business Central Performance Toolkit.

Setting	Mandatory	Value
id	Yes	The unique ID of the extension. When the `app.json` file is automatically created, the ID is set to a new GUID value. Note: The app ID is used at runtime to bind table names contained in the application. Changing the app ID will result in data from old tables not being used.
name	Yes	The unique extension name. The name can be changed to reflect branding or acquisition, but then the `version` must be incremented. Note: The name can be used by other extensions to express a compile-time dependency on the extension. Changing the name of your extension will force any extensions that have taken a dependency to download symbols and recompile their extension. For more information, see App Identity.
publisher	Yes	The name of your publisher, for example: NAV Partner, LLC. Note: The publisher can be used by other extensions to express a compile-time dependency on the extension. Changing the publisher of your extension will force those extensions that have taken a dependency to download symbols and recompile their extension. For more information, see App Identity.
brief	No, but required for AppSource submission	Short description of the extension.
description	No, but required for AppSource submission	Longer description of the extension.
version	Yes	The version of the app package.
privacyStatement	No, but required for AppSource submission	URL to the privacy statement for the extension.
EULA	No, but required for AppSource submission	URL to the license terms for the extension.
help	No, but required for AppSource submission	URL to an online description of the extension focusing on the help and troubleshooting content. The link is used in AppSource and can be the same as the value of the `contextSensitiveHelpUrl` property. To learn more about help links, see Help and Support Links.
url	No, but required for AppSource submission	URL of the extension package. The link is used in Business Central, on the Extension Management page, as Website. This URL can be a link to an advertising page for your app, a page describing the features and additional resources other than troubleshooting and help, or it can be a link for contacting the app support, for example, see Support Links.
logo	No, but required for AppSource submission	Relative path to the app package logo from the root of the package.
test	No	Version of the dependent test framework in the format X.Y.U.Z. Note: This property is only supported for Business Central version 14 and earlier, where the base app is C/AL.
dependencies	No	List of dependencies for the extension package. For example: `"dependencies": [ {"id": "4805fd15-75a5-46a2-952f-39c1c4eab821", "name": "WeatherLibrary", "publisher": "Microsoft", "version": "1.0.0.0"},{}]`. Note: For dependencies to the System Application and Base Application, these are no longer listed as explicit dependencies, but captured in the `application` setting as a reference to the application package. They must have a version number of the Application package. See `application` below. Note: The version specified defines the minimum version for the dependency. At runtime and when downloading symbols, the latest version of the dependency satisfying the specified name, publisher and, minimum version will be returned. When `runtime` is set to 4.0 or earlier, use `appId` instead of `id`.
screenshots	No	Relative paths to any screenshots that should be in the extension package.
platform	Yes, if system tables are referenced in the extension	The minimum supported version of the platform symbol package file, for example: "16.0.0.0". See the Symbols for the list of object symbols contained in the platform symbol package file.
application	Yes, if base application is referenced in the extension. Required for AppSource submission	The supported version of the system and base application package file, for example: "16.0.0.0". The file name of this reference is Microsoft_Application.app and the `name` is `Application`. If the base application has been customized, the Microsoft_Application.app file can be modified to reference the code-customized base application instead. It's important to keep `"name": "Application"` in the extension, but information about publisher can be changed and the .app file can be renamed. For more information, see The Microsoft_Application.app File.
idRange	Yes	A range for application object IDs. For example: `"idRange": {"from": 50100,"to": 50149}`. For all objects outside the range, a compilation error will be raised. When you create new objects, an ID is automatically suggested. To learn about which object ranges are allowed for your extension, see Object Ranges.
idRanges	Yes	A list of ranges for application object IDs. For example: `"idRanges": [{"from": 50100,"to": 50200},{"from": 50202,"to": 50300}]`. For all objects outside the ranges, a compilation error will be raised. When you create new objects, an ID is automatically suggested. You must use either the `idRange` or the `idRanges` setting. Overlapping ranges aren't allowed and will result in a compilation error. To learn about which object ranges are allowed for your extension, see Object Ranges.
showMyCode	No	By default, it's set to `false` and isn't visible in the manifest. To enable viewing the source code when debugging an extension, add the following setting: `"showMyCode": true`. Note: This setting will be deprecated in a future release, and replaced by the `resourceExposurePolicy` setting introduced with runtime 8.0. It's described in this table.
target	No	By default, this is `Cloud`. The setting currently has the following options: `Internal`, `Extension`, `OnPrem`, and `Cloud`. The `Internal` and `Extension` settings are being deprecated with runtime 4.0 and replaced by the `OnPrem` and `Cloud` respectively. For on-premises, you can set this to `OnPrem` to get access to otherwise restricted APIs and .NET Interop. Then, the Business Central Server setting must also be set to `OnPrem`. Note: System tables that have the Scope property set to `Internal`/`OnPrem` can't be accessed from extensions that have `target` set to `Cloud`/`External` through direct reference or through RecordRef. For more information, see Compilation Scope Overview
contextSensitiveHelpUrl	No, but required for AppSource submission	The URL for the website that displays context-sensitive Help for the objects in the app, such as `https://mysite.com/documentation/`. If the app doesn't support all locales currently supported by Business Central, then include a parameter for the locale in this URL, `/{0}/`, and also specify the relevant locales in the `supportedLocales` setting.
helpBaseUrl	No	The URL for the website that overtakes all Help for the specified locales. This property is intended for localization apps specifically, since the setting overwrites the default URL of `/{0}/dynamics365/business-central`. If you set this value, you must also specify one or more languages in the `supportedLocales` setting.
supportedLocales	No	The list of locales that are supported in your Help if different from all locales. The value on the list is entered into the URL defined in the `contextSensitiveHelpUrl` and `helpBaseUrl` properties. The first locale on the list is default. An example is `"supportedLocales": ["da-DK", "en-US"]` for an app that supports only Danish and English (US).
runtime	No	The version of the runtime that the project is targeting. The project can be published to a server that supports the same or a higher runtime version. The available options are: `1.0` - Business Central April 2018 Release `2.0` - Business Central Fall '18 Release `3.0` - Business Central Spring '19 Release `4.0` - Business Central 2019 release wave 2 `5.0` - Business Central 2020 release wave 1 `6.0` - Business Central 2020 release wave 2 `6.1` - Business Central 2020 release wave 2 update 17.1 `6.2` - Business Central 2020 release wave 2 update 17.2 `6.3` - Business Central 2020 release wave 2 update 17.3 `6.4` - Business Central 2020 release wave 2 update 17.4 `7.0` - Business Central 2021 release wave 1 `7.1` - Business Central 2021 release wave 1 update 18.1 `7.2` - Business Central 2021 release wave 1 update 18.3 `8.0` - Business Central 2021 release wave 2 `8.1` - Business Central 2021 release wave 2 update 19.1 `9.0` - Business Central 2022 release wave 1 `9.1` - Business Central 2022 release wave 1 update 20.1 `9.2` - Business Central 2022 release wave 1 update 20.4 `10.0` - Business Central 2022 release wave 2 For more information, see Choosing Runtime Version in AL.
features	No	Specifies a list of options. The `TranslationFile` option generates a `\Translations` folder that is populated with the .xlf file that contains all the labels, label properties, and report labels that you're using in the extension. The `GenerateCaptions` option depends on the `TranslationFile` setting. It generates captions for objects that don't have a `Caption` or `CaptionML` specified. These are then written to the .xlf file. The `GenerateLockedTranslations` flag is used to generate `<trans-unit>` elements in the XLIFF file for locked labels. The syntax is `"features": [ "TranslationFile", "GenerateCaptions", "GenerateLockedTranslations" ]`. For more information, see Working with Translation Files. When the `NoImplicitWith` flag is specified, `ImplicitWith` will be turned off by default. This flag is useful when all code has been rewritten to avoid any future use of `ImplicitWith`. For more information, see Pragma ImplicitWith and Deprecating Explicit and Implicit With Statements.
internalsVisibleTo	No	Specifies a list of modules that have access to the objects that are marked as `Internal` using the Access property from the current module. The syntax is `{ "appId": "d6c3f231-08d3-4681-996f-261c06500e1a", "name": "TheConsumer", "publisher": "Microsoft"}]`. For more information, see Access Property and InternalEvent Attribute. Note: Using `internalsVisibleTo` in Business Central online will throw a warning from AppSourceCop and PTECop. `Access = Internal` is not designed as a security boundary, but for API development.
propagateDependencies	No	Specifies whether the direct dependencies of this project should be propagated as direct dependencies of projects that depend on this one. Default is `false`. If, set to `true` then, any dependencies of the current package will be visible to consumers of the package. For example, if A depends on B that depends on C, by default, A won't be able to use types defined in C. If B has `"propagateDependencies" : "true"`, then A will be able to use types defined in C without taking a direct dependency. Note: `propagateDependencies` applies to all direct dependencies, there's no option to exclude specific dependencies.
preprocessorSymbols	No	Defines any symbols to use with preprocessor directives. The syntax is `"preprocessorSymbols": [ "DEBUG","PROD" ]`. For more information, see Preprocessor Directives in AL.
applicationInsightsKey	No, is deprecated in favor of `applicationInsightsConnectionString` as of runtime `7.2` - Business Central 2021 release wave 1 update 18.2	The instrumentation key of the Azure Application Insights resource for monitoring operations, for example, like app secrets retrieval by extensions. For more information, see Monitoring and Analyzing Telemetry.
applicationInsightsConnectionString	No, but recommended for AppSource submission	The instrumentation key of the Azure Application Insights resource for monitoring operations, for example, like app secrets retrieval by extensions. For more information, see Monitoring and Analyzing Telemetry.
keyVaultUrls	No	List of URLs of key vaults that from which the extension can retrieve secrets. For example: `"keyVaultUrls": [ "https://myfirstkeyvault.vault.azure.net", "https://mysecondkeyvault.vault.azure.net" ]`. For more information, see App Key Vaults.
suppressWarnings	No	Specifies that warnings issued by, for example, a specific analyzer rule shouldn't be shown in the Output window. Syntax is `"suppressWarnings": [<warning ID>,<warning ID2>,...]`. For example, `"suppressWarnings": [ "AL0458" ]`. It's also possible to use `#pragma` directives for suppressing warnings for specific areas of code. For more information, see Pragma Warning Directive and Suppressing Warnings.
resourceExposurePolicy	No	Defines the accessibility of the resources and source code during different operations. The `resourceExposurePolicy` property contains four options for defining access: `applyToDevExtension`, `allowDebugging`, `allowDownloadingSource`, and `includeSourceInSymbolFile`. All defaults are false. The syntax is `"resourceExposurePolicy": {"applyToDevExtension": true, "allowDebugging": true, "allowDownloadingSource": true, "includeSourceInSymbolFile": true}`. For more information, see Resource Exposure Policy Setting.

Launch.json file

The following table describes the settings in the launch.json file. The launch.json file has two configurations depending on whether the extension is published to a local server or to the cloud.

Publish to local server settings

Setting	Mandatory	Value
name	Yes	"Your own server"
type	Yes	Must be set to `"al"`. Required by Visual Studio Code.
request	Yes	Request type of the configuration. Can be set to `"launch"`, `"attach"`, or `"snapshotInitialize"` . Required by Visual Studio Code. For more information, see Attach and Debug Next and Snapshot Debugging.
server	Yes	The HTTP URL of your server, for example: `"https://localhost\|serverInstance"`
port	No	The port assigned to the development service.
serverInstance	Yes	The instance name of your server, for example: `"US"`
authentication	Yes	Specifies the server authentication method and can be set to `"UserPassword"`, `"Windows"`, or `"AAD"`. To use AAD authentication for on-premise servers, `primaryTenantDomain` setting must be entered. For more information, see Using Azure AD authentication for Business Central on-premises installations.
startupObjectType	No	Specifies whether the object to open after publishing is a Page type (`"Page"`), a Table type (`"Table"`), a Report type (`"Report"`) or a Query type (`"Query"`) object. The default is `"Page"`.
startupObjectId	No	Specifies the ID of the object to open after publishing. Only objects of type Page, Table, Report, and Query are currently supported.
startupCompany	No	Specifies the name of the company to open after publishing. If `startupCompany` is specified, the settings `startupObjectId` and `startupObjectType` must also be defined.
schemaUpdateMode	No	Specifies the data synchronization mode when you publish an extension to the development server, for example: `"schemaUpdateMode": "Recreate"` The default value is Synchronize. For more information, see Retaining table data after publishing This feature is not supported in Dynamics NAV.
environmentType	No	Specifies which type of environment to use to connect to Business Central. Possible values are `OnPrem`, `Sandbox`, or `Production`.
environmentName	No	Specifies which named production or sandbox environment to use in cases where multiple sandboxes are owned by the same tenant.
breakOnError	No	Specifies if and how the debugger breaks on errors in Try functions. With Business Central 2022 release wave 2 `breakOnError` contains the following options: `true` `false`, `None`, `All`, `ExcludeTry`. `false/None` - does not break on any errors, `true/All` -breaks on all errors, and `ExcludeTry` - breaks on errors only if they occur outside of the context of a Try function. The values `true` and `false` are retained for now for backwards compatibility. They map to `All` and `None`. We recommend using the latter going forward. `True` and `false` might become obsolete in a future version.
breakOnNext	No	Specifies the session type that the server will connect to. The options are: `WebserviceClient` - web API-based client including ODdata and SOAP clients, `WebClient` - standard web client, `Background` - background sessions, such as job queues, see Task Scheduler. This setting applies to Attach and Debug Next and to Snapshot Debugging. For Attach debugging, `breakOnNext` defines the next client session that the debug engine will attach to for the same user who has initiated an attach debug session from Visual Studio Code. For Snapshot debugging, `breakOnNext` defines the next session to hook AL code execution recording for a given user on a tenant. Or, if this isn't specified with the userId in the configuration settings; the first user on the tenant.
breakOnRecordWrite	No	Specifies if and how the debugger breaks on record changes. With Business Central 2022 release wave 2 `breakOnRecordWrite` contains the following options: `true`, `false`, `None`, `All`, and `Exclude Temporary`. - `false`/`None` specifies to not break on any record writes. - `true`/`All` specifies to break on all record writes. - `ExcludeTemporary` specifies to break on record writes only if they are not on a temporary table. The values `true` and `false` are retained for backward compatibility, mapping to `All` and `None`. It's recommended using the latter going forward. `True` and `false` might become obsolete in a future version.
launchBrowser	No	Specifies whether to open a new tab page in the browser when publishing the AL extension (Ctrl+F5). The default value is `false`. If the value isn't specified or set to `true`, the session is started. If the value is explicitly set to `false`, the session isn't started unless you launch your extension in debugging mode.
enableSqlInformationDebugger	Yes	Specifies whether the debugger shows the SQL information. The default value is `true`. For more information, see Debugging SQL behavior.
enableLongRunningSqlStatements	Yes	Specifies whether the debugger enables long running SQL statements in the debugger window.
longRunningSqlStatementsThreshold	Yes	Sets the number of milliseconds spent before a SQL statement is considered as long running in the debugger.
numberOfSqlStatements	Yes	Sets the number of SQL statements to be shown in the debugger.
dependencyPublishingOption	No	Available options are: `Default` - set dependency publishing will be applied `Ignore` - dependency publishing is ignored `Strict` - dependency publishing will fail if there are any apps that directly depend on the startup project and these apps aren't part of the workspace. For more information, see Working with multiple projects and project references.
disableHttpRequestTimeout	No	Specifies if the default setting for HTTP request timeout in Visual Studio Code is switched off. The default value is `false`. If the value is set to `true` requests can run without timeout.
attach	No	Sets the session to attach to. There are two options; `Attach to the next client on the cloud sandbox` and `Attach to the next client on your server`. Use the first option to attach to a cloud session, and the second option to attach to a local server. For more information, see Attach and Debug Next.
forceUpgrade	No	Always run upgrade codeunits, even if the version number of the extension is the same as an already installed version. This can be useful for troubleshooting upgrade issues. Note: The `forceUpgrade` setting requires the package ID to be changed.
useSystemSession	No	Runs install and upgrade codeunits in a system session. This will prevent debugging install and upgrade codeunits.
snapshotFileName	No	Specifies the snapshot file name used when snapshot debugging files are saved. For more information, see Snapshot Debugging.
primaryTenantDomain	No	Specifies the URL of the Azure AD organization or company associated with the Azure AD tenant. This setting enables AAD scenarios for on-premises installations. For more information, see Azure AD authentication for Business Central on-premises

Publish to cloud settings

Setting	Mandatory	Value
name	Yes	"Microsoft cloud sandbox"
type	Yes	Must be set to `"al"`. Required by Visual Studio Code.
request	Yes	Request type of the configuration. Must be set to `"launch"`. Required by Visual Studio Code.
startupObjectType	No	Specifies whether the object to open after publishing is a Page type (`"Page"`), a Table type (`"Table"`), a Report type (`"Report"`) or a Query type (`"Query"`) object. The default is `"Page"`.
startupObjectId	No	Specifies the ID of the object to open after publishing. Only objects of type Page, Table, Report and Query are currently supported.
startupCompany	No	Specifies the name of the company to open after publishing. If `startupCompany` is specified, the settings `startupObjectId` and `startupObjectType` must also be defined.
tenant	No	Specifies the tenant to which the package is deployed. If you specify multiple configurations, a drop-down of options will be available when you deploy. This parameter must contain a tenant AAD domain name, for example `mycustomer.onmicrosoft.com`.
environmentType	No	Specifies which type of environment to use to connect to Business Central. Possible values are `OnPrem`, `Sandbox`, or `Production`.
environmentName	No	Specifies which named production or sandbox environment to use in cases where multiple sandboxes are owned by the same tenant.
applicationFamily	No (Yes for Embed apps)	The application family in the cloud server, for example `Fabrikam`. This property is reserved for Embed apps.
breakOnError	No	Specifies if and how the debugger breaks on errors in Try functions. With Business Central 2022 release wave 2 `breakOnError` contains the following options: `true`, `false`, `None`, `All`, `ExcludeTry`. `false/None` - does not break on any errors, `true/All` -breaks on all errors, and `ExcludeTry` - breaks on errors only if they occur outside of the context of a Try function. The values `true` and `false` are retained for now for backwards compatibility. They map to `All` and `None`. We recommend using the latter going forward. `True` and `false` might become obsolete in a future version.
breakOnNext	No	Specifies the session type that the server will connect to. The options are: `WebserviceClient` - web API-based client including OData and SOAP clients, `WebClient` - standard web client, `Background` - background sessions, such as job queues, see Task Scheduler. This setting applies to Attach and Debug Next and to Snapshot Debugging. For Attach debugging, `breakOnNext` defines the next client session that the debug engine will attach to for the same user who has initiated an attach debug session from Visual Studio Code. For Snapshot debugging, `breakOnNext` defines the next session to hook AL code execution recording for a given user on a tenant. Or, if this isn't specified with the userId in the configuration settings; the first user on the tenant.
breakOnRecordWrite	No	Specifies if and how the debugger breaks on record changes. With Business Central 2022 release wave 2 `breakOnRecordWrite` contains the following options: `true`, `false`, `None`, `All`, and `Exclude Temporary`. - `false`/`None` specifies to not break on any record writes. - `true`/`All` specifies to break on all record writes. - `ExcludeTemporary` specifies to break on record writes only if they are not on a temporary table. The values `true` and `false` are retained for backward compatibility, mapping to `All` and `None`. It's recommended using the latter going forward. `True` and `false` might become obsolete in a future version.
launchBrowser	No	Specifies whether to open a new tab page in the browser when publishing the AL extension (Ctrl+F5). The default value is `false`. If the value isn't specified or set to `true`, the session is started. If the value is explicitly set to `false`, the session isn't started unless you launch your extension in debugging mode.
enableSqlInformationDebugger	Yes	Specifies whether the debugger shows the SQL information. The default value is `true`. For more information, see Debugging SQL behavior.
enableLongRunningSqlStatements	Yes	Specifies whether the debugger enables long running SQL statements in the debugger window.
longRunningSqlStatementsThreshold	Yes	Sets the number of milliseconds spent before a SQL statement is considered as long running in the debugger.
numberOfSqlStatements	Yes	Sets the number of SQL statements to be shown in the debugger.
dependencyPublishingOption	No	Available options are: `Default` - set dependency publishing will be applied `Ignore` - dependency publishing is ignored `Strict` - dependency publishing will fail if there are any apps that directly depend on the startup project and these apps aren't part of the workspace. For more information, see Working with multiple projects and project references.
disableHttpRequestTimeout	No	Specifies if the default setting for HTTP request timeout in Visual Studio Code is switched off. The default value is `false`. If the value is set to `true` requests can run without timeout.
attach	No	Sets the session to attach to. There are two options; `Attach to the next client on the cloud sandbox` and `Attach to the next client on your server`. Use the first option to attach to a cloud session, and the second option to attach to a local server. For more information, see Attach and Debug Next.

Global and workspace launch configuration

With Business Central version 21.1, you can add a launch property to a code-workspace or in the settings.json file. This allows for a centralized configuration of projects. A local launch.json file overrides the workspace and global configuration. A workspace launch configuration overrides the launch configuration specified in the global settings.json file.

Note

If a local launch.json file doesn't contain a valid AL launch configuration, we'll try to find one in the code-workspace first, and then in the settings.json files. However, if the launch property is specified in the code-workspace file even without specifying a valid AL configuration, the global settings.json file won't be able to override it.