编辑

C# 开发工具包常见问题解答

Name: Visual Studio Code
Author: Microsoft

使用本常见问题解答 (FAQ) 主题来详细了解 C# 开发工具包扩展，并对可能遇到的问题进行故障排除。

通用

什么是 C# 开发工具包？

C# 开发工具包是一个为增强 Visual Studio Code 中的 C# 开发体验而创建的扩展。它旨在为 VS Code 带来更广阔、更高效、更可靠的 C# 体验。C# 开发工具包不会取代现有的 C# 扩展，而是在其提供的出色语言服务功能之上进行补充。开发者可以选择继续使用现有 C# 扩展的更新版本，或者通过添加 C# 开发工具包来增强他们的体验。

目前支持哪些项目类型？

C# 开发工具包支持为 .NET Core（通常也称为 .NET）构建 Web 应用、控制台应用、类库项目和测试项目。.NET MAUI 扩展和Unity 扩展构建在 C# 开发工具包之上，为构建 .NET 多平台应用 UI (MAUI) 应用和 Unity 应用提供了额外支持。这些扩展支持现代 .NET 项目格式，也称为“SDK 风格”项目。如果你正在构建非 SDK 格式的项目，例如 .NET Framework 应用和 Xamarin 应用，请参阅项目系统部分。

C# 开发工具包中包含哪些扩展？

目前，C# 开发工具包系列中包含的扩展有：

这些扩展的使用受C# 开发工具包系列扩展最终用户许可协议 (EULA) 的约束。

这些扩展还有一些依赖项，它们带有自己的许可证——例如，C# 开发工具包依赖于C# 扩展和.NET 安装工具。

为什么 C# 开发工具包没有激活/找不到 C# 开发工具包的命令？

当你尝试编辑 C# 文件时，C# 开发工具包没有激活，可能有以下几个原因。

未安装 2.0+ 版本的 C# 扩展。C# 开发工具包需要 2.0 或更高版本的 C# 扩展。请检查确保你已安装 C# 扩展，并且版本为 2.0 或更高。
工作区偏好使用 C# 扩展。C# 开发工具包不支持 .NET Framework 项目，如果你已将 dotnet.preferCSharpExtension 设置为 true，则 C# 开发工具包将对该工作区禁用。如果项目不是 .NET Framework 项目，请确保禁用此设置。
使用只读操作系统。C# 开发工具包需要对其自身的扩展文件夹以及 VS Code 提供的用于扩展写入任意状态的文件夹具有写入权限，因此，如果你使用的是完全只读的操作系统，C# 开发工具包将无法工作。

如果你已经检查了这些问题，但仍然找不到 C# 开发工具包的命令，请报告问题并提供 C# 开发工具包输出窗口中的信息。

许可和贡献

谁可以使用 C# 开发工具包？

C# 开发工具包通过社区许可证提供给符合条件的个人，并且也作为对现有 Visual Studio 订阅的又一补充。这意味着拥有有效 Visual Studio 订阅的开发者今天就可以使用 C# 开发工具包。

对于个人、学术和开源项目，C# 开发工具包可以免费使用。对于商业用途，最多 5 人的团队也可以免费使用 C# 开发工具包。对于 6 人及以上的开发者，这些用户将需要 Visual Studio Professional（或更高版本）订阅。C# 开发工具包也包含在 GitHub Codespaces 和 Microsoft Dev Box 中，因此这些产品的用户可以免费使用 C# 开发工具包，无需额外费用。

我应该在哪里提交反馈和建议？

用户可以通过 VS Code 的**帮助 > 报告问题**来报告问题或建议。选择是错误、功能请求还是性能问题，提交到**一个扩展**，然后从扩展列表中选择 **C# Dev Kit**。

Help > Report Issue image

C# 开发工具包是开源的吗？为什么不是？

不是。C# 开发工具包是闭源的，但它依赖于开源的 C# for VS Code 扩展，并且两者都与开源组件（如 Roslyn 和 Razor）进行通信。我们 C# 开发工具包的目标之一是为使用 VS Code 的 C# 开发者提供改进的生产力体验。为了实现这一点，C# 开发工具包包含了一些与我们其他工具共享的专有、闭源功能。为了让 VS Code 用户也能使用这些体验，我们需要将 C# 开发工具包作为一个闭源扩展引入。

