Remote Debugging Apps

What is it?

Want to be able to set breakpoints on an app that's running in Cloud Foundry just like debugging on your local machine? The Tanzu Toolkit for Visual Studio extension adds a new button to the context menu for projects in Visual Studio which allows them to be deployed to Tanzu Platform with remote debug capabilities.

Where can I find it?

Right-click on your project in the solution explorer and look for the "Remote Debug on Tanzu Platform" button.

How do I use it?

Visual learner? Here's a demo video that shows a net5.0 web app being debugged remotely on both linux and windows.

remote-debug-windows-linux-demo.mp4

Clicking the "Remote Debug on Tanzu Platform" button will attempt to find a deployed app which -- by default -- has the same name as the project in the Solution Explorer. If no such app is found (among the list of apps visible to the user who is logged in), a dialog window will prompt you to select an existing app (that may be named differently than the selected project) to start remotely debugging. If you'd prefer to push a new version of the selected project for remote debugging instead, click 'Push New App to Debug' to be shown options for configuring that new app deployment.

How do I stop a remote debugging session?

To stop remote debugging while keeping the app running, use the "Detach All" button found under Visual Studio's "Debug" menu

Be warned! Using the rectangular stop button will stop the debugging process, but it will also stop the running (app) process it's attached to. If this happens, Tanzu Platform should restart the app as soon as it recognizes the crash and you should only notice a short window of app downtime.

What's going on behind the curtain?

In this context, configuring an app for remote debugging means including these additional components with the final app binaries that get pushed to the platform:

1. PDB files
   • These are important because they provide a mapping between source code and the compiled binary -- this mapping is essential for allowing breakpoints to be hit at a particular point in the execution of the app.
   • These are generated as a result of publishing the app in "Debug" mode via dotnet publish -c Debug
2. The Visual Studio remote debug agent ("vsdbg")
   • This tool is responsible for starting the debugging process for an app that has PDB files associated with it -- it's a necessary prerequisite for attaching to a process for remote debugging from Visual Studio
   • This is installed in a 2-step process: first, downloading an installer script from Microsoft, then invoking that installer script to acquire the right version of vsdbg for the app/IDE

Once an app is successfully running on Tanzu Platform with PDB files included and vsdbg installed, Visual Studio can attempt to attach to the remote app process using the DebugAdapterHost.Launch command. This command attempts to establish communication with the remote process over ssh using a configuration file that specifies how the connection should be made. Tanzu Toolkit for Visual Studio creates a temporary config file (named "launch.json") when setting up this connection and deletes it after the remote debugging session ends. Here is an example of one such "launch.json" configuration file:

{
    "version": "0.2.0",
    "adapter": "c:\\users\\awoosnam\\appdata\\local\\microsoft\\visualstudio\\17.0_a4444530exp\\extensions\\vmware\\tanzu toolkit for visual studio 2022\\0.0.4\\Resources\\cf7.exe",
    "adapterArgs": "ssh WebApplication1 -c \"c:\\Users\\vcap\\app\\vsdbg\\vsdbg.exe --interpreter=vscode\"",
    "languageMappings": {
        "C#": {
            "languageId": "3F5162F8-07C6-11D3-9053-00C04FA302A1",
            "extensions": [
                "*"
            ]
        }
    },
    "exceptionCategoryMappings": {
        "CLR": "449EC4CC-30D2-4032-9256-EE18EB41B62B",
        "MDA": "6ECE07A9-0EDE-45C4-8296-818D8FC401D4"
    },
    "configurations": [
        {
            "name": ".NET Core Launch",
            "type": "coreclr",
            "processName": "WebApplication1.exe",
            "request": "attach",
            "justMyCode": false,
            "cwd": "/home/vcap/app/vsdbg",
            "logging": {
                "engineLogging": true
            }
        }
    ]
}