Dynamics 365 Business Central: using snapshot debugging

One of the top requested features for Dynamics 365 Business Central from a long time is absolutely one: debugging the production environment! And now you can 🙂

Dynamics 365 Business Central version 17 introduces a feature called Snapshot Debugging. Snapshot Debugging allows a delegated admin to record AL code that runs on the server side and then debug the recorded snapshot in Visual Studio Code in an offline manner.

How does this feature work?

Imagine that I have deployed an extension to my online customer and this extension throws an error on code. I want to debug the cause of this error in order to fix it as soon as possible.

To show the snapshot debugging feature in action, I’ve deployed on my cloud sandbox the following code:

As you can see, in this extension there’s an action on the Customer List page that throws an error if the isError variable is true (process fail), otherwise it shows a message (the process is ok).

The customer is happy because it has my wonderful extension installed. But now he executes the marvellous extension’s code and… error! 😦

We need to react and understood the cause of this problem!

To debug the remote session, we first need to set a breakpoint (snappoint) on our code. Here I’ve placed a snappoint on the standard Microsoft’s code (OnOpenPage trigger of the Customer List) and then on my action:

To start a snapshot debugging session, you first need to add a snapshot configuration in your launch.json file. When adding a configuration, now you have the following two new options:

• AL: Initialize a snapshot debugging session locally
• AL: Initialize a snapshot debugging session on cloud

I select the AL: Initialize a snapshot debugging session on cloud option (I need to debug the cloud environment). When you start a snapshot debugging session, you can debug a specific session ID or you can debug a specific user ID (the GUID of the user on whose behalf a snapshot debugging will be started.).

In this case, I want to debug a specific user’s session so I check for the session ID to debug on the tenant’s Admin Center:

and then I set the debugging configuration as follows:

Here the sessionId parameter identifies the session where to attach the snapshot debugging.

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 directly pressing F7:

The snapshot debugger initialize request is sent to the environment and the snapshot is initialized:

On the bottom left corner of the status bar you can see the debugger icon that shows that a new snapshot session is available:

If you click on this icon (or Shift + F7) a list of available snapshots is listed:

Here the snapshot status can be as follows:

• Initialized: A request is issued and the server is waiting for the next session to be snapshot debugged based on the above rules.
• Started: You have attached to an end-user session to snapshot debug.
• Finished: When the snapshot debugging session has finished.
• Downloaded: When the snapshot file is downloaded.

If the snapshot debugging session status is started, you can connect to your user session and executes the code (all the process you want to monitor until you reach the final point, in my case the error message). When the process is finished to execute, you can select AL: Finish snapshot debugging on the server (or ALT+F7):

This action downloads the snapshot as a ZIP file to the .snapshots folder in your Visual Studio Code project (the location of a snapshot file is controlled by the al.snapshotOutputPath configuration parameter in VS Code):

Note the debug icon on the status bar (now yellow). By clicking on it, you can see the list of the downloaded snapshots:

You can now select the snapshot and enjoy the offline debugging:

Some important things to note/remember:

• Symbols on the tenant must match the symbols on the server, so please check (otherwise the snapshot debugging is not thrown)
• 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
• If a snapshot debugger session is started, it has to be finished after 10 minutes.
• If you’re using the sessionId parameter, check for the right user’s session ID (not always so easy, could be interesting to have this detail show on the user profile in Dynamics 365 Business Central too).

NOTE: This feature is actually enabled on sandbox environments and it will be enabled on production environments in a later Cumulative Update.