Remotely Debugging ASP.NET Core Containers on OpenShift With VS Code

Visual Studio allows for graphical remote debugging of ASP.NET Core apps with Docker Tools for Windows. Since Visual Studio supports SSH, you can remotely debug ASP.NET Core processes running on the Linux host. It used to be that if you installed and set up an SSH server on a Docker container, you could remotely debug with Visual Studio.

However, it’s strongly not recommended due to security reasons. Now I’ll explain to you how to remotely debug your ASP.NET Core on OpenShift with Visual Studio Code by using the oc exec command instead of installing SSH servers on Docker containers. You can use Microsoft's proprietary debugger engine vsdbg with Visual Studio Code (or other Visual Studio products). Visual Studio Code can integrate commands other than SSH for the debugger transport protocol.

Install and Set Up vsdbg on Your Docker Containers

To follow the steps below, you may have to deploy your ASP.NET Core app on OpenShift. If you haven’t done so, you can use this example project. Once the application pod runs, you’ll install vsdbg on this pod. The dotnet image version 2.0-7 or later has an unzip command. You can install vsdbg with the steps below.

$ export POD_NAME=<pod_name>
$ oc rsh $POD_NAME
sh-4.2$  curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /opt/app-root/vsdbg -r linux-x64
Info: Creating install directory
Using arguments
    Version                    : 'latest'
    Location                   : '/opt/app-root/vsdbg'
    SkipDownloads              : 'false'
    LaunchVsDbgAfter           : 'false'
    RemoveExistingOnUpgrade    : 'false'
Info: Using vsdbg version '15.1.10630.1'
Info: Previous installation at /opt/app-root/vsdbg not found
Info: Using Runtime ID 'linux-x64'
Downloading https://vsdebugger.azureedge.net/vsdbg-15-1-10630-1/vsdbg-linux-x64.zip
Info: Successfully installed vsdbg at '/opt/app-root/vsdbg'

If you use an older version of a dotnet image, an alternative way is installing vsdbg on your local machine and transferring it.

$ export POD_NAME=<pod_name>
$ curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l ./vsdbg -r linux-x64
$ oc rsync ./vsdbg $POD_NAME:/opt/app-root/app/

The PID of a dotnet process is also required. It’s usually 1, but confirm with the command below, just in case.

$ oc exec $POD_NAME -- ps aux
USER        PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
default       1  0.0  0.5 21251236 75376 ?      SLsl Sep29   0:24 dotnet app.dll
default      48  0.0  0.0  17748  2016 ?        Ss+  Sep29   0:00 /bin/sh
default   25663  0.0  0.0  53424  1936 ?        Rs   05:47   0:00 ps aux

Now the pod is ready to debug.

Set Up Your Local Machine

You should have the same code as the one deployed. If you use the .NET example app, clone the code and check out the dotnetcore-2.0 branch.

$ git clone https://github.com/redhat-developer/s2i-dotnetcore-ex.git
$ cd s2i-dotnetcore-ex
$ git checkout dotnetcore-2.0

Now open the project with Visual Studio Code.

$ code app

Then open a .vscode/launch.json file or create it if it hasn’t been created. Then add the following JSON as an element of the configuration array.

{
    "name": ".NET Core OpenShift Pod Remote Attach",
    "type": "coreclr",
    "request": "attach", 
    "processId": "",
    "pipeTransport": {
        "pipeProgram": "oc", 
        "pipeArgs": [ "exec", "-it", "<pod_name>", "--"], 
        "quoteArgs":false, 
        "debuggerPath": "/opt/app-root/vsdbg/vsdbg", 
        "pipeCwd": "${workspaceRoot}"
    },
    "justMyCode":false,
    "sourceFileMap": { "/opt/app-root/src": "${workspaceRoot}"}
}

Visual Studio Code will launch the process specified by pipeProgram and pipeArgs as transferring remote debug commands. debuggerPath is a full path of vsdbg. If you install at another location, it should be changed. If your application builds with the Release configuration, which is a default for s2i-dotnetcore, justMyCode should be false. Since the s2i-dotnetcore builds your source located at /opt/app-root/src, you should specify this path at sourceFileMap. Please note this is the path where your project is located when it’s built. If you build and deploy via .NET Core Runtime image, the application code has no source code. However, remote debug will work if you specify the sourceFileMap as above.

Now you're ready for remote debugging.

Start Remote Debugging

You can start remote debugging by selecting .NET Core OpenShift Pod Remote Attach in the debug menu and clicking the debug start menu or F5 key. You’ll find log messages and the remote debug icons once it’s connected.

Let’s put in a breakpoint. Contoller/HomeContoller.cs is easy to test.

When you’re accessing the about page...

...the debugger stops at the breakpoint.

You can see the local variables and stack trace, set endpoints, and so on. Let’s enjoy remote debugging!