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
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
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
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
⚠️ Important!
Only use
dotnet-install
scripts after installing it usingsudo 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 usingapt-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
⚠️ 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
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 ..
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.
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”!