Debugging in AL

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Note

We're working on improving the onboarding experience for AL developers. If you've input for this article, we'd love to hear from you. Please use the Feedback section at the bottom of this article to help us make improvements that you’d like to see.

We also welcome contributions to our docs. New to contributing to docs? Don't worry, read more about contributing here Contribute to the help.

Debugging is the process of finding and correcting errors. With Visual Studio Code and the AL Language extension for Microsoft Dynamics 365 Business Central, you get an integrated debugger to help you inspect your code and verify that your application can run as expected. You can start a debugging session by pressing F5. For more information about Debugging in Visual Studio Code, see Debugging.

An alternative to classic debugging is snapshot debugging, which allows you to record running code, and later debug it. For more information, see Snapshot Debugging.

Important

To enable debugging in versions before Business Central April 2019, the NetFx40_LegacySecurityPolicy setting in the Microsoft.Dynamics.Nav.Server.exe.config file must be set to false. This step requires a server restart.

Important

To use the development environment and debugger for on-premises environments, you must make sure that port 7049 is available.

There are some limitations to be aware of:

• "External code" can only be debugged if the code has the allowDebugging flag set to true. For more information, see Resource Exposure Policy Setting.
• The debugger launches a new client instance each time you select F5. If you close the debugging session and then start a new session, this new session will rely on a new client instance. We recommend that you close the Web client instances when you close a debugging session.
• Pausing the debugging session isn't supported.

To control table data synchronization between each debugging session, see Retaining table data after publishing.

Tip

To be able to debug an online environment with an Embed app published in it, make sure to specify the applicationFamily parameter in your launch.json file. You must define the application family for your Embed app during onboarding.

Breakpoints

The basic concept in debugging is the breakpoint, which is a mark that you set on a statement. When the program flow reaches the breakpoint, the debugger stops execution until you instruct it to continue. Without any breakpoints, the code runs without interruption when the debugger is active. You can set a breakpoint by using the Debug Menu in Visual Studio Code. For more information, see Debugging Shortcuts.

Set breakpoints on the external code that isn't part of your original project. You can step into the base application code by using the Go to Definition feature and set breakpoints on the referenced code, which is generally a .dal file. To set a breakpoint on the external code or base application code, you do as follows:

• Use Go to Definition, which opens the "external file", and then a breakpoint can be set.
• By using the debugger, you can step into the code, and then set a breakpoint.

The following video illustrates that Customer.dal is an external file. A breakpoint is set in the Customer.dal file, which is referenced from your AL project to stop execution at the marked point.

For more information about Go to Definition, see AL Code Navigation.

Conditional breakpoints

You can also set a condition on a breakpoint and if the condition evaluates as true, then code execution breaks at the breakpoint. For more information, see Setting conditional breakpoints.

Break on errors

Specify if the debugger breaks on the next error by using the breakOnError property. If the debugger is set to breakOnError, it stops execution on both errors that are handled in code and unhandled errors.

The default value of the breakOnError property is true, which means the debugger stops the execution that throws an error by default. To skip the error handling process, set the breakOnError property to false in the launch.json file.

Tip

If the debugging session takes longer, you can refresh the session by selecting the Ctrl+Shift+P keys and selecting Reload Window.

Break on record changes

Specify if the debugger breaks on record changes by using the breakOnRecordWrite property. If the debugger is set to break on record changes, then it breaks before creating, modifying, or deleting a record. The following table shows each record change and the AL methods that cause each change.

Record change	AL Methods
Create a new record	Insert Method (Record)
Update an existing record	Modify Method (Record), ModifyAll Method (Record), Rename Method (Record)
Delete an existing record	Delete Method (Record), DeleteAll Method (Record)

The default value of the breakOnRecordWrite property is false, which means that the debugger isn't set to break on record changes by default. To break on record changes, you can set the breakOnRecordWrite property to true in the launch.json file. For more information, see JSON Files.

Debugging large size variable values

Variables with values larger than 1024 bytes are truncated (…) and can't be fully inspected from the VARIABLES window. To inspect a large size variable value, instead use the DEBUG CONSOLE and write the name, or qualified name of a variable to inspect at the prompt and then select Enter.

Attach and Debug Next

If you don't want to publish and invoke the functionality to debug it, you can attach a session to a specified server and await a process to trigger the breakpoint you have set. For more information, see Attach and Debug Next.

Debugging shortcuts

Keystroke	Action
F5	Start debugging
Ctrl+F5	Start without debugging
Shift+F5	Stop debugging
Ctrl+Shift+F5	Start debugging without publishing. Using this command on a changed but unpublished code may trigger false existing breakpoints. For example, if you modify the method "foo", add two lines, put a breakpoint on the second line, and then start debugging without publishing, that breakpoint won't be hit, or if it's hit isn't your new code that it breaks. If it breaks, it will break on the line that the server thinks the breakpoint is, based on the last published code.
Alt+F5	Start RAD with debugging. For more information, see Working with Rapid Application Development.
F10	Step over
F11	Step into
Shift+F11	Step out
F12	Go To Definition

