Debug Your .NET Core Apps in WSL 2 with Visual Studio

Nathan Carlson

Are you a .NET Core developer who loves working in Windows and Visual Studio, but needs to test your app in Linux? Are you a cross-platform developer that needs an easy way to test more of your target environments? Have you already discovered the benefits of WSL 2, but need a way to integrate it into your inner loop? Have I got an extension for you! The .NET Core Debugging with WSL 2 – Preview extension gives you the ability to run and debug your .NET Core apps in WSL 2 without leaving Visual Studio.

When would I want to debug in WSL 2?

For a Windows .NET user targeting Linux, WSL 2 lives in a sweet spot between production realism and productivity. In Visual Studio you can already debug in a remote Linux environment using the Remote Debugger, or with containers using the Container Tools. When production realism is your main concern, you should use one of those. When an easy and fast inner-loop is more important, WSL 2 is a great option.

You don’t have to choose just one! You can have a launch profile for Docker and WSL 2 in the same project and pick whichever is appropriate for a particular run. And once your app is deployed, you can always use the Remote Debugger to attach to it if there is an issue.

Getting Started with .NET Core Debugging with WSL 2 – Preview

Before using the extension, be sure to install WSL 2 and the distribution of your choice. After you have installed the extension, when you open an ASP.NET Core web app or .NET Core console app in Visual Studio, you’ll see a new Launch Profile named WSL 2:

WSL 2 launch profile in the launch profile list

Selecting this profile will add it to your launchSettings.json, and will look something like:

