In this article, we would discuss Debugging in Dynamics 365 Business Central Production Cloud Environment.
Normal debugging is not allowed in a Dynamics 365 Business Central Production Environment as,
a) Cannot accept halting execution/stopping session on shared NST
b) Performance impact
c) Too powerful endpoint (e.g., deploy)
d) Common limitation for SaaS services
Snapshot debugging allows a delegated admin to record AL code that runs on the server, and once it has run, debug the recorded snapshot in Visual Studio Code.
For a delegated admin to create and download a snapshot file that exists on the server on behalf of an end-user, the delegated admin must be part of the D365 Snapshot Debug permission group.
1 - User Permissions
To enable snapshot debugging it is very important that the symbols on the tenant match the symbols on the server.
There are two template configurations for a snapshot, which are accessed by selecting Add Configuration in Visual Studio Code.
a) AL: Initialize a snapshot debugging session locally
b) AL: Initialize a snapshot debugging session on cloud
2 - Initialize a snapshot debugging
Choose whether to run the session on a cloud service or locally. The configuration file will now contain the following information:
userId: The GUID of the user on whose behalf a snapshot debugging will be started. 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.
sessionId: A session ID for the user specified above in userId.
snapshotVerbosity: Determines how much execution context to be recorded. If SnapPoint is specified, then only methods that hit a snappoint will be recorded.
3 - Initialize Snapshot Debugging with UserId
4 - Business Central Admin Center
5 - Session ID and User ID
When a configuration is defined, a snapshot debugging session can be initialized by pressing Ctrl+Shift+P and then selecting AL:Initialize Snapshot Debugging or by pressing F7.
To record the AL execution, the server will now wait for a connection to happen where the following rules apply:
a) If a sessionId is specified for a userId for a given tenant then it will be that session that will be snapshot debugged.
b) If only a userId is specified for a given tenant then the next session that is specified in the breakOnNext configuration parameter is snapshot debugged.
c) If no userId is specified then the next session on a given tenant that validates the breakOnNext parameter will be snapshot debugged.
Once a snapshot debugging session is initialized the snapshot debugging session counter on the status bar will be updated and look like this:
6 - Initialize Snapshot Debugging
7 - Snapshot Debugging Initializing succeeded
Clicking on the status bar icon or pressing Shift+F7 will bring up a list of all available snapshots.
The status list will show the state of a snapshot-debugged session.
A snapshot debugging session can be in the below states:
a) Initialized - A request is issued and the server is waiting for the next session to be snapshot debugged based on the above rules.
b) Started - You have attached to an end-user session to snapshot debug.
c) Finished - When the snapshot debugging session has finished.
d) Downloaded - When the snapshot file is downloaded.
8 - Snapshot Debugging Status Initialized
9 - Sample Code for Testing
10 - Open Production Environment
11 - Snapshot Debugging Started
12 - Perform Activity in Business Central Production Environment
13 - Activity Result
You can finish a snapshot debugging session by pressing Alt+F7. This brings up all snapshot sessions that have been started. Choosing one will close the session debugging on the server and download the snapshot file.
14 - Finish Snapshot Debugging
15 - Snapshot Debugging Finished
The snapshot is downloaded as a ZIP file to the .snapshots folder in your VS Code project. And the debug icon on the status bar will be orange now.
16 - Status Downloaded
Downloaded snapshot session can be debugged offline also using Shift + F7 or click debug status icon.
17 - Select the snapshot and start the Snapshot Debugging
It is based on call stack sequence, not real time execution.
Triggers may not be stepped to in the right order in "playback".
Breakpoints can be added and removed and they will be hit if given a breakpoint; the breakpoint is in the execution context of a recorded state. This means that if walking the execution stack for a breakpoint and the next stepped line is reached, then the code will break on the breakpoint.
You can investigate code and set snappoints in symbol AL (.dal) files
a) Initialized session closed if not started within 30 minutes.
b) If on a frame data to be serialized grows over 100 MB, it will not be collected.
c) Captured snspahsots are removed from BC server after 8 hours (periodic scheduler)
I hope this would help you a lot. Please also let me know your views.
Your valuable comments and feedback are appreciated.