使用 Visual Studio 在 WSL 中调试 .NET 应用

项目
02/10/2025

可以在 Linux 中轻松运行和调试 .NET Core 和 .NET 5+ 应用，而无需使用适用于 Linux 的 Windows 子系统（WSL）离开 Visual Studio。如果你是跨平台开发人员，则可以使用此方法作为测试更多目标环境的简单方法。

对于面向 Linux 的 Windows .NET 用户，WSL 处于生产环境的真实感和生产力之间的理想位置。在 Visual Studio 中，你已在远程 Linux 环境中使用远程调试器进行调试，也可以使用容器工具的容器进行调试。当生产现实主义是你主要关心的问题时，应使用这些选项之一。当一个简单且快速的内部循环更重要时，WSL 是一个很好的选择。

你不必只选择一种方法！可以在同一项目中为 Docker 和 WSL 设置启动配置文件，并选取适合特定运行的启动配置文件。应用程序部署后，如果出现问题，可以随时使用远程调试器连接到它。若要调试在 WSL 中运行的 Linux Docker 容器，请参阅附加到在 Docker 容器上运行的进程。

说明

从 Visual Studio 2019 版本 16.11 预览版 3 开始，WSL 2 调试目标已重命名为 WSL。

先决条件

Visual Studio 2019 v16.9 预览版 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 预览版 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 子系统（WSL），然后选择 连接目标的 Linux 分发版。
选择附加。

启动配置文件中的 WSL 设置

下表显示了启动配置文件中支持的设置。

名字	违约	目的	支持令牌？
executablePath	dotnet	要运行的可执行文件	是的
commandLineArgs	映射到 WSL 环境的 MSBuild 属性 TargetPath 的值	传递给 executablePath 的命令行参数	是的
workingDirectory	对于控制台应用：{OutDir} Web 应用：{ProjectDir}	在其中开始调试的工作目录	是的
环境变量		要为已调试进程设置的环境变量的键值对。	是的
setupScriptPath		在调试之前要运行的脚本。适用于运行 ~/.bash_profile 等脚本。	是的
distributionName		要使用的 WSL 发行版名称。	不
launchBrowser	false	是否启动浏览器	不
launchUrl		launchBrowser 为 true 时要启动的 URL	不

支持的令牌：

{ProjectDir} - 项目目录的路径

{OutDir} - MSBuild 属性 OutDir 的值

说明

所有路径都适用于 WSL 而不是 Windows。

传递命令行参数

使用 commandLineArgs 设置在启动配置文件中将命令行参数传递到 WSL。

在以下示例中，将两个参数传递给名为 ConsoleApp 的 DLL 项目。

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

通过