Debuggen von .NET-Apps in WSL mit Visual Studio

Sie können Ihre .NET Core- und .NET 5+-Apps in Linux ganz einfach ausführen und debuggen, ohne Visual Studio mit Windows-Subsystem für Linux (WSL) zu verlassen. Wenn Sie plattformübergreifend entwickeln, können Sie diese Methode als einfache Möglichkeit zum Testen Ihrer Zielumgebungen verwenden.

Für Windows .NET-Benutzer, die Linux als Zielplattform verwenden, stellt WSL einen optimalen Punkt zwischen realistischer Produktionsumgebung und Produktivität dar. In Visual Studio können Sie bereits mithilfe des Remotedebuggers oder mit Containern unter Verwendung von Containertools in einer Linux-Remoteumgebung debuggen. Wenn Sie Ihr Hauptaugenmerk auf eine realistische Produktionsumgebung legen möchten, sollten Sie eine dieser Optionen verwenden. Wenn Ihnen eine einfache und schnelle innere Schleife wichtiger ist, eignet sich WSL großartig.

Sie müssen nicht nur eine Methode auswählen. Sie können ein Startprofil für Docker und WSL in demselben Projekt erstellen und auswählen, welcher Dienst für eine bestimmte Ausführung geeignet ist. Nachdem Sie Ihre App bereitgestellt haben, können Sie diese immer an einen Remotedebugger anfügen, wenn ein Problem auftreten sollte. Informationen zum Debuggen eines Linux-Docker-Containers, der in WSL ausgeführt wird, finden Sie unter Anfügen an einen Prozess, der auf einem Docker-Container ausgeführt wird.

Hinweis

Ab Visual Studio 2019 Version 16.11 Vorschau 3 wurde das „WSL-Debugziel“ in „WSL“ umbenannt.

Voraussetzungen

• Visual Studio 2019 Version 16.9 Vorschau 1 oder höhere Versionen mit der optionalen WSL-Komponente zum Debuggen mit .NET.

  Um die WSL-Komponente zu suchen, klicken Sie auf Extras>Get Tools and Features (Tools und Features abrufen). Vergewissern Sie sich im Visual Studio-Installer, dass die Komponente installiert ist, indem Sie die Registerkarte Einzelne Komponenten auswählen und WSL als Suchbegriff eingeben.

  In einigen Versionen von Visual Studio ist die optionale Komponente standardmäßig in einigen der .NET-Workloads enthalten.

• Installieren Sie WSL.

• Installieren Sie eine Distribution Ihrer Wahl.

Starten Sie das Debuggen mit WSL

1. Nachdem Sie die erforderlichen Komponenten installiert haben, öffnen Sie eine ASP.NET Core Web-App oder eine .NET Core-Konsolen-App in Visual Studio. Dann wird ein neues Startprofil mit dem Namen WSL angezeigt:

   

2. Wählen Sie dieses Profil aus, um es der Datei launchSettings.json hinzuzufügen.

   Einige der Schlüsselattribute in der Datei werden im folgenden Beispiel gezeigt.

   Hinweis

   Ab Visual Studio 2022 Vorschau 3 wurde der Befehlsname im Startprofil von „WSL2“ in „WSL“ geändert.

   "WSL": {
       "commandName": "WSL",
       "launchBrowser": true,
       "launchUrl": "https://localhost:5001",
       "environmentVariables": {
           "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
           "ASPNETCORE_ENVIRONMENT": "Development"
       },
       "distributionName": ""
   }
   

   Nachdem Sie das neue Profil ausgewählt haben, wird durch die Erweiterung überprüft, ob die WSL-Distribution zum Ausführen von .NET-Apps konfiguriert ist, und Sie erhalten Hilfe bei der Installation fehlender Abhängigkeiten. Nachdem Sie diese Abhängigkeiten installiert haben, können Sie in WSL debuggen.

3. Starten Sie den Debugging-Vorgang wie gewohnt. Dann wird Ihre App in Ihrer WSL-Standarddistribution ausgeführt.

   Sie können ganz einfach überprüfen, ob Ihre App in Linux ausgeführt wird, indem Sie den Wert von Environment.OSVersion überprüfen.

Hinweis

Nur Ubuntu und Debian wurden getestet und werden unterstützt. Andere Distributionen, die von .NET unterstützt werden, sollten funktionieren. Dafür müssen allerdings die .NET-Runtime und cURL manuell installiert werden.

