How to install WSL and develop Linux applications on Windows using .NET C#, Visual Studio and the Avalonia extension

.NETLinuxDevOnWindows.md

WSL Installation

Install Ubuntu (Default)

1. Open PowerShell as Administrator and run wsl --install
2. Wait until the first components are installed and reboot !
3. After the reboot wait until the WSL installation has completely finished
4. Set up a username and password
5. Run sudo apt-get update && sudo apt-get upgrade

• Ubuntu (24.04) will be installed as default.

Install Debian (Optional)

1. Open PowerShell as Administrator and run wsl --install Debian
2. Wait until the WSL installation has completely finished
3. Set up a username and password
4. Run sudo apt-get update && sudo apt-get upgrade

• Debian (13.2) is now installed.

Install Fedora (Optional)

1. Open PowerShell as Administrator and run wsl --install FedoraLinux-43
2. Wait until the WSL installation has completely finished
3. Set up a username (and password)
4. Run sudo dnf check-update && sudo dnf upgrade

• Fedora (43) is now installed.

Visual Studio Components

Avalonia

1. In Visual Studio click Manage Extensions on the Extensions top menu
2. In the search box, type Avalonia, click 'Download' and follow the instructions

Enable .NET Debugging with WSL

1. Inside Visual Studio: Select Tools on top -> Get Tools and Features

• OR Using the Visual Studio Installer: Select Modify on your Visual Studio Version

2. Switch to the Individual components tab and search for WSL
3. Select .NET Debugging with WSL and hit Modify to install

Required Linux Packages

Ubuntu 24.04

• Update using sudo apt-get update && sudo apt-get upgrade

Missing libraries

• Install using sudo apt-get install libice6 libsm6

.NET 8.0 - 9.0 SDK

• Install using sudo apt-get install dotnet-sdk-9.0 dotnet-sdk-8.0

Debian 13.2 (Optional)

• Update using sudo apt-get update && sudo apt-get upgrade

Missing Libraries

• Install using sudo apt-get install curl gpg wget libice6 libsm6 libfontconfig1 libx11-6 libx11-dev

.NET 8.0 - 9.0 SDK

• Install using

wget https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get install dotnet-sdk-9.0 dotnet-sdk-8.0

Fedora 43 (Optional)

1. Check for updates using sudo dnf check-update
2. Update packages using sudo dnf upgrade

Missing Libraries

• Install using sudo dnf install awk curl gpg wget libICE libSM libX11 libX11-devel fontconfig freetype fontconfig-devel freetype-devel

.NET 8.0 - 9.0 SDK

• Install using sudo dnf install dotnet-sdk-9.0 dotnet-sdk-8.0

Create & Debug a project on WSL

Creating a project

1. Start Visual Studio and select Create a new project
2. Select C# as language, Linux as platform and Avalonia as project type
3. Select the .NET App or .NET MVVM App depending on your requirements
4. Give your project a name and select the .NET 8.0 or .NET 9.0 framework

Debugging the project on WSL

1. Select the Start Debugging ˅ (Context Menu) on top and select WSL

• This creates a launchSettings.json file inside a Properties folder in your project

2. Simply hit Start Debugging or press F5 to debug your project in the default WSL distribution

Debugging the project on multiple WSL distributions

• Open the created launchSettings.json file inside the Properties folder
• By default the file will look like :

{
  "profiles": {
    "AvaloniaApplication1": {
      "commandName": "Project"
    },
    "WSL": {
      "commandName": "WSL2",
      "distributionName": ""
    }
  }
}

• You can debug on another distribution by adding another launch profile like :

{
  "profiles": {
    "AvaloniaApplication1": {
      "commandName": "Project"
    },
    "WSL : Debian 13.2": {
      "commandName": "WSL2",
      "distributionName": "Debian"
    },
    "WSL : Ubuntu 24.04": {
      "commandName": "WSL2",
      "distributionName": "Ubuntu"
    },
    "WSL : Fedora 43": {
      "commandName": "WSL2",
      "distributionName": "FedoraLinux-43"
    }
  }
}

• WSL : Debian 13.2 defines the launch profile name
• commandName identifies the debug target to run
• distributionName targets a specific distribution

