Windows Subsystem for Linux

With the Windows 10 Creators Update (Windows version 10.0.15063), you can use Visual Studio Code to debug .NET core applications on Windows Subsystem for Linux (WSL).

This page will walk you through the steps required to debug a .NET core application on WSL.

Prerequisites

• Windows 10 Creators Update or newer with Windows Subsystem for Linux and Bash installed.
• .NET Core on WSL
• Visual Studio Code
• Microsoft C# extension for VSCode.

Be sure to check the version of Ubuntu on WSL. The Windows 10 Creators Update comes with 16.04.2 LTS version of Ubuntu. You can confirm that by running the command below.

~$ cat /etc/os-release  | grep  -i version
VERSION="16.04.2 LTS (Xenial Xerus)"
VERSION_ID="16.04"
VERSION_CODENAME=xenial

If you had upgraded to Windows Creators update and already had WSL installed, you might still have Ubuntu 14 in the WSL. If the version is 14, run the following commands in a cmd prompt to reinstall and update WSL.

Note: These commands remove everything in your current WSL. Please be sure to save any files you wish to keep.

lxrun /uninstall /full
lxrun /install

Go to https://www.microsoft.com/net/learn/get-started/linux/ubuntu16-04 follow the instructions to install .NET core in WSL. You will need to follow the 16.04 instructions.

Install the debugger

You can download a copy of the debugger with:

sudo apt-get install unzip
curl -ssl https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l ~/vsdbg

This will download and install the debugger at ~/vsdbg/vsdbg. This will be used later as the debuggerPath.

Configuring debugging

VS Code uses json files to configure how your application is debugged (both for launch and attach) as well as built. There are two files that we need to configure --

• <your-open-folder>/.vscode/launch.json: This provides an array of different configurations you can use to launch your application. There is a drop down in the Debug view for selecting which configuration is active.
• <your-open-folder>/.vscode/tasks.json: This provides an array of different tasks, like building your application, that you can execute. Debug configurations can link to one of these tasks through the preLaunchTask property.

The rest of this page will provide examples of how launch.json and tasks.json should be configured to support WSL.

Sample launch.json configuration for launch

        {
           "name": ".NET Core WSL Launch",
           "type": "coreclr",
           "request": "launch",
           "preLaunchTask": "publish",
           "program": "/mnt/c/temp/dotnetapps/wslApp/bin/publish/wslApp.dll",
           "args": [],
           "cwd": "/mnt/c/temp/dotnetapps/wslApp",
           "stopAtEntry": false,
           "console": "internalConsole",
           "pipeTransport": {
               "pipeCwd": "${workspaceRoot}",
               "pipeProgram": "bash.exe",
               "pipeArgs": [ "-c" ],
               "debuggerPath": "~/vsdbg/vsdbg"
           }
       }

Sample 'publish' task for tasks.json (needed for launching)

{
    "version": "2.0.0",
    "tasks": [
        ...,
        {
            "label": "publish",
            "command": "dotnet",
            "type": "process",
            "args": [
                "publish",
                "${workspaceFolder}/wslApp.csproj",
                "-o",
                "${workspaceFolder}/bin/publish"
            ]
        }
    ]
}

The sample application shown here was created in the Windows path C:\temp\dotnetapps\wslApp. WSL by default allows windows paths to be accessible through /mnt/<driveletter>/<path>, so the path above is accessible as /mnt/c/temp/dotnetapps/wslApp from WSL.

Notes:

1. preLaunchTask executes dotnet publish, which builds the project on Windows. Since coreclr is cross-platform, the binary can be executed on WSL without any extra work.
2. pipeProgram is set to bash.exe.
3. debuggerPath points to vsdbg, the coreclr debugger.
4. This will not support programs that want to read from the console.

Sample launch.json configuration for attach

       {
           "name": ".NET Core WSL Attach",
           "type": "coreclr",
           "request": "attach",
           "processId": "${command:pickRemoteProcess}",
           "pipeTransport": {
               "pipeCwd": "${workspaceRoot}",
               "pipeProgram": "bash.exe",
               "pipeArgs": [ "-c" ],
               "debuggerPath": "~/vsdbg/vsdbg",
               "quoteArgs": true
           }
       }

Notes:

1. "processId": "${command:pickRemoteProcess}" lists the processes running on WSL using the pipe program.
2. quoteArgs will quote any arguments and debugger commands with spaces if set to true.
3. Use sourceFileMap to map sources if they are available in a different location than where they were built. If you build your project in Linux, make sure to add a map from the /mnt drive letters. Example: "sourceFileMap": { "/mnt/c/": "c:\\" }
4. File and paths are case sensitive in Linux.

Also see

Configuring C# Launch.json

C++ debugging in WSL with VSCode C++ Extensions.