Auswählen einer bestimmten Distribution

Standardmäßig verwendet das WSL 2-Startprofil die Standarddistribution, die in der Datei wsl.exe festgelegt ist. Wenn Sie möchten, dass Ihr Startprofil unabhängig von diesem Standard eine bestimmte Distribution als Ziel verwendet, können Sie das Startprofil ändern. Wenn Sie z. B. eine Web-App debuggen und sie unter Ubuntu 20.04 testen möchten, sieht Ihr Startprofil wie folgt aus:

"WSL": {
    "commandName": "WSL",
    "launchBrowser": true,
    "launchUrl": "https://localhost:5001",
    "environmentVariables": {
        "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
        "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "distributionName": "Ubuntu-20.04"
}

Verwenden mehrerer Distributionen als Ziel

Wenn Sie an einer Anwendung arbeiten, die in mehreren Distributionen ausgeführt werden soll, und Sie diese schnell für jede Distributionen testen möchten, können Sie mehrere Startprofile verwenden. Wenn Sie z. B. Ihre Konsolen-App unter Debian, Ubuntu 18.04 und Ubuntu 20.04 testen müssen, können Sie die folgenden Startprofile verwenden:

"WSL : Debian": {
    "commandName": "WSL",
    "distributionName": "Debian"
},
"WSL : Ubuntu 18.04": {
    "commandName": "WSL",
    "distributionName": "Ubuntu-18.04"
},
"WSL : Ubuntu 20.04": {
    "commandName": "WSL",
    "distributionName": "Ubuntu-20.04"
}

Mit diesen Startprofilen können Sie problemlos zwischen den Zieldistributionen hin- und herwechseln, ohne auf die Vorteile von Visual Studio verzichten zu müssen.

Anfügen an einen laufenden WSL-Prozess

Zusätzlich zum Debuggen ab dem App-Start mit F5 können Sie mithilfe des Anfügens an einen ausgeführten WSL-Prozess mithilfe der Funktion zum Anfügen an einen Prozess debuggen.

1. Wenn die App ausgeführt wird, wählen Sie Debuggen>An Prozess anfügen aus.

2. Wählen Sie für den Verbindungstyp die Option Windows-Subsystem für Linux (WSL) und dann die Linux-Verteilung für das Verbindungsziel aus.

3. Wählen Sie Anfügenaus.

   

WSL-Einstellungen im Startprofil

In der folgenden Tabelle werden die Einstellungen aufgeführt, die im Startprofil unterstützt werden.

Name	Standard	Zweck	Tokenunterstützung?
executablePath	dotnet	Die auszuführende ausführbare Datei	Ja
commandLineArgs	Der Wert der MSBuild-Eigenschaft „TargetPath“, die der WSL-Umgebung zugeordnet ist	Befehlszeilenargumente, die an executablePath übergeben werden	Ja
workingDirectory	Für Konsolen-Apps: {OutDir} Für Web-Apps: {ProjectDir}	Das Arbeitsverzeichnis, in dem der Debuggingvorgang gestartet werden soll	Ja
EnvironmentVariables		Schlüssel-Wert-Paare von Umgebungsvariablen, die für den Debuggingvorgang festgelegt werden sollen	Ja
setupScriptPath		Skript, das vor dem Debuggingvorgang ausgeführt werden soll; nützlich für das Ausführen von Skripts wie „~/.bash_profile“	Ja
distributionName		Der Name der zu verwendenden WSL-Distribution	Nein
launchBrowser	false	Gibt an, ob ein Browser gestartet werden soll	Nein
launchUrl		Zu startende URL, wenn der Wert für launchbrowser Richtig ist	Nein

Unterstützte Token:

{ProjectDir}: der Pfad zum Projektverzeichnis

{OutDir}: der Wert der MSBuild-Eigenschaft OutDir

Hinweis

Alle Pfade gelten für WSL, nicht für Windows.

Übergeben eines Befehlszeilenarguments

Verwenden Sie die commandLineArgs-Einstellung, um ein Befehlszeilenargument an WSL im Startprofil zu übergeben.

Im folgenden Beispiel übergeben Sie zwei Argumente an ein DLL-Projekt namens ConsoleApp.

"WSL": {
  "commandName": "WSL",
  "commandLineArgs": "\"{OutDir}/ConsoleApp.dll\" arg1 arg2"
}