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

發行項
01/27/2025

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

對於以Linux為目標的Windows.NET使用者，WSL 生活在生產現實主義與生產力之間的甜蜜位置。在 Visual Studio 中，您可以使用遠端調試程式，或使用 Container Tools的容器，在遠端 Linux 環境中進行偵錯。當生產現實主義是您的主要考慮時，您應該使用其中一個選項。當簡單且快速的內部迴圈更重要時，WSL 是絕佳的選項。

您不必只選擇一種方法！您可以在相同的專案中擁有 Docker 和 WSL 的啟動設定檔，並選擇適合特定運行的那一個。部署應用程式之後，您可以隨時使用遠端調試工具在發生錯誤時連接到它。若要偵錯在 WSL 中運行的 Linux Docker 容器，請參閱附加至在 Docker 容器上運行的程序。

注意

從 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 程序進行偵錯。

執行應用程式後，選擇 [偵錯]>[附加至程序]。
針對 [連接類型]，選擇 [適用於 Linux 的 Windows 子系統]，然後選擇 [連接目標] 的 Linux 發行版。
選擇 [附加]。

啟動設定檔中的 WSL 設定

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

名字	預設	目的	是否支援代幣？
可執行檔路徑	dotnet	要執行的可執行檔	是的
commandLineArgs	對應至 WSL 環境的 MSBuild 屬性 TargetPath 值	傳遞至 executablePath 的命令行自變數	是的
workingDirectory	針對控制台應用程式： {OutDir} Web 應用程式： {ProjectDir}	用於開始偵錯的工作目錄	是的
環境變數		要為偵錯進程設定的環境變數索引鍵值組。	是的
設定腳本路徑		偵錯之前要執行的腳本。適用於執行 ~/.bash_profile 之類的腳本。	是的
分配名稱		您要使用的 WSL 發行版名稱。	不
啟動瀏覽器	假	是否要啟動瀏覽器	不
launchUrl		launchBrowser 為 true 時要啟動的 URL	不

支援的代幣：

{ProjectDir} - 項目目錄的路徑

{OutDir} - OutDir 的 MSBuild 屬性值

注意

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

傳遞命令行自變數

使用 commandLineArgs 設定，將命令行自變數傳遞至啟動配置檔中的WSL。

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

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

共用方式為