Debugging in AL
Azure Active Directory is now Microsoft Entra ID. Learn more
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.
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.
To use the development environment and debugger, 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
allowDebuggingflag set to
true. For more information, see Resource Exposure Policy Setting.
- The debugger launches a new client instance each time you press 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.
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.
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.
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
If the debugging session takes longer, you can refresh the session by pressing 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 press 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.
|Ctrl+F5||Start without 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.|
|F12||Go To Definition|
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:
|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.|
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:
|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.
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.
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.