Configuring WSL2 for .NET Development

Developers can access the power of both Windows and Linux at the same time on a Windows machine. The Windows Subsystem for Linux (WSL) lets developers install a Linux distribution (such as Ubuntu, OpenSUSE, Kali, Debian, Arch Linux, etc) and use Linux applications, utilities, and Bash command-line tools directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.

This guide is about setting up a development environment for .NET applications inside WSL with NodeJs (because most of you guys use a front end JS framework these days!)

Using WSL for developement is also good if you are planning to migrate all your Windows App Services in Azure to Linus App Services.

✅ Prerequisites

• Install Windows Terminal (Get Windows Terminal from the Microsoft Store)
• Basic knowledge about Linux file system (optional)

⏏️ Enable WSL2 in Windows

Open windows search and look for “Turn Windows features on or off”, then enable both

• Virtual Machine Platform
• Windows Subsystem for Linux

Or else you can just run the following powershell command.

wsl --install

Restart Windows after installing WSL

After that open Microsoft Store and install the latest ubuntu distribution

After installing ubuntu click Open. It will ask for a username and a password for your Ubuntu installation.

Update the Linux kernal if prompted just like in the below image. Manual installation steps for older versions of WSL

Manual installation steps for older versions of WSL

Also now Windows terminal has a new entry to launch WSL Terminal (Ubuntu in our case).

Now you can check if the Ubuntu was installed correctly using this command on Powershell

wsl -l -v

You need to have an output like,

Move on to the next section if you get this output. But if your output is different from above, just like in the below image, we need to change that.

You need to make the Ubuntu distro as the default distro and upgrade the version (WSL vesion) to 2 (If it’s on version 1, just like in the above image). To do that run following 2 commands in sequence.

wsl --setdefault <DistributionName>

In our case it’s wsl --setdefault Ubuntu-22.04

wsl --set-version <DistributionName> 2

In our case it’s wsl --set-version Ubuntu-22.04 2

Refer Check which version of WSL you are running and Upgrade version from WSL 1 to WSL 2

Install WSL

Final result of wsl -l -v should look like this

🔦 Install debugging tools from VS installer

Using “Visual Studio Installer” add “.NET debugging with WSL” component;

Click “Modify” under the Visual Studio version which you want to run in WSL. In the open component installation window, choose “Individual Components” tab and type “WSL” within the search box. Select ‘.NET Debugging with WSL’ and click “Modify”

🔌 Install dotnet SDKs

Before installing we need to tell WSL to use Microsoft packages instead of Ubuntu packages. To do that open a terminal on WSL and configure Microsoft PPA by running the following commands:

Note that we’re using 22.04 version of the package list because we installed Ubuntu 22.04 version. Install .NET on Ubuntu — .NET

Install .NET on Ubuntu - .NET

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb 
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

To install the .NET SDK, run the following commands:

sudo apt-get update && \
  sudo apt-get install -y dotnet-sdk-7.0

Run dotnet --list-sdks to check if installed correctly. Output of this command should be like,

7.0.101 [/usr/share/dotnet/sdk]

After that if you want a specific dotnet version ( specified in global.json e.g: 6.0.200 ) you can do that using dotnet-install script Refer: dotnet-install scripts — .NET CLI

dotnet-install scripts - .NET CLI

⚠️ Important!

Only use dotnet-install scripts after installing it using sudo apt-get install as in the previous step, because the scripts will not add the installation path to the Ubuntu $PATH variable. After installing the latest SDK using apt-get install follow below steps.

Install curl

sudo apt update && sudo apt install curl

Download script.

curl -L -O https://dot.net/v1/dotnet-install.sh

Get execution permission.

sudo chmod +x ./dotnet-install.sh

Install dotnet SDK specific version.

sudo ./dotnet-install.sh -v 6.0.200 --install-dir /usr/share/dotnet

Check for installed SDKs

dotnet --list-sdks

⚙️ Install NodeJs

Since here also we want to install specific versions of Node, we are using Node Version Manager (NVM) Refer: GitHub — nvm-sh/nvm: Node Version Manager — POSIX-compliant bash script to manage multiple active node.js versions

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active…

⚠️ Important!

Open new WSL Terminal window.

Get nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

Make sure our terminal (bash) picks up then nvm command.

source ~/.bashrc

You can check available node versions using nvm list-remote and select the version you want.

Install Node specific version (I wanted 16.15.0 so I’m installing that version)

nvm install v16.15.0

Check if installed correctly using node -v

🔧 Create certificates

We need run few commands to make sure our browsers trust WSL certificates. Note that this is a one time operation.

Export Windows development certificates using this command on Windows Powershell Refer: Enforce HTTPS in ASP.NET Core

Enforce HTTPS in ASP.NET Core

dotnet dev-certs https -ep https.pfx -p <any-password> --trust

Replace <any-password> with a password that you want and remember it, because we are going to need it in the next step. Note that we’re running this command in the Windows OS using Powershell.

Next step is to import this certificate to WSL. So open a WSL Terminal and execute this command.

dotnet dev-certs https --clean --import <path-to-pfx> --password <password-from-above-step>

Change <path-to-pfx> to the path where the https.pfx file created in the previous step. (It is created on the same directory where you ran the command). <password-from-above-step> is the <any-password> that you set in the previous command.

If you open the same location from both Windows Powershell and WSL Terminal, you don’t need to give a path, only the file name (https.pfx).

Also execute this after everything.

dotnet dev-certs https --trust

🚀 Run applications

Now inside Visual Studio you will the WSL option to run the application. Use that to start the application.

If you’re running the SPA application separately or not using Visual Studio, you may need to open VSCode in WSL. Read more about that here. It’s very straight forward, If you ran in to any issues drop a comment to this ..

Developing in the Windows Subsystem for Linux with Visual Studio Code

You have access to Windows partitions in WSL at /mnt/. As an example if the project is in D drive folder Adra, you can navigate to that location using WSL terminal by typing cd /mnt/d/Adra

But it is advised to move your source code to /home directory for improved performance rather than keeping them in the Windows file system.

🚫 Common problems

NET::ERR_CERT_AUTHORITY_INVALID

If you get the following Error while navigating to localhost, try doing these steps in order in an WSL terminal.

Stop all development servers, Kestral, Webpack etc.

Remove all certificates created by MAUI dev server.

sudo rm -rf /home/<username>/.aspnet/https/*

Remove all certificates created by dotnet

sudo rm -rf /usr/local/share/ca-certificates/aspnet/*

dotnet dev-certs https --clean

Now execute all 3 commands mentioned in Create certificates section.

Read more if you still get any errors for certificates here.

Enforce HTTPS in ASP.NET Core

Logon failure: the user has not been granted the requested logon type

If you get this error, go to Services, (⊞ Win + R and type services.msc then hit Enter)

Then restart Hyper-V Host Compute Service

I’m gonna wrap things up there, If you ran into any issues drop a comment to this. If you were able to succefully configure WSL then leave a “Clap”!