我如何做出贡献？

C# 扩展是 C# 开发工具包的一部分，它是完全开源的，并受这些许可条款的约束。该扩展的源代码可在 https://github.com/dotnet/vscode-csharp 上找到，并根据 MIT 许可证授权。

本项目采用了贡献者契约定义的行为准则，以明确我们社区中的预期行为。更多信息，请参阅 .NET 基金会行为准则。通过签署 CLA，社区可以自由地使用你对 .NET 基金会项目的贡献。

.NET SDK

安装脚本超时

请注意，根据你的网络速度，安装 .NET Core 运行时可能需要一些时间。默认情况下，如果安装时间超过 4.5 分钟，安装将失败终止。如果你认为这个下载时间太短（或太长），可以通过将 dotnetAcquisitionExtension.installTimeoutValue 设置为自定义值来更改超时值。

了解有关配置 VS Code 设置的更多信息，并参阅下面 settings.json 文件中自定义超时的示例。在此示例中，自定义超时值为 180 秒，即 3 分钟。

{
  "dotnetAcquisitionExtension.installTimeoutValue": 180
}

获取 .NET SDK 时出错

Error acquiring .NET SDK

注意：如果你位于中国，你的 .NET SDK 下载可能会被阻止并导致超时。

你需要确保已安装 .NET SDK。作为一种解决方法，你可以将 .NET 运行时获取扩展指向一个已有的 .NET 安装：

Point the .NET runtime acquisition extension to an existing .NET SDK install

如何手动安装 .NET？

如果 .NET 安装失败，或者你想重用现有的 .NET 安装，你可以使用 dotnetAcquisitionExtension.existingDotnetPath 设置。.NET 可以从 **C# 开发工具包演练**或 .NET 网站手动安装。要将扩展指向该安装，请使用扩展 ID 和路径更新你的设置，如下所示：

Windows

{
  "dotnetAcquisitionExtension.existingDotnetPath": [
    {
      "extensionId": "msazuretools.azurerm-vscode-tools",
      "path": "C:\\Program Files\\dotnet\\dotnet.exe"
    }
  ]
}

macOS

{
  "dotnetAcquisitionExtension.existingDotnetPath": [
    {
      "extensionId": "msazuretools.azurerm-vscode-tools",
      "path": "/usr/local/share/dotnet/dotnet"
    }
  ]
}

扩展认为我处于离线状态，错误响应为 400 或 407，并且我使用了代理

如果你的系统使用代理并且禁用了注册表访问，你需要在扩展设置中明确设置代理 URL。当通过环境变量和注册表设置代理时，代理会被自动检测到，但如果你的代理仅通过注册表项管理且注册表访问被禁用，扩展将无法找到它。要设置代理 URL，请添加以下扩展设置：

{
  "dotnetAcquisitionExtension.proxyUrl": "https://your_proxy_url:port"
}

项目系统

解决方案资源管理器报告我的项目在 C# 开发工具包中不受支持

这通常是因为项目面向的是 .NET Framework 而不是 .NET Core/.NET。目前，C# 开发工具包不支持 .NET Framework 项目。

Project Not Supported in Solution Explorer

要解决此问题，你有两种选择。

你可以将你的项目更新为 SDK 风格的项目，以访问所有可用的 C# 开发工具包功能。

或者，你可以在设置编辑器中使用**偏好 CSharp 扩展**工作区设置，将项目和解决方案的加载委托给C# 扩展。请记住，使用此设置后，某些 C# 开发工具包功能将不可用。要访问此设置，请转到设置编辑器并选择**工作区**选项卡。然后，在搜索栏中搜索“Prefer CSharp”，并勾选**偏好 CSharp 扩展**设置旁边的复选框。如果你尝试加载 .NET Framework 项目，C# 开发工具包将自动显示一个通知，要求你将项目更新为 SDK 风格的项目，或者通过从通知中选择**使用 C# 扩展**来让 C# 扩展加载你的项目或解决方案。此选项将自动选择**偏好 CSharp 扩展**设置。请注意，你需要重新加载 VS Code 才能使此设置生效。

我点击了“创建 .NET 项目”按钮，但没有任何反应

