Debuggen von .NET-Apps in WSL mit Visual Studio

Sie können Ihre .NET Core- und .NET 5+-Apps in Linux problemlos ausführen und debuggen, ohne Visual Studio mit dem Windows-Subsystem für Linux (WSL) zu verlassen. Wenn Sie plattformübergreifende Entwickler sind, können Sie diese Methode als einfache Möglichkeit verwenden, um mehr Ihrer Zielumgebungen zu testen.

Für einen Windows .NET-Benutzer für Linux lebt WSL in einem süßen Punkt zwischen Produktionsrealismus und Produktivität. In Visual Studio können Sie bereits in einer Remote-Linux-Umgebung mithilfe des Remotedebuggersoder mit Containern mithilfe der Containertoolsdebuggen. Wenn der Produktionsrealismus Ihr Hauptanliegen ist, sollten Sie eine dieser Optionen verwenden. Wenn ein leichter und schneller interner Prozess entscheidender ist, ist WSL eine großartige Option.

Sie müssen nicht nur eine Methode auswählen! Sie können ein Startprofil für Docker und WSL im selben Projekt haben und auswählen, welches für eine bestimmte Ausführung geeignet ist. Und sobald Ihre App bereitgestellt wurde, können Sie den Remotedebugger jederzeit verwenden, um an die App anzudocken, falls es ein Problem gibt. 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-Containerausgeführt wird.

Anmerkung

Ab Visual Studio 2019, Version 16.11 Preview 3, wurde das WSL 2-Debugziel in WSL umbenannt.

Voraussetzungen

  • Visual Studio 2019 v16.9 Preview 1 oder höher mit der optionalen Komponente .NET Debugging mit WSL.

    Um die WSL-Komponente zu suchen, klicken Sie auf Extras>Tools und Features abrufen. Stellen Sie im Visual Studio Installer sicher, dass die Komponente installiert ist, indem Sie den Einzelne Komponenten Reiter auswählen und WSL als Suchbegriff eingeben.

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

  • Installieren Sie WSL.

  • Installieren Sie eine Distribution Ihrer Wahl.

Starten des Debuggens mit WSL

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

    WSL-Startprofil in der Liste „Startprofil“

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

    Einige der wichtigsten Attribute in der Datei werden im folgenden Beispiel gezeigt.

    Anmerkung

    Ab Visual Studio 2022 Preview 3 wurde der Befehlsname im Startprofil von WSL2 zu 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": ""
    }
    
    "WSL": {
        "commandName": "WSL2",
        "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, überprüft die Erweiterung, ob Ihre WSL-Verteilung für die Ausführung von .NET-Apps konfiguriert ist, und hilft Ihnen bei der Installation fehlender Abhängigkeiten. Nachdem Sie diese Abhängigkeiten installiert haben, können Sie in WSL debuggen.

  3. Starten Sie das Debuggen wie gewohnt, und Ihre App wird in der Standardmäßigen WSL-Verteilung ausgeführt.

    Eine einfache Möglichkeit, zu überprüfen, ob Sie in Linux ausgeführt werden, besteht darin, den Wert von Environment.OSVersionzu überprüfen.

Anmerkung

Nur Ubuntu und Debian wurden getestet und werden unterstützt. Andere von .NET unterstützte Verteilungen sollten funktionieren, erfordern jedoch, dass die .NET Runtime und Curlmanuell installiert werden.

Auswählen einer bestimmten Verteilung

Standardmäßig verwendet das WSL 2-Startprofil die Standardverteilung, wie in wsl.exefestgelegt. Wenn Ihr Startprofil auf eine bestimmte Verteilung ausgerichtet werden soll, unabhängig von dieser Standardeinstellung, können Sie Ihr Startprofil ändern. Wenn Sie beispielsweise eine Web-App debuggen und auf Ubuntu 20.04 testen möchten, würde Ihr Startprofil wie folgt aussehen:

"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"
}
"WSL": {
    "commandName": "WSL2",
    "launchBrowser": true,
    "launchUrl": "https://localhost:5001",
    "environmentVariables": {
        "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
        "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "distributionName": "Ubuntu-20.04"
}

Mehrere Verteilungen anvisieren

Wenn Sie einen Schritt weiter gehen, wenn Sie an einer Anwendung arbeiten, die in mehreren Verteilungen ausgeführt werden muss und Sie eine schnelle Möglichkeit zum Testen auf jedem dieser Anwendungen wünschen, können Sie mehrere Startprofile haben. Wenn Sie beispielsweise Ihre Konsolen-App auf 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"
}
"WSL : Debian": {
    "commandName": "WSL2",
    "distributionName": "Debian"
},
"WSL : Ubuntu 18.04": {
    "commandName": "WSL2",
    "distributionName": "Ubuntu-18.04"
},
"WSL : Ubuntu 20.04": {
    "commandName": "WSL2",
    "distributionName": "Ubuntu-20.04"
}

Mit diesen Startprofilen können Sie ganz einfach zwischen Ihren Zielverteilungen wechseln, ohne den Komfort von Visual Studio zu verlassen.

Mehrere WSL-Startprofile in der Startprofilliste

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 VerbindungstypWindows-Subsystem für Linux (WSL)aus, und wählen Sie dann die Linux-Verteilung für das Verbindungszielaus.

  3. Wählen Sie an und fügen Siean.

    Screenshot: WSL-Prozess im Dialogfeld „An Prozess anfügen“

    Screenshot: WSL-Prozess im Dialogfeld „An Prozess anfügen“

WSL-Einstellungen im Startprofil

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

Name Standard Zweck Unterstützung von Tokens?
executablePath dotnet Ausführbare Datei, die ausgeführt werden soll Ja
commandLineArgs Der Wert der MSBuild-Eigenschaft TargetPath, die der WSL-Umgebung zugeordnet ist Befehlszeilenargumente, die an ausführbarePath übergeben werden Ja
workingDirectory Für Konsolen-Apps: {OutDir}
Für Web-Apps: {ProjectDir}
Das Arbeitsverzeichnis, in dem das Debuggen gestartet werden soll Ja
Umgebungsvariablen Schlüsselwertpaare von Umgebungsvariablen, die für den debuggierten Prozess festgelegt werden sollen. Ja
setupScriptPath Skript, das vor dem Debuggen ausgeführt werden soll. Nützlich für das Ausführen von Skripts wie ~/.bash_profile. Ja
distributionName Name der zu verwendenden WSL-Verteilung. Nein
launchBrowser FALSCH Gibt an, ob ein Browser gestartet werden soll Nein
launchUrl URL, die gestartet werden soll, wenn launchBrowser "true" ist Nein

Unterstützte Token:

{ProjectDir} - Der Pfad zum Projektverzeichnis

{OutDir}: Wert der MSBuild-Eigenschaft OutDir

Anmerkung

Alle Pfade sind für WSL und nicht für Windows bestimmt.

Übergeben eines Befehlszeilenarguments

Verwenden Sie die einstellung commandLineArgs, 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"
}