"WSL 2": {
    "commandName": "WSL2",
    "launchBrowser": true,
    "launchUrl": "https://localhost:5001",
    "environmentVariables": {
        "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
        "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "distributionName": ""
}

Once the new profile is selected, the extension checks that your WSL 2 distribution is configured to run .NET Core apps, and helps you install any missing dependencies. Once all the dependencies are installed, you are ready to debug in WSL 2. Simply start Debugging as normal, and your app will now be running in your default WSL 2 distribution. An easy way to verify that you are running in Linux is to check the value of Environment.OSVersion.

Note: Only Ubuntu and Debian have been tested and are supported. Other distributions supported by .NET Core should work but require manually installing the .NET Core Runtime and Curl.

Using a specific distribution

By default, the WSL 2 launch profile will use the default distribution as set in wsl.exe. If you want your launch profile to target a specific distribution, regardless of that default, you can modify your launch profile. For example, if you are debugging a web app and want to test it on Ubuntu 20.04, your launch profile would look like:

"WSL 2": {
    "commandName": "WSL2",
    "launchBrowser": true,
    "launchUrl": "https://localhost:5001",
    "environmentVariables": {
        "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
        "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "distributionName": "Ubuntu-20.04"
}

Targeting multiple distributions

Going one step further, if you are working on an application that needs to run in multiple distributions and you want a quick way to test on each of them, you can have multiple launch profiles. For instance, if you need to test your console app on Debian, Ubuntu 18.04, and Ubuntu 20.04, you could use the following launch profiles:

"WSL 2 : Debian": {
    "commandName": "WSL2",
    "distributionName": "Debian"
},
"WSL 2 : Ubuntu 18.04": {
    "commandName": "WSL2",
    "distributionName": "Ubuntu-18.04"
},
"WSL 2 : Ubuntu 20.04": {
    "commandName": "WSL2",
    "distributionName": "Ubuntu-20.04"
}

With these launch profiles, you can easily switch back and forth between your target distributions, all without leaving the comfort of Visual Studio:

Multiple WSL 2 launch profiles in the launch profile list

Give it a try today!

So, if you love working in Visual Studio, but need to test your app in Linux, go to the Visual Studio Marketplace to install the extension today. Please use the marketplace to ask any questions and give us your feedback to let us know how useful this extension is.

16 comments

Discussion is closed. Login to edit/delete existing comments.

  • Nicola Iarocci 0

    That’s nice. What I am still missing is a way to open projects (and solutions) in Visual Studio from WSL, like I can do with VSCode and its Remote Extension. Basically I want to keep all my repos and source code (windows-only projects like legacy winforms too) on the linux side, so I can still leverage my linux-cli-fu. VSCode already allows to do that, but sometimes you really need VS (winforms, UWP, etc.)

    • Szymon Dolny 0

      You can map wsl2 to a standard drive with a letter. It will work in VS this way

      • robert orozco 0

        vs2019 16.8 can use a mapped network drive to build from a directory like /home/sln_src. I have issue with debug adapter connecting. I get a message where cwd is always prefixed with /mnt/x/… (where x is my mapped drive) and can not find the path to begin debugging. Adjusting directory in wsl2 in launch.json file does not seem to help. i can single step debug in WSL2 , verified with top, if src is located in Windows directory. Not sure where to configure cwd for debug adapter in wsl2 to use mapped drive letter correctly.

        I was hoping this was fixed 9 mos. later. This link https://www.docker.com/blog/docker-desktop-wsl-2-best-practices/ describes how to be able to point to your sln when it is located in wsl2. Supposed best practice to locate project src in wsl2 directory structure. Yes I can edit files and get sln to build.
        What is the use of being able to edit and build in wsl2 directory structure if you cannot debug there with vs2019? How about vs2022?

        • Nathan CarlsonMicrosoft employee 0

          Currently the extension only support opening projects that are stored in the windows disks (it leverages WSLs automount feature). If opening from a network location is something you need please add it as a suggestion on Developer Community.

    • Nathan CarlsonMicrosoft employee 0

      This extension in not planning to offer the same experience as VSCode’s remote WSL Extension. If you are interested in having that in VS, please add it as a suggestion on Developer Community.

  • Moritz Beutel 0

    But is any of this specific to WSL 2? Wouldn’t it work with WSL 1 as well?

    • Nathan CarlsonMicrosoft employee 0

      The extension does rely on APIs introduced with WSL 2, but should still work against a version 1 distribution (as long as you are using the latest wsl.exe).

  • vincent habonimana 0

    That’s nice

  • Roel Brook 0

    Finally. Vs code had an extension for this for a while now. Glad to see there’s now one for vs as well.

  • Ioannis Kyriakidis 0

    Awesome! I would give it a try 🙂

  • Juan Carlos Ganzo Dominguez 0

    it’s amazing

  • Byron Adams 0

    When I do “dotnet run” from a command prompt in WSL2, I can run my console app even though the source is still in my windows side… I like that. However, when I open the same source from Visual Studio 2019 with the extension and profile WSL2 I get:
    Exception thrown: ‘System.UnauthorizedAccessException’ in System.IO.FileSystem.dll
    M?a?i?n? ?E?r?r?o?r?:? ?A?c?c?e?s?s? ?t?o? ?t?h?e? ?p?a?t?h? ?’?/?u?s?r?/?s?h?a?r?e?/?d?o?t?n?e?t?/?x?D?B?/?T?e?m?p?’? ?i?s? ?d?e?n?i?e?d?.?
    The ?? make it hard to read there error. (I’ll have to write a tool to remove all the ??)

    • Nathan CarlsonMicrosoft employee 0

      I’ve never seen an error like this in my testing. Do you see this on F5 and Ctrl+F5? Where do you see the error? Assumign this happens for F5, if you turn off Just My Code and Turn on first change exception handling does that reveal the issue?

      • Byron Adams 0

        I got that error using F5, but Ctrl+F5 (thank you for the tip) helped me see my error more clearly.
        The problem was with my code. I start a console app and use the app name to create some sub folders, but it’s using “dotnet” and trying to work below that.
        Coding for Linux, is making me rethink some code paths.

  • Alex 0

    Hi Nathan, really nice being able to deploy and debug in WSL2. However I’m having weird issue, do you have any suggestion on how to fix this?

    -------------------------------------------------------------------
    You may only use the Microsoft .NET Core Debugger (vsdbg) with
    Visual Studio Code, Visual Studio or Visual Studio for Mac software
    to help you develop and test your applications.
    -------------------------------------------------------------------
    A fatal error was encountered. The library 'libhostpolicy.so' required to execute the application was not found in '/mnt/c/GIT/app/BE.App/bin/Dev/netcoreapp3.1/win-x64/'.
    Failed to run as a self-contained app. If this should be a framework-dependent app, specify the appropriate framework in /mnt/c/GIT/app/BE.App/bin/Dev/netcoreapp3.1/win-x64/BE.App.runtimeconfig.json.
    The target process exited without raising a CoreCLR started event. Ensure that the target process is configured to use .NET Core. This may be expected if the target process did not run on .NET Core.
    The program 'dotnet' has exited with code 131 (0x83).
    

    Getting in Output that all is set properly

    Checking WSL 2 configuration: Success
    Checking WSL 2 configuration: Success
    Checking HTTPs configuration: Success
    Checking HTTPs configuration: Success
    Checking User Secrets configuration: Success
    Checking User Secrets configuration: Success
    Checking Visual Studio debugger installation: Success
    Checking Visual Studio debugger installation: Success
    • Nathan CarlsonMicrosoft employee 0

      Looking at your output it would appear that your project has the property:

      <RuntimeIdentifier>win-x64</RuntimeIdentifier>

      I would recommend removing that property (if it is not needed) or swapping it out for:

      <RuntimeIdentifiers>linux-x64;win-x64</RuntimeIdentifiers>

      To allow for restoring and building against windows and linux.

Feedback usabilla icon