这通常发生在扩展版本不匹配时。C# 开发工具包需要 2.0 或更高版本的C# 扩展。如果你使用的是 v1 版本的 C# 扩展，C# 开发工具包以及与 C# 开发工具包相关的命令将无法正常工作。要解决此问题，请将 C# 扩展升级到最新版本。

项目系统报告它遇到了问题

当发生内部项目系统错误时，你通常会在 VS Code 的一个角落看到这样的通知弹出

Failed to Restore Solution

选择**打开日志**按钮，打开一个视图，显示问题发生处的堆栈跟踪。选择并复制日志中的所有文本。通过 VS Code 报告问题，并确保包含从日志中复制的文本。

当我打开我的解决方案时，我收到通知“未能还原解决方案”

选择**显示错误**。这将打开 NuGet 的输出面板。通读错误信息，以确定包还原无法完成的原因。如果你无法解决问题，请通过 VS Code 报告问题。

解决方案资源管理器显示“未找到兼容的 .NET SDK”

此错误最可能的原因是一个 global.json 文件指定了与系统上安装的 SDK 不同的 SDK。

A compatible .NET SDK was not found

打开输出窗口并切换到**项目**窗格以查找更多信息。你应该会看到类似这样的内容

Output Window Projects Pane

要解决此问题，请更新 global.json 以指定一个已安装的 SDK，或从下载 .NET 页面安装指定的 SDK。

接下来，关闭并重新打开工作区。

也可能是 SDK 没有安装在 C# 开发工具包已知的位置。例如，如果 SDK 是通过包管理器而不是通过微软提供的安装程序安装的，就可能发生这种情况。要解决此问题，请通过包管理器卸载 SDK，然后通过下载 .NET 进行安装。

测试资源管理器

为什么我的测试没有出现在测试资源管理器面板中？

确保你的解决方案包含一个测试项目。只有作为已打开解决方案一部分的测试项目才会被包含。要查看测试项目是否是解决方案的一部分，请在文件资源管理器中打开解决方案资源管理器视图，并查看项目是否出现在树中。右键单击解决方案节点以添加现有测试项目，或在解决方案中创建新的测试项目。

C# 开发工具包还要求在测试出现在测试资源管理器面板之前，它已经成功构建了你的项目。此外，如果对你的项目/解决方案执行了**清理**操作，测试 dll 会从测试资源管理器面板中移除。

在确认你的测试项目是解决方案的一部分后，通过在解决方案资源管理器中右键单击解决方案并选择**生成**，或使用 ⇧⌘B (Windows、Linux 为 Ctrl+Shift+B) 来构建你的解决方案。构建完成后，你的测试将出现在测试资源管理器面板中。

如果你的测试仍然没有出现，请考虑以下额外检查：

支持的 .NET Core SDK：确保你为你的平台和机器使用了受支持的 .NET Core SDK。某些 SDK 在特定的操作系统或架构上无法工作。更多信息，请查看官方 .NET 下载页面：https://dotnet.microsoft.com/en-us/download。
有效的 SDK 安装：验证是否检测到有效的 SDK 安装。你可以启用诊断日志来检查为你的 .NET 项目检测到了哪个 SDK。请注意，通过不支持的工具（如 ASDF 或 Mise）安装的 .NET SDK 可能无法被检测到，因为它们偏离了微软的官方安装方法。我们建议遵循官方说明。
生成输出：确认生成已完成并已生成相应的输出二进制文件，例如 .dll 或 .exe 文件。
项目加载：确保所有项目都已加载完毕。在解决方案资源管理器中，查找测试项目旁边的测试图标，以确认它们已被检测到。

我的测试出现在测试资源管理器面板中，但我无法调试它们

确保你的测试面向的是 .NET Core。C# 开发工具包不支持 .NET Framework 项目，尽管 .NET Framework 项目可能会加载并看起来可以工作。VS Code 中的调试器不支持 .NET Framework。

我刚刚向我的测试项目添加了新测试，但它们没有出现在测试资源管理器面板中？

C# 开发工具包要求在测试出现在测试资源管理器面板之前，它已经成功构建了你的项目。

通过在解决方案资源管理器中右键单击解决方案并选择**生成**，或使用 ⇧⌘B (Windows、Linux 为 Ctrl+Shift+B) 来构建你的解决方案。构建完成后，你的测试将出现在测试资源管理器面板中。

为什么我的测试在测试资源管理器中没有被发现或运行？

