Debug live ASP.NET Azure apps using the Snapshot Debugger
The Snapshot Debugger takes a snapshot of your in-production apps when code that you are interested in executes. To instruct the debugger to take a snapshot, you set snappoints and logpoints in your code. The debugger lets you see exactly what went wrong, without impacting traffic of your production application. The Snapshot Debugger can help you dramatically reduce the time it takes to resolve issues that occur in production environments.
Snappoints and logpoints are similar to breakpoints. Unlike breakpoints, snappoints do not halt the application when hit. Typically, capturing a snapshot at a snappoint takes 10-20 milliseconds.
Snapshot collection is available for the following web apps running in Azure App Service:
- ASP.NET applications running on .NET Framework 4.6.1 or later.
- ASP.NET Core applications running on .NET Core 2.0 or later on Windows.
Additionally, the Snapshot Debugger is only available for Visual Studio 2017 Enterprise version 15.5 or higher and Basic or higher App Service plans.
Start the Snapshot Debugger
Install Visual Studio 2017 Enterprise version 15.5 or later. If you are updating from a previous Visual Studio 2017 installation, run the Visual Studio Installer and check the Snapshot Debugger component in the ASP.NET and web development workload.
Open the project you would like to snapshot debug.
In order to snapshot debug, you need to open the same version of source code that is published to your Azure App Service.
In the Cloud Explorer (select View > Cloud Explorer), right click the Azure App Service your project is deployed to and select Attach Snapshot Debugger to start the Snapshot Debugger.
The first time you select Attach Snapshot Debugger, you are prompted to install the Snapshot Debugger site extension on your Azure App Service. This installation requires a restart of your Azure App Service.
Visual Studio is now in snapshot debugging mode.
The Application Insights site extension also supports Snapshot Debugging. If you encounter a "site extension out of date" error message, please see troubleshooting tips and known issues for snapshot debugging for upgrading details.
The Modules window shows you when all the modules have loaded for the Azure App Service (choose Debug / Windows / Modules to open this window).
Set a snappoint
In the code editor, click the left gutter next to a line of code you are interested in to set a snappoint. Make sure it is code that you know will execute.
Click Start Collection to turn on the snappoint.
You cannot step when viewing a snapshot, but you can place multiple snappoints in your code to follow execution at different lines of code. If you have multiple snappoints in your code, the Snapshot Debugger ensures that the corresponding snapshots are from the same end-user session, even if there are multiple users hitting your app.
Take a snapshot
When a snappoint is turned on, it will capture a snapshot whenever the line of code where the snappoint is placed is executed. This execution can be caused by a real request on your server. To force your snappoint to hit, you can also go to the browser view of your web site and take any actions required that cause your snappoint to be hit.
Inspect snapshot data
When the snappoint is hit, a snapshot appears in the Diagnostic Tools window. Choose Debug / Windows / Show Diagnostic Tools to open this window.
Double-click the snappoint to open the snapshot in the code editor.
From this view, you can hover over variables to view DataTips, use the Locals, Watches, and Call Stack windows, and also evaluate expressions.
The website itself is still live and end users are not impacted.Only one snapshot is captured per snappoint by default: after a snapshot is captured the snappoint turns off. If you want to capture another snapshot at the snappoint, you can turn the snappoint back on by clicking Update Collection.
You can also add more snappoints to your app and turn them on with the Update Collection button.
Set a conditional snappoint
If it is difficult to recreate a particular state in your app, consider whether the use of a conditional snappoint can help. You can use conditional snappoints to avoid taking a snapshot until the app enters a desired state, such as when a variable has a particular value you're interested in. You can set conditions using expressions, filters, or hit counts.
To create a conditional snappoint
Right-click a snappoint icon (the hollow ball) and choose Settings.
In the snappoint settings window, type an expression.
In the preceding illustration, the snapshot is only taken for the snappoint when
visitor.FirstName == "Dan".
Set a logpoint
In addition to taking a snapshot when a snappoint is hit, you can also configure a snappoint to log a message (that is, create a logpoint). You can set logpoints without having to redeploy your app. Logpoints are executed virtually and cause no impact or side effects to your running application.
To create a logpoint
Right-click a snappoint icon (the blue hexagon) and choose Settings.
In the snappoint settings window, select Actions.
In the Message field, you can enter the new log message you want to log. You can also evaluate variables in your log message by placing them inside curly braces.
If you choose Send to Output Window, when the logpoint is hit, the message appears in the Diagnostic Tools window.
If you choose Send to application log, when the logpoint is hit, the message appears anywhere that you can see messages from
ILoggerin .NET Core), such as App Insights.
- To learn how to inspect variables while viewing a snapshot, see Debugger Feature Tour.
- View the FAQ for snapshot debugging.
- View troubleshooting tips and known issues for snapshot debugging.
- If you want to view snapshots in Application Insights when your app hits an exception, you can do that. For more information, see Debug snapshots on exceptions in .NET apps. Application Insights supports Service Fabric apps in addition to Azure App Service.