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.

The following configuration options are available:

• Attach to the client on the cloud sandbox
• Attach to the client on your own server
• Initialize a snapshot debugging session on cloud sandbox
• Initialize a snapshot debugging session on your own server
• Publish to Microsoft cloud sandbox
• Publish to your own server

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.

Related information

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