如果你的测试项目正在使用 Microsoft 测试平台 (MTP)（无论是通过 MSTest、NUnit、xUnit v3 还是 TUnit 测试框架），你的测试可能无法在测试资源管理器中被发现或运行，因为 MTP 与传统的 VSTest 平台不同。要解决此问题，你需要在 Visual Studio Code 中启用“使用测试平台协议”设置，以允许 C# 开发工具包与 MTP 测试项目通信。

请按照以下步骤启用该设置：

在 VS Code 中打开设置：转到文件 > 首选项 > 设置（或按 ⌘, (Windows、Linux 为 Ctrl+,)）。
在设置搜索栏中，输入“Test Window”以筛选结果。
在 C# 开发工具包扩展设置下，找到设置 Dotnet > Test Window: Use Testing Platform Protocol。
勾选复选框以启用它（或将其切换为“开”）。
通过在命令面板（⇧⌘P (Windows、Linux 为 Ctrl+Shift+P)）中运行**重新加载窗口**命令来重新加载 VS Code。

启用此设置后，你的测试应该可以在测试资源管理器中被正确发现和运行。

如何收集用于排查测试资源管理器问题的日志？

如果你遇到测试资源管理器的问题，可以启用诊断日志以收集更多信息进行故障排除：

增加测试资源管理器的详细程度：导航到 C# 开发工具包设置，并将测试资源管理器详细程度设置从 `minimal` 增加到 `diagnostic`。这将生成更详细的日志。
检查输出窗口：在 Visual Studio Code 中打开输出窗口，并从下拉菜单中选择 **C# Dev Kit - Test Explorer**。诊断消息将以 `[dev]` 前缀出现。
收集以下信息：报告问题时，请确保包含：
- 来自输出窗口的诊断日志。
- 你的操作系统和版本（例如，Windows 10、macOS 13）。
- 你正在使用的 C# 开发工具包扩展的版本。转到扩展视图，并将鼠标悬停在扩展上以查看版本信息。

这些信息将有助于更有效地诊断和解决问题。

调试器

当我按 F5 时，没有任何反应

确保你已打开一个 C# 项目，或者活动文档是 .cs 或 .razor 文件。如果调试器仍然无法加载，请确保 C# 开发工具包和 C# 扩展都已激活。

当我按 F5 时，它要求我“选择一个调试器”。我该如何知道选择哪一个？

如果你正在尝试调试 .NET 控制台应用程序、Blazor 服务器应用、Blazor WebAssembly 或 Web 应用程序，请确保选择 **C#** 选项。其他选项可能是其他扩展的一部分，例如用于 JavaScript 调试的 **Node** 或用于 Python 调试的 **Python**，它们不属于 C# 开发工具包。

当我按 F5 时，它提示我输入密码（仅限 macOS）

macOS 默认禁用开发者模式，如果某个程序想用作调试器，它会提示输入密码以保护用户。

如果你希望禁用这些提示，可以运行以下命令：

DevToolsSecurity --enable
sudo dscl . append /Groups/_developer GroupMembership $USER

为什么调试不工作？

如果你正在尝试调试一个库或一个测试项目，很可能需要采取一些额外的步骤来确保你的代码被正确调试。要调试一个库，你可以创建一个与该库交互的控制台或 Web 应用程序。对于测试项目，你可以使用测试资源管理器来有效地调试你的代码。

调试时，我的断点没有绑定

你正在调试的进程不是在 Debug 模式下构建的，请确保在调试进程之前以调试模式进行构建。

C# 编辑器

我如何让智能感知（IntelliSense）正常工作？

确保你已打开一个项目或解决方案。如果你有多个解决方案，扩展会自动打开一个或提示你打开一个。接下来，在设置搜索栏中搜索“Trace”，并将 **Dotnet** > **Server:** 从下拉菜单中设置为 **Trace**。此选项提供更多的输出信息，以帮助开发团队诊断问题。

Set Dotnet Server to Trace

做出此更改后，通过打开命令面板（⇧⌘P (Windows、Linux 为 Ctrl+Shift+P)），然后输入“Reload Window”并按 Enter 来重新加载窗口。重新加载窗口后，检查输出面板（⇧⌘U (Windows 为 Ctrl+Shift+U，Linux 为 Ctrl+K Ctrl+H)）中的项目日志，并从下拉菜单中选择**项目**。这将显示与你的项目未完全加载相关的任何错误。复制输出面板中的所有文本，并通过 VS Code 报告问题，确保包含复制的文本。