For more shortcuts, see Debugging in Visual Studio Code. For working with Snapshot Debugging, see Snapshot Debugging.

Debugging SQL behavior

Traditionally, debugging AL has been about examining the behavior of the language runtime, for example, looking into the content of local variables at a breakpoint. As of Business Central April 2019, the AL debugger also offers the capability to examine your AL code's effect on the Business Central database. The enableSQLInformationDebugger setting enables this functionality. For more information, see Launch JSON file.

View database statistics

In the VARIABLES pane in debugger, expand the <Database statistics> node to get insights such as the current network latency between the Business Central Server and the Business Central database, the total number of SQL statements executed, the total number of rows read, and locks held, as well as insights into the most recent SQL statements executed by the server. The following insights are part of the database statistics:

Insight	Description
Current SQL latency (ms)	When the debugger hits a breakpoint, the Business Central Server will send a short SQL statement to the database, and measures the time it takes. The value is in milliseconds.
Number of SQL Executes	This number shows the total number of SQL statements executed in the debugging session since the debugger was started.
Number of SQL Rows Read	This number shows the total number of rows read from the Business Central database in the debugging session since the debugger was started.

Tip

You can also get database insights from the AL runtime by using the SqlStatementsExecuted() and SqlRowsRead() methods.

View locks held

The Locks part of the database statistics shows an overview of the SQL locks held by the debugged session. The insight can be used to understand the locks acquired while stepping through AL code. The access mode of the lock is also provided, which allows advanced developers to establish concurrency compatibility with other operations.

View SQL statement statistics

The database insights also let you peek into the most recent and the latest long running SQL statements executed by the server. To view a list of the statements, expand either the <Last Executed SQL Statements> or <Last Long Running SQL Statements> node. The following insights are part of the SQL statement statistics:

Insight	Description
Statement	The SQL statement that the AL server sent to the Business Central database. For further analysis, you can copy the SQL statement into other database tools, such as SQL Server Management Studio.
Execution time (UTC)	The timestamp (in UTC) of when the SQL statement was executed. You can use this to infer whether the SQL statement was part of the AL code between the current and last breakpoint (if set).
Duration (ms)	The duration in milliseconds of the total execution time of the SQL statement measured inside the Business Central Server. You can use Duration (ms) to analyze whether you're missing indexes (Business Central keys), or to experiment with database partitioning and/or compression performance.
Approx. Rows Read	This number shows the approximate number of rows read from the Business Central database by the SQL statement. You can use this insight to analyze whether you're missing filters.

The number of SQL statements tracked by the debugger can be configured in the Business Central Server. The default value is 10.

Note

For Business Central on-premises, the Business Central Server instance has several configuration settings that control the SQL statistics. These statistics are gathered and then displayed in the debugger, like whether long running SQL statements or SQL statements are shown. Check the server configuration if you don't see the insights that you expect in the debugger. For more information, see Configuring Business Central Server.

Debugging web services

It's possible to debug code executed from web service endpoints, both pages and codeunits exposed as OData/SOAP, and API pages/queries. To do so, simply set the breakOnNext setting to WebServiceClient and trigger the web service endpoint from an API explorer tool or your web service client code. For more information, see Attach and Debug Next.

NonDebuggable attribute

The ability to debug certain methods and/or variables can be restricted. For more information, see NonDebuggable Attribute.

Authenticate with Microsoft Entra ID on Business Central on-premises

You can use Microsoft Entra ID as the authentication mechanism for Business Central on-premises or containers. For more information, see Microsoft Entra authentication for Business Central on-premises.

Troubleshooting your debugging setup

This section provides some tips and tricks for working with and troubleshooting your debugging setup.

Debugging in versions before Business Central April 2019

To enable debugging in versions before Business Central April 2019, the NetFx40_LegacySecurityPolicy setting in the Microsoft.Dynamics.Nav.Server.exe.config file must be set to false. This step requires a server restart.

Firewall settings for on-premises environments (port 7049)

To use the development environment and debugger for on-premises environments, you must make sure that port 7049 (the default port for the debugger) is open. The port can be changed with the server setting DeveloperServicesPort.

Debug an online environment with an Embed app published in it

To be able to debug an online environment with an Embed app published in it, make sure to specify the applicationFamily parameter in your launch.json file. You must define the application family for your Embed app during onboarding.

Launching debug sessions to on-premises environments

To be able to debug sessions in an on-premises environment, make sure to specify the usePublicURLFromServer parameter in your launch.json file. For more information, see Publish to local server settings (launch.json)

Related information

Attach and debug next
Snapshot debugging
Developing extensions
JSON files
AL code navigation