在 VS Code 中试用！

C# Dev Kit 常见问题

使用此 FAQ（常见问题解答）主题详细了解 C# Dev Kit 扩展并排除您可能遇到的问题。

常规

什么是 C# Dev Kit？

C# Dev Kit 是一个旨在增强您在 Visual Studio Code 中的 C# 开发体验的扩展。它致力于为 VS Code 带来更广阔、高效且可靠的 C# 体验。C# Dev Kit 并未取代现有的 C# 扩展，而是在其提供的强大语言服务功能之上进行了补充。开发者可以选择继续使用现有 C# 扩展的更新版本，或者通过添加 C# Dev Kit 来增强体验。

目前支持哪些项目类型？

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

C# Dev Kit 中包含哪些扩展？

目前，C# Dev Kit 系列中包含的扩展有：

这些扩展的使用受C# Dev Kit 系列扩展的 EULA 约束。

这些扩展也包含带有其自身许可的依赖项，例如，C# Dev Kit 依赖于 C# 扩展和 .NET 安装工具。

为什么 C# Dev Kit 未激活 / 找不到 C# Dev Kit 命令？

尝试编辑 C# 文件时，C# Dev Kit 未激活有几个原因。

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

如果您已检查上述情况，但仍然找不到 C# Dev Kit 命令，请报告问题并提供 C# Dev Kit 输出窗口中的信息。

许可和贡献

谁可以使用 C# Dev Kit？

C# Dev Kit 通过社区许可向符合条件的用户提供，并且作为现有 Visual Studio 订阅的另一补充。这意味着，拥有有效 Visual Studio 订阅的开发者今天就可以开始使用 C# Dev Kit。

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

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

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

Help > Report Issue image

C# Dev Kit 是开源的吗？为什么不是？

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

如何贡献？

C# 扩展（它是 C# Dev Kit 的一部分）是完全开源的，并受 这些许可条款的约束。该扩展的源代码可在 https://github.com/dotnet/vscode-csharp 上获取，并根据 MIT 许可进行许可。

本项目采用了由 贡献者盟约 (Contributor Covenant) 定义的行为准则，以阐明我们社区中预期的行为。有关更多信息，请参阅 .NET Foundation 行为准则。通过签署 CLA，社区可以自由地将您的贡献用于 .NET Foundation 项目。

.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 设置。您可以从C# Dev Kit 演练或.NET 网站手动安装 .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# Dev Kit 中不受支持

这通常是因为项目面向的是 .NET Framework 而非 .NET Core/.NET。目前，C# Dev Kit 不支持 .NET Framework 项目。

Project Not Supported in Solution Explorer

要解决此问题，您有两个选项。

您可以将项目更新为 SDK 样式的项目，以便访问所有可用的 C# Dev Kit 功能。

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

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

这通常发生在扩展版本不匹配时。C# Dev Kit 需要 C# 扩展的 2.0 或更高版本。如果您使用的是 C# 扩展的 v1 版本，C# Dev Kit 以及与 C# Dev Kit 相关的命令将无法正常工作。要解决此问题，请将 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# Dev Kit 已知的位置。例如，如果 SDK 是通过包管理器而不是 Microsoft 提供的安装程序安装的，则可能会发生这种情况。要解决此问题，请通过包管理器卸载 SDK，然后通过下载 .NET 进行安装。

测试资源管理器

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

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

C# Dev Kit 还要求您的项目成功生成后，测试才会出现在测试资源管理器面板中。此外，如果对项目/解决方案执行了清理操作，则测试 dll 将从测试资源管理器面板中移除。

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

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

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

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

请确保您的测试面向 .NET Core。C# Dev Kit 不支持 .NET Framework 项目，尽管 .NET Framework 项目可能会加载并看起来可以工作。VS Code 中的调试器不支持 .NET Framework。

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

C# Dev Kit 要求您的项目成功生成后，测试才会出现在测试资源管理器面板中。

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

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

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

按照以下步骤启用设置：

  1. 在 VS Code 中打开设置：转到 文件 > 首选项 > 设置（或按 ⌘, (Windows, Linux Ctrl+,)）。
  2. 在设置搜索栏中，键入“Test Window”以筛选结果。
  3. 在 C# Dev Kit 扩展设置下找到 Dotnet > 测试窗口：使用测试平台协议 设置。
  4. 勾选此框以启用它（或将其切换为“开”）。
  5. 通过在命令面板中运行重新加载窗口命令重新加载 VS Code（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。

启用此设置后，您的测试应能正常在测试资源管理器中被发现和运行。

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

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

  1. 增加测试资源管理器详细程度：导航到 C# Dev Kit 设置，并将测试资源管理器详细程度设置从 minimal 更改为 diagnostic。这将生成更详细的日志。
  2. 检查输出窗口：在 Visual Studio Code 中打开输出窗口，并从下拉列表中选择C# Dev Kit - 测试资源管理器。诊断消息将以 [dev] 前缀显示。
  3. 收集以下信息：报告问题时，请务必包含：
    • 输出窗口中的诊断日志。
    • 您的操作系统和版本（例如，Windows 10、macOS 13）。
    • 您使用的 C# Dev Kit 扩展版本。转到扩展视图，将鼠标悬停在扩展上以查看版本信息。

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

调试器

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

确保您已打开 C# 项目，或者活动文档是 .cs 或 .razor 文件。如果调试器仍然无法加载，请确保 C# Dev Kit 和 C# 扩展都已激活。

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

如果您正在尝试调试 .NET 控制台应用、Blazor Server 应用、Blazor WebAssembly 或 Web 应用，请务必选择C#选项。其他选项可能是其他扩展的一部分，例如用于 JavaScript 调试的 Node 或用于 Python 调试的 Python，它们不是 C# Dev Kit 的一部分。

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

macOS 默认禁用开发者模式，并且在程序想要用作调试器时提示输入密码以保护用户。

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

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

为什么调试不起作用？

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

调试时，我的断点未绑定

您正在调试的进程未在 Debug 配置下生成，请确保在调试进程之前将其生成为 Debug 配置。

C# 编辑器

如何使智能感知正常工作？

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

Set Dotnet Server to Trace

完成此更改后，通过打开命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)），然后输入“重新加载窗口”并按 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，请查阅文档。

如果您看到的诊断信息不足或根本没有，可能是您的项目未完全加载。要检查是否属于这种情况，请参阅如何使智能感知正常工作？部分。它提供了关于如何验证项目是否完全加载的说明。

Razor 编辑器

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

在可以发现 Blazor 组件之前，C# Dev Kit 需要成功加载您的项目。此外，Razor 语言服务器需要生成一个 project.razor.vscode.bin 文件，以便理解项目的状态。如果未生成此文件，或者生成的文件不包含任何组件，则 Razor 体验可能会受到影响。

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

如果您的项目已正确加载，请验证您的文件系统上 obj\Debug\<tfm> 文件夹中是否存在 project.razor.vscode.bin 文件。由于它是二进制文件，无法直接验证文件内容，但一般来说，大多数 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# Dev Kit 的调试器设置中启用热重载选项时启动热重载会话。如果选项已启用，则在调试期间状态栏中应出现热重载图标：

Hot Reload icon in the bottom bar

您可以点击热重载图标，也可以通过打开C# 热重载输出窗口查看诊断信息。如果您没有看到任何一个，则该项目可能不受 C# Dev Kit 扩展的支持，请参阅热重载支持的项目。

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

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

5/3/2024