C# 扩展无法启动服务器

作为一种解决方法，你可以通过 dotnetAcquisitionExtension.existingDotnetPath 设置，将 .NET 运行时获取扩展指向一个已有的 .NET 7 安装。

{
  "dotnetAcquisitionExtension.existingDotnetPath": [
    {
      "extensionId": "msazuretools.azurerm-vscode-tools",
      "path": "C\\Program Files\\dotnet\\dotnet.exe"
    }
  ]
}

我有太多诊断信息，或者我没有足够的诊断信息

C# 扩展允许你配置各种后台代码分析设置。要访问这些设置，请转到文件 > 首选项 > 设置或使用键盘快捷键（⌘, (Windows、Linux 为 Ctrl+,)）。在搜索栏中，输入“analysis”以缩小与代码分析相关的设置范围。在**运行后台代码分析范围：**下，你可以从下拉菜单中选择分析范围。默认设置是分析打开的文件，但你可以将其自定义为整个解决方案、无或打开的文档。

Configure Background Code Analysis

你也可以使用 EditorConfig 文件来配置诊断和代码分析。要了解有关 EditorConfig 的更多信息，请查看文档。

如果你没有看到足够的诊断信息或根本没有，可能是因为你的项目没有完全加载。要检查是否是这种情况，请参阅我如何让智能感知（IntelliSense）正常工作？部分。它提供了如何验证项目是否完全加载的说明。

Razor 编辑器

大多数或所有 Blazor 组件都显示警告

在发现 Blazor 组件之前，C# 开发工具包需要成功加载你的项目。此外，Razor 语言服务器需要生成一个 project.razor.vscode.bin 文件才能理解你的项目状态。如果此文件未生成，或者生成时没有任何组件，Razor 体验可能会受到影响。

为了提高性能，扩展有时会推迟生成或加载此文件，直到你打开第一个 .razor 或 .cshtml 文件。为确保你要使用的项目在解决方案资源管理器中没有错误，请仔细检查它。

如果你的项目已正确加载，请验证文件系统中是否存在 project.razor.vscode.bin 文件，位于 obj\Debug\<tfm> 文件夹中。由于它是一个二进制文件，直接验证文件内容并不简单，但总的来说，大多数 Razor 项目应该会生成一个至少 150KB 大小的文件。如果文件只有几千字节，则意味着标记帮助程序和/或组件可能没有被正确发现。

要强制重新生成文件，请关闭所有打开的 .razor 或 .cshtml 文件，重新加载 VS Code 窗口，并在项目正确加载后，打开任何 .razor 或 .cshtml 文件以触发重新生成过程。

Razor 文件中提到了目标框架错误

Razor 语言服务器通常没有“解决方案”的概念，而是根据项目 obj\Debug\<tfm> 文件夹中是否存在 project.razor.vscode.bin 文件来加载项目。有时，来自不再使用的目标框架的旧文件可能会引起混淆，使 Razor 服务器认为项目是多目标的，或者某些组件仍然被引用而实际上并非如此。

要解决此问题，请清除 obj 文件夹中的旧文件夹或清除所有文件夹。然后，重新加载 VS Code 窗口并打开一个 .razor 文件。这应确保生成新的 JSON 文件，并移除旧文件。

IntelliCode

我没有得到整行补全

当GitHub Copilot扩展启用时，整行补全功能会被禁用，以便你利用更高级的AI 补全功能。你可以通过检查 VS Code 右下角是否存在 Copilot 徽标来验证 Copilot 是否已启用。

热重载

我开始调试后，热重载图标没有出现

只有在 C# 开发工具包调试器设置中启用了热重载选项时，调试器才会启动热重载会话。如果该选项已启用，预计在调试时热重载图标会出现在状态栏中

Hot Reload icon in the bottom bar

你可以点击热重载图标，或者通过打开 **C# Hot Reload** 输出窗口查看诊断信息。如果你两者都看不到，则该项目可能不受 C# 开发工具包扩展的支持，请参阅热重载支持的项目。

热重载支持哪些类型的编辑？

有关热重载支持的 C# 代码更改列表，请参阅支持的代码更改。

5/3/2024