|
| 1 | +--- |
| 2 | +title: "Debug .NET Core apps in WSL 2" |
| 3 | +description: Learn to run and debug your .NET Core apps in WSL 2 without leaving Visual Studio. |
| 4 | +ms.date: "01/25/2021" |
| 5 | +ms.topic: "conceptual" |
| 6 | +helpviewer_keywords: |
| 7 | + - "debugging, linux" |
| 8 | + - "debugging, wsl2" |
| 9 | +author: "mikejo5000" |
| 10 | +ms.author: "mikejo" |
| 11 | +manager: jillfra |
| 12 | +monikerRange: '>= vs-2019' |
| 13 | +ms.workload: |
| 14 | + - "multiple" |
| 15 | +--- |
| 16 | + |
| 17 | +# Debug .NET Core Apps in WSL 2 with Visual Studio |
| 18 | + |
| 19 | +You can easily run and debug your .NET Core apps in Linux without leaving Visual Studio using WSL 2. If you are a cross-platform developer, you can use this method as a simple way to test more of your target environments. |
| 20 | + |
| 21 | +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](../debugger/remote-debugging-dotnet-core-linux-with-ssh.md), or with containers using the [Container Tools](../containers/overview.md). When production realism is your main concern, you should use one of those options. When an easy and fast inner-loop is more important, WSL 2 is a great option. |
| 22 | + |
| 23 | +You don’t have to choose just one method! 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's an issue. |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +- Visual Studio 2019 v16.9 Preview 1 or later versions with the .NET Core Debugging with WSL 2 optional component. |
| 28 | + |
| 29 | + The optional component is included by default with the .NET Core cross-platform or the ASP.NET and web development workloads. You must install one or both of these workloads. |
| 30 | + |
| 31 | +- Install [WSL 2](/windows/wsl/about). |
| 32 | + |
| 33 | +- Install the [distribution](https://aka.ms/wslstore) of your choice. |
| 34 | + |
| 35 | +## Start debugging with WSL 2 |
| 36 | + |
| 37 | +1. After you've installed the required components, 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: |
| 38 | + |
| 39 | +  |
| 40 | + |
| 41 | +1. Select this profile to add it to your *launchSettings.json*. |
| 42 | + |
| 43 | + Some of the key attributes in the file are shown in the following example. |
| 44 | + |
| 45 | + ```json |
| 46 | + "WSL 2": { |
| 47 | + "commandName": "WSL2", |
| 48 | + "launchBrowser": true, |
| 49 | + "launchUrl": "https://localhost:5001", |
| 50 | + "environmentVariables": { |
| 51 | + "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000", |
| 52 | + "ASPNETCORE_ENVIRONMENT": "Development" |
| 53 | + }, |
| 54 | + "distributionName": "" |
| 55 | + } |
| 56 | + ``` |
| 57 | + |
| 58 | + Once you select the new profile, the extension checks that your WSL 2 distribution is configured to run .NET Core apps, and helps you install any missing dependencies. Once you've installed these dependencies, you are ready to debug in WSL 2. |
| 59 | + |
| 60 | +1. Start debugging as normal, and your app will run in your default WSL 2 distribution. |
| 61 | + |
| 62 | + An easy way to verify that you're running in Linux is to check the value of `Environment.OSVersion`. |
| 63 | + |
| 64 | +>[!NOTE] |
| 65 | +> 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](https://aka.ms/wsldotnet) and [Curl](https://curl.haxx.se/). |
| 66 | + |
| 67 | +## Choose a specific distribution |
| 68 | + |
| 69 | +By default, the WSL 2 launch profile uses 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're debugging a web app and want to test it on Ubuntu 20.04, your launch profile would look like: |
| 70 | + |
| 71 | +```json |
| 72 | +"WSL 2": { |
| 73 | + "commandName": "WSL2", |
| 74 | + "launchBrowser": true, |
| 75 | + "launchUrl": "https://localhost:5001", |
| 76 | + "environmentVariables": { |
| 77 | + "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000", |
| 78 | + "ASPNETCORE_ENVIRONMENT": "Development" |
| 79 | + }, |
| 80 | + "distributionName": "Ubuntu-20.04" |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +## Target multiple distributions |
| 85 | + |
| 86 | +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: |
| 87 | + |
| 88 | +```json |
| 89 | +"WSL 2 : Debian": { |
| 90 | + "commandName": "WSL2", |
| 91 | + "distributionName": "Debian" |
| 92 | +}, |
| 93 | +"WSL 2 : Ubuntu 18.04": { |
| 94 | + "commandName": "WSL2", |
| 95 | + "distributionName": "Ubuntu-18.04" |
| 96 | +}, |
| 97 | +"WSL 2 : Ubuntu 20.04": { |
| 98 | + "commandName": "WSL2", |
| 99 | + "distributionName": "Ubuntu-20.04" |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +With these launch profiles, you can easily switch back and forth between your target distributions, all without leaving the comfort of Visual Studio. |
| 104 | + |
| 105 | + |
| 106 | + |
| 107 | +## WSL settings in the launch profile |
| 108 | + |
| 109 | +The following table shows the settings that are supported in the launch profile. |
| 110 | + |
| 111 | +|Name|Default|Purpose|Supports Tokens?| |
| 112 | +|-|-|-|-| |
| 113 | +|executablePath|dotnet|The executable to run|Yes| |
| 114 | +|commandLineArgs|The value of the MSBuild property TargetPath mapped to the WSL environment|Command line arguments passed to executablePath|Yes| |
| 115 | +|workingDirectory|For console apps: {*OutDir*}</br>For web apps: {*ProjectDir*}|The working directory in which to start debugging|Yes| |
| 116 | +|environmentVariables||Key Value pairs of environment variables to set for the debugged process.|Yes| |
| 117 | +|setupScriptPath||Script to be run before debugging. Useful for running scripts like ~/.bash_profile.|Yes| |
| 118 | +|distributionName||Name of the WSL distribution to use.|No| |
| 119 | +|launchBrowser|false|Whether or not to launch a browser|No| |
| 120 | +|launchUrl||Url to launch if launchBrowser is true|No| |
| 121 | + |
| 122 | +Supported tokens: |
| 123 | + |
| 124 | +{*ProjectDir*} - The path to the project directory |
| 125 | + |
| 126 | +{*OutDir*} - The value of the MSBuild property `OutDir` |
| 127 | + |
| 128 | +>[!NOTE] |
| 129 | +> All paths are for WSL not Windows. |
0 commit comments