How to Run and Debug WinForms & WPF Applications on Linux Using WSL2

Running Windows desktop applications on Linux has long been a challenge for developers working in cross-platform environments. With recent advancements in the Windows Subsystem for Linux (WSL2), it's now possible to run and debug WinForms and WPF applications directly in Linux. This guide walks through the complete process of setting up your environment, running applications, and configuring debugging tools for both Visual Studio and Visual Studio Code.

Prerequisites and Environment Setup

Before diving into running WinForms and WPF applications on Linux, you'll need to set up your environment properly. This guide uses Ubuntu 20.04 on WSL2 with kernel version 5.10. The key component enabling Windows applications to run on Linux is Wine, a compatibility layer that translates Windows system calls to Linux system calls.

Installing Wine on WSL2

Wine is not an emulator, sandbox, or virtualization software—it's a compatibility layer that allows Windows applications to run natively on Linux. Here's how to install Wine 6 (the stable version at the time of writing) on your WSL2 Ubuntu installation:

Enable 32-bit package installation: `sudo dpkg --add-architecture i386`
Download and add the Wine repository key: `wget -nc https://dl.winehq.org/wine-builds/winehq.key && sudo apt-key add winehq.key`
Add the official Wine repository: `sudo add-apt-repository 'deb https://dl.winehq.org/wine-builds/ubuntu/ focal main'`
Update package lists: `sudo apt update`
Install Wine: `sudo apt install --install-recommends winehq-stable`
Verify installation: `wine --version` (should show version 6.x)

Wine installation process in WSL2 Ubuntu environment

Configuring Wine for .NET Applications

After installing Wine, you need to configure it properly to run .NET applications. This involves setting up Mono (an open-source implementation of .NET Framework) and installing the required .NET Framework version for your application.

Run initial Wine configuration: `winecfg`
When prompted, install both Mono and Gecko packages
Install WineTricks for easier .NET Framework installation: `sudo apt install winetricks`
Install .NET Framework 4.5 (or your required version): `winetricks dotnet45`
Run `winecfg` again and set Windows version compatibility to at least Windows 7

Important: Never run Wine or WineTricks with sudo/as root, as this will cause issues with the installation and configuration.

Running WinForms and WPF Applications on Linux

Once Wine is properly configured with the necessary .NET Framework, you can run your WinForms or WPF applications. WSL2 mounts Windows drives under the `/mnt` directory, making it easy to access your application files.

BASH

# Basic syntax for running a Windows application with Wine
wine /mnt/c/path/to/your/application.exe

# For 64-bit applications
wine64 /mnt/c/path/to/your/application.exe

When your application runs, you'll notice that Wine automatically handles the Windows-specific GUI elements and interactions. For .NET applications, you can verify the framework version and architecture (32-bit or 64-bit) through application diagnostics.

Setting Up Debugging for WinForms and WPF on Linux

One of the most powerful capabilities is being able to debug your Windows applications running on Linux. This requires setting up the Visual Studio debugger to work with Wine.

Debugging a WinForms application running in WSL2 with full symbol support

Preparing the Debugger

To debug .NET applications running on Wine, you need to set up the Visual Studio Code C# extension's debugger on your Linux system:

Locate the debugger in your Windows user folder: `%USERPROFILE%\.vscode\extensions\ms-dotnettools.csharp-*\debugger`
Copy the entire debugger folder to your Ubuntu user home directory
Rename it to `.vsdebugger` for convenience
Create a symbolic link under `/mnt` with the same Windows drive letter for easier path references: `ln -s /mnt/c /mnt/c:`

Debugging with Visual Studio Code

To debug your application with Visual Studio Code, you need to create a proper launch configuration in your `launch.json` file:

JSON

{
  "name": ".NET Wine Attach",
  "type": "coreclr",
  "request": "attach",
  "processName": "YourApplication.exe",
  "pipeTransport": {
    "pipeProgram": "wsl.exe",
    "debuggerPath": "/home/yourusername/.vsdebugger/vsdbg",
    "pipeCwd": "${workspaceFolder}"
  }
}

Additionally, make sure your .csproj file includes the following properties to enable proper debugging:

XML

<PropertyGroup>
  <DebugType>portable</DebugType>
  <DebugSymbols>true</DebugSymbols>
</PropertyGroup>

Visual Studio Code debugging interface with breakpoints and watch window for a WinForms application

With this configuration, you can set breakpoints, inspect variables, view the call stack, and use all the standard debugging features while your application runs on Linux through Wine.

Debugging with Visual Studio

For Visual Studio users, debugging requires a similar JSON configuration file but uses a different mechanism to launch the debugger:

JSON

{
  "name": ".NET Wine Launch",
  "type": "coreclr",
  "request": "launch",
  "program": "C:/path/to/your/application.exe",
  "cwd": "C:/path/to/your/application/directory",
  "adapter": {
    "name": "wine",
    "type": "executable",
    "command": "wsl.exe",
    "args": ["/home/yourusername/.vsdebugger/vsdbg"]
  }
}

To use this configuration with Visual Studio, you need to launch the Debug Adapter Host with the following command:

POWERSHELL

DebugAdapterHost.Launch /launch:path/to/launch.json /configuration:"NET Wine Launch"

Framework Compatibility and Considerations

While this approach works well for most WinForms and WPF applications, there are some important considerations regarding framework compatibility:

Older .NET Framework applications (4.5, 4.6, etc.) run well but might have limited debugging capabilities
For best debugging experience, consider migrating to .NET 5+ with the Windows compatibility pack
Some complex WPF features might not render correctly in all cases
Performance may vary depending on the complexity of your application
Not all Windows-specific APIs will be available or function correctly

Troubleshooting Common Issues

When running WinForms or WPF applications on Linux through Wine, you might encounter some common issues:

Missing dependencies: Use WineTricks to install additional required Windows components
Graphics issues: Try adjusting Wine's Windows version compatibility in winecfg
Debugger crashes: For .NET Framework apps, consider upgrading to .NET 5+ with Windows compatibility
Path reference problems: Ensure you're using the correct path format (/mnt/c/ vs Z:/mnt/c/)
Performance issues: Wine has some overhead; complex UI operations might be slower than on native Windows

Conclusion

Running and debugging WinForms and WPF applications on Linux using WSL2 represents a significant step forward in cross-platform .NET development. While it's not officially supported by Microsoft, this approach provides a viable solution for developers who need to work with Windows desktop applications in Linux environments.

For the best experience, consider migrating your applications to .NET 5 or newer with the Windows compatibility pack, which provides better debugging support and performance when running through Wine. As WSL2 continues to evolve, we can expect even better integration and support for these scenarios in the future.

This approach opens up new possibilities for cross-platform development workflows, allowing developers to leverage Linux tools and environments while still working with traditionally Windows-only application frameworks.

Complete Guide: Running and Debugging WinForms & WPF .NET Applications on Linux with WSL2