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