使用 Visual Studio 對 WSL 中的 .NET Apps 進行偵錯

發行項
04/09/2024

您可以在不需離開 Visual Studio 的情況下，輕鬆地使用 WSL 執行和偵錯 Linux 中的 .NET Core 和 .NET 5+ 應用程式。如果您是跨平台開發人員，則可使用此方法作為簡單的方法來測試更多目標環境。

對於以 Linux 為目標的 Windows .NET 使用者，WSL 處於生產務實性與生產力之間的甜蜜點。在 Visual Studio 中，您已經可以使用遠端偵錯程式在遠端 Linux 環境中進行偵錯，或使用容器工具對容器進行偵錯。當生產務實性是您的主要考量時，您應該使用下列其中一個選項。當簡單且快速的內部迴圈更重要時，WSL 是絕佳的選項。

您不必只選擇一種方法！您可以在相同的專案中擁有 Docker 和 WSL 的啟動設定檔，並挑選適合特定執行的項目。部署您的應用程式後，您隨時都可以在發生問題時，使用遠端偵錯工具來連結至該應用程式。

注意

從 Visual Studio 2019 16.11 版 Preview 3 開始，WSL 2 偵錯目標已重新命名為 WSL。

必要條件

Visual Studio 2019 v16.9 Preview 1 或更新版本，而且使用 WSL 選用元件進行 .NET 偵錯。

若要檢查 WSL 元件，請選擇 [工具]>[取得工具和功能]。在 Visual Studio 安裝程式中，選擇 [個別元件] 索引標籤，然後輸入 WSL 作為搜尋詞彙，以確定已安裝元件。

在某些 Visual Studio 版本中，選用元件預設會隨附於某些 .NET 工作負載中。
安裝 WSL。
安裝您選擇的發行版本。

使用 WSL 開始偵錯

安裝必要元件之後，請在 Visual Studio 中開啟 ASP.NET Core Web 應用程式或 .NET Core 主機應用程式。您會看到名為 WSL 的新啟動設定檔：

選取此設定檔，將其新增至 launchSettings.json。

下列範例顯示該檔案中的一些重要屬性。

注意

從 Visual Studio 2022 Preview 3 開始，啟動設定檔中的命令名稱已從 WSL2 變更為 WSL。

"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": ""
}

選取新的設定檔後，延伸模組會檢查您的 WSL 發行版本是否已設定為執行 .NET 應用程式，並協助您安裝任何遺漏的相依性。安裝這些相依性後，您就可以在 WSL 中進行偵錯。

正常開始偵錯，您的應用程式會在預設 WSL 發行版本中執行。

確認您在 Linux 中執行的簡單方法，就是檢查 Environment.OSVersion 的值。

注意

只有 Ubuntu 和 Debian 已經過測試並受到支援。 .NET 支援的其他發行版本應該運作，但需要手動安裝 .NET 執行階段和 Curl。

選擇特定發行版本

根據預設，WSL 2 啟動設定檔會使用如 wsl.exe 中設定的預設發行版本。如果您想要讓啟動設定檔以特定發行版本為目標，不論該預設值為何，您都可以修改啟動設定檔。例如，如果您要對 Web 應用程式進行偵錯，而且想要在 Ubuntu 20.04 上進行測試，您的啟動設定檔會如下所示：

"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"
}

以多個發行版本為目標

更進一步，如果您正在處理需要在多個發行版本中執行的應用程式，而且您想要快速測試每個發行版本，則可有多個啟動設定檔。例如，如果您需要在 Debian、Ubuntu 18.04 和 Ubuntu 20.04 上測試主控台應用程式，您可以使用下列啟動設定檔：

"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"
}

透過這些啟動設定檔，您可以輕鬆地在目標發行版本之間來回切換，而不需要離開 Visual Studio 的舒適。

啟動設定檔清單中的多個 WSL 啟動設定檔

連結至執行中的 WSL 處理序

除了使用 F5 從應用程式啟動時進行偵錯之外，您還可以使用連結至處理序功能來連結至執行中的 WSL 處理序來進行偵錯。

執行應用程式後，選擇 [偵錯]>[連結至處理序]。
針對 [連線類型]，選擇 [Windows 子系統 Linux 版 (WSL)]，然後針對 [連線目標] 選擇 Linux 發行版本。
選擇 [連結]。

啟動設定檔中的 WSL 設定

下表顯示啟動設定檔中支援的設定。

名稱	預設	目的	支援權杖？
executablePath	dotnet	要執行的可執行檔	Yes
commandLineArgs	對應至 WSL 環境的 MSBuild 屬性 TargetPath 值	傳遞至 executablePath 的命令列引數	Yes
workingDirectory	針對主控台應用程式：{OutDir} 針對 Web 應用程式：{ProjectDir}	要在其中開始偵錯的工作目錄	Yes
environmentVariables		要為偵錯的處理序設定的環境變數索引鍵值組。	Yes
setupScriptPath		偵錯之前要執行的指令碼。適用於執行 ~/.bash_profile 之類的指令碼。	Yes
distributionName		要使用的 WSL 發行版本名稱。	No
launchBrowser	false	是否要啟動瀏覽器	No
launchUrl		如果 launchBrowser 為 true，則為要啟動的 URL	No

支援的權杖：

{ProjectDir} - 專案目錄的路徑

{OutDir} - MSBuild 屬性 OutDir 的值

注意

所有路徑都適用於 WSL，而非 Windows。

傳遞命令列引數

使用 commandLineArgs 設定，將命令列引數傳遞至啟動設定檔中的 WSL。

在下列範例中，您會將兩個引數傳遞至名為 ConsoleApp 的 DLL 專案。

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