Deploying an application

1. Open a Developer Command Prompt where your .csproj project file is located
2. Execute dotnet publish YOURPROJECT.csproj --nologo --configuration Release --self-contained true --runtime linux-x64 --output "./out/linux-x64"

• The folder ./out/linux-x64 will be created and contains your application compiled for Linux x64
• You can attach /p:PublishSingleFile=true, this change produces a single file app on self-contained publish
• You can also attach /p:PublishTrimmed=true, this change will produce a trimmed app on self-contained publish

Packaging an application

Ubuntu / Debian

Please refer to this guide by Avalonia : https://docs.avaloniaui.net/docs/deployment/debian-ubuntu

Fedora

On Fedora

1. Install the required packaging tools on Fedora with sudo dnf install fedora-packager rpmdevtools rpmbuild mock gcc
2. Move to a free directory and create a RPM skeleton with rpmdev-setuptree
3. Change to the directory with cd ~/rpmbuild

On Windows

1. Rename the compiled build folder /out/linux-x64 to APPLICATION_NAME-VERSION

• Example: linux-x64 -> MyApp-1.0.0

2. Create a packaging folder inside the renamed compiled build folder
3. Add an PNG icon with the name of your application APPLICATION_NAME.png into the packaging folder
4. Add a Desktop shortcut for your application APPLICATION_NAME.desktop into the packaging folder, example :

[Desktop Entry]
Name=APPLICATION_NAME
Comment=APPLICATION_SHORT_DESCRIPTION
Icon=APPLICATION_NAME
Exec=APPLICATION_NAME
StartupWMClass=APPLICATION_NAME
Terminal=false
Type=Application
Categories=CATEGORY
GenericName=APPLICATION_NAME
Keywords=keyword1; keyword2; keyword3

• Replace APPLICATION_NAME, APPLICATION_SHORT_DESCRIPTION, CATEGORY and keywords with your project details
• Registered categories : https://specifications.freedesktop.org/menu/latest/category-registry.html
• You can validate the .desktop shortcut (on Fedora) with desktop-file-validate APPLICATION_NAME.desktop

5. Open a PowerShell Command Prompt on the parent folder of the compiled build folder
6. Create a compressed tarball .tar.gz using tar -czf build.tar.gz MyApp-1.0.0
7. Copy the created compressed tarball build.tar.gz into the SOURCES folder back on Fedora

Back on Fedora

1. Create a APPLICATION_NAME.spec file in the SPECS folder like :

Name:           APPLICATION_NAME
Version:        1.0.0
Release:        1%{?dist}
Summary:        APPLICATION_DESCRIPTION
License:        LICENSE
URL:            https://example.com
Source0:        build.tar.gz
BuildArch:      x86_64
Requires:       libX11, gtk3, libGL

%description
APPLICATION_DESCRIPTION.

%global debug_package %{nil}

%prep
%setup -q

%install
rm -rf %{buildroot}
mkdir -p %{buildroot}/opt/%{name}
cp -a * %{buildroot}/opt/%{name}/
mkdir -p %{buildroot}/usr/share/applications
install -m 644 packaging/APPLICATION_NAME.desktop %{buildroot}/usr/share/applications/
mkdir -p %{buildroot}/usr/share/icons/hicolor/256x256/apps
install -m 644 packaging/APPLICATION_NAME.png %{buildroot}/usr/share/icons/hicolor/256x256/apps/

%files
/opt/%{name}
/usr/share/applications/APPLICATION_NAME.desktop
/usr/share/icons/hicolor/256x256/apps/APPLICATION_NAME.png

%changelog
* DATE_TODAY YOUR_NAME - 1.0.0-1
- Initial package

• Replace APPLICATION_NAME, APPLICATION_DESCRIPTION, LICENSE, URL, DATE_TODAY and YOUR_NAME with your project details

2. Build with rpmbuild -ba SPECS/APPLICATION_NAME.spec

Error Resolving

• Error Unhandled exception. System.Exception: XOpenDisplay failed when testing in WSL :
  • Execute export DISPLAY=$(ip route | grep default | awk '{print $3}'):0.0 and restart your WSL session