Launch JSON file

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

The launch.json file contains information about the server that the extension launches on. The launch.json file has multiple configuration options available, for example, for snapshot debugging and attach debugging. In Visual Studio Code, you can choose to add a new configuration to the launch.json file, by selecting the Add Configuration button.

Shows the different configurations available in the lauch.json file for the Business Central development environment

The following configuration options are available:

In the following sections, you can find a description of the parameters that are available for each of the configurations. You'll also find a description of how to create a user or workspace launch configuration file.

Publish to local server settings (launch.json)

Here's an example of a configuration file for publishing to a local server.

{
    "name": "Publish: Your own server",        // maybe change the configuration name
    "type": "al",
    "request": "launch",
    "environmentType": "OnPrem",
    "server": "http://bcserver",               // change this to point to your instance URI
    "serverInstance": "BC",                    // change this to point to your instance
    "authentication": "UserPassword",          // change this to your auth setup
    "startupObjectId": 22,                     // change this to your choice of startup object
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "launchBrowser": true,
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500, 
    "numberOfSqlStatements": 10,
    "tenant": "default",                       // change this to point to your tenant
    "usePublicURLFromServer": true
}

The following table describes the settings in the launch.json file for publishing to a local server.

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. Set to "launch".
environmentType Yes Specifies which environment to use to connect to Business Central.
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 Microsoft Entra authentication for on-premise servers, primaryTenantDomain setting must be entered. For more information, see Using Microsoft Entra 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.
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.
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.
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.
useSystemSessionForDeployment 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 Microsoft Entra organization or company associated with the Microsoft Entra tenant. This setting enables Microsoft Entra ID scenarios for on-premises installations. For more information, see Microsoft Entra authentication for Business Central on-premises
tenant Yes For an on-premise server, this parameter must contain a tenant name, for example: MyTenant.
usePublicURLFromServer No Specifies whether to override the NST setting and instead use the host provided in the launch.json server property. When set to false, the PublicWebBaseURL server (NST) setting will be overridden with the server parameter of the launch.json when launching the browser using that specific launch configuration.
Note:
This option only affects launching debug sessions to on-premise servers.
When set to true, the PublicWebBaseURL server setting will be used.

Publish to cloud settings (launch.json)

Here's an example of a configuration file for publishing to a cloud sandbox.

{
    "name": "Publish: Microsoft cloud sandbox", // maybe change the configuration name
    "type": "al",
    "request": "launch",
    "environmentType": "Sandbox",
    "environmentName": "sandbox",               // change this to point to your sandbox environment
    "startupObjectId": 22,                      // change this to your choice of startup object
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "launchBrowser": true,
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10
}

The following table describes the settings in the launch.json file for publishing to a cloud sandbox.

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.
environmentType Yes Specifies which environment to use to connect to Business Central. Must be set to 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.
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 Microsoft Entra ID domain name, for example mycustomer.onmicrosoft.com.
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.
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 to client on cloud sandbox settings (launch.json)

The attach configuration is used for specific debugging scenarios where you don't want to publish and invoke functionality to debug it. For more information, see Attach and debug next.

Here's an example of a configuration file for attaching to a client on a cloud sandbox.

{
    "name": "Attach: Microsoft cloud sandbox",  // maybe change the configuration name
    "type": "al",
    "request": "attach",
    "environmentType": "Sandbox",
    "environmentName": "sandbox",               // change this to point to your sandbox environment
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10,
    "breakOnNext": "WebServiceClient"
}

The following table describes the settings in the launch.json file for attaching to a client on a cloud sandbox.

Setting Mandatory Value
name Yes "Attach: Microsoft cloud sandbox"
type Yes Must be set to "al". Required by Visual Studio Code.
request Yes Must be set to attach.
environmentType Yes Specifies which environment to use to connect to Business Central. Must be set to Sandbox.
environmentName Yes Specifies which production, or sandbox environment to use.
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.
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.

Attach to client on your own server (launch.json)

The attach configuration is used for specific debugging scenarios where you don't want to publish and invoke functionality to debug it. For more information, see Attach and debug next.

Here's an example of a configuration file for attaching to a client on your own server.

{
    "name": "Publish: Your own server",        // maybe change the configuration name
    "type": "al",
    "request": "attach",
    "environmentType": "OnPrem",
    "server": "http://bcserver",               // change this to point to your instance URI
    "serverInstance": "BC",                    // change this to point to your instance
    "authentication": "UserPassword",          // change this to your auth setup
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,  
    "numberOfSqlStatements": 10,
    "breakOnNext": "WebServiceClient",
    "tenant": "default",                       // change this to point to your tenant
}

The following table describes the settings in the launch.json file for attaching to a client on your own server.

The settings for attaching to a client on your own server are described in the following table.

Setting Mandatory Value
name Yes "Attach: Your own server"
type Yes Must be set to "al". Required by Visual Studio Code.
request Yes Must be set to attach.
environmentType Yes Specifies which environment to use to connect to Business Central. Must be set to OnPrem.
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" (Microsoft Entra ID). To use Microsoft Entra ID for authenticating on-premise servers, primaryTenantDomain setting must be entered. For more information, see Using Microsoft Entra authentication for Business Central on-premises installations.
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.
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.
tenant Yes For an on-premise server, this parameter must contain a tenant name, for example: MyTenant.

Initialize a snapshot debugging session on a cloud production environment (launch.json)

Snapshot debugging allows you to record AL code that runs on the server, and when it has completed, you can debug the recorded snapshot in Visual Studio Code. For more information, see Snapshot debugging.

Here's an example of a configuration file for snapshot debugging on a cloud production environment.

{
    "name": "snapshotInitialize: Microsoft production cloud",  // maybe change the configuration name
    "type": "al",
    "request": "snapshotInitialize",
    "environmentType": "Production",                           // change this if you want to debug a sandbox environment 
    "environmentName": "production",                           // change this to point to your online environment
    "breakOnNext": "WebClient",
    "executionContext": "DebugAndProfile"
}

The following table describes the settings in the launch.json file for snapshot debugging on a cloud production environment.

Setting Mandatory Value
name Yes "snapshotInitialize: Microsoft production cloud"
type Yes Must be set to "al". Required by Visual Studio Code.
request Yes Must be set to snapshotInitialize.
userId No The GUID of the user who initiated the process to start snapshot debugging. For on-premises, this can also be the user name in user password authentication scenarios. The user must be able to start, or have a session type opened that is specified in the breakOnNext parameter.
Note: Specifying userId doesn't work with Windows authentication: "authentication" : "Windows", in which case you can only choose sessionId or attach to the next session. For more information, see Launch JSON file.
sessionId No A session ID for the user specified in userId.
environmentType Yes Specifies which environment to use to connect to Business Central. Must be set to Production.
environmentName Yes Specifies the production environment to use.
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.
executionContext Yes Specifies which kind of connection a snapshot debugging session will be established. There are three options: Debug, DebugAndProfile, and Profile. For more information, see AL Profiler.
snapshotVerbosity No Specifies the verbosity level of snapshot data. If SnapPoint is specified then stacktraces and line information will only be gathered on snap points. The options are: Full, which allows stepping through every line executed and SnapPoint, which only allows stepping to lines with SnapPoints.
profilingType Yes Specifies the profiling type to be used. There are two options:
Instrumentation, which means that if profiling is enabled then all frames executed will be measured for their total time
Sampling, which means that if profiling is enabled then frames will be collected and aggregated based on a sample interval. This option can only be used with the executionContext set to Profile. For more information, see [AL Profiler](devenv-al-profiler-overview.md
profileSamplingInterval No Specifies the sampling interval in milliseconds when the Sampling profiling type is specified. The default value is 100ms. Options are 50, 100, or 150 ms.

Initialize a snapshot debugging session on your own server (launch.json)

Snapshot debugging allows you to record AL code that runs on the server, and when it has completed, you can debug the recorded snapshot in Visual Studio Code. For more information, see Snapshot debugging.

Here's an example of a configuration file for snapshot debugging on your own server

{
    "name": "snapshotInitialize: Your own server",  // maybe change the configuration name
    "type": "al",
    "request": "snapshotInitialize",
    "environmentType": "OnPrem",
    "server": "http://bcserver",                    // change this to point to your instance URI
    "serverInstance": "BC",                         // change this to point to your instance
    "authentication": "UserPassword",               // change this to your auth setup
    "breakOnNext": "WebClient",
    "executionContext": "DebugAndProfile"
}

The following table describes the settings in the launch.json file for snapshot debugging on your own server.

Setting Mandatory Value
name Yes "snapshotInitialize: Your own server"
type Yes Must be set to "al". Required by Visual Studio Code.
request Yes Must be set to snapshotInitialize.
userId No The GUID of the user who initiated the process to start snapshot debugging. For on-premises, this can also be the user name in user password authentication scenarios. The user must be able to start, or have a session type opened that is specified in the breakOnNext parameter.
Note: Specifying userId doesn't work with Windows authentication: "authentication" : "Windows", in which case you can only choose sessionId or attach to the next session. For more information, see Launch JSON file.
sessionId No A session ID for the user specified in userId.
environmentType Yes Specifies which environment to use to connect to Business Central. Must be set to OnPrem.
environmentName Yes Specifies the environment to use.
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 Microsoft Entra authentication for on-premise servers, primaryTenantDomain setting must be entered. For more information, see Using Microsoft Entra authentication for Business Central on-premises installations.
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.
executionContext Yes Specifies which kind of connection a snapshot debugging session will be established. There are three options: Debug, DebugAndProfile, and Profile. For more information, see AL Profiler.
snapshotVerbosity No Specifies the verbosity level of snapshot data. If SnapPoint is specified then stacktraces and line information will only be gathered on snap points. The options are:
Full, which allows stepping through every line executed
SnapPoint, which only allows stepping to lines with SnapPoints.
profilingType Yes Specifies the profiling type to be used. There are two options:
Instrumentation, which means that if profiling is enabled then all frames executed will be measured for their total time
Sampling, which means that if profiling is enabled then frames will be collected and aggregated based on a sample interval. This option can only be used with the executionContext set to Profile. For more information, see AL Profiler.
profileSamplingInterval No Specifies the sampling interval in milliseconds when the Sampling profiling type is specified. The default value is 100ms. Options are 50, 100, or 150 ms.

User 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 user configuration. A workspace launch configuration overrides the launch configuration specified in the user 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 user settings.json file won't be able to override it.

See also

JSON files
AL development environment
App identity
Debugging in AL
Resource exposure policy setting
AL Language extension configuration
Configure context-sensitive help
App Key Vaults