💻 欢迎参加 6 月 3 日 MS Build 上的 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 样式”项目）。如果您正在构建非 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. 未安装 2.0 及以上版本的 C# 扩展。C# Dev Kit 需要 2.0 或更高版本的 C# 扩展。请检查确保您已安装 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（或更高版本）订阅。此外，GitHub Codespaces 和 Microsoft Dev Box 中也包含 C# Dev Kit，因此这些产品的用户可以免费使用该工具。

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

用户可以通过 VS Code 的 Help > Report Issue（帮助 > 报告问题）功能来提交问题或建议。选择该条目属于 Bug、功能需求还是性能问题，在 An extension（某个扩展）下归档，并从扩展列表中选择 C# Dev Kit。

Help > Report Issue image

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

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

我该如何贡献？

作为 C# Dev Kit 一部分的 C# 扩展是完全开源的，并受这些许可条款约束。该扩展的源代码可在 https://github.com/dotnet/vscode-csharp 获取，并采用 MIT 许可证授权。

本项目采用了 Contributor Covenant 定义的行为准则，以明确社区中的预期行为。有关详细信息，请参阅 .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 设置。您可以从 C# Dev Kit Walkthrough（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 功能。

或者，您可以使用设置编辑器中的 Prefer CSharp Extension（偏好 C# 扩展）工作区设置，将项目和解决方案的加载委托给 C# 扩展。请记住，启用此设置后，某些 C# Dev Kit 功能将不可用。要访问此设置，请进入设置编辑器并选择 Workspace（工作区）选项卡，在搜索栏中搜索“Prefer CSharp”，并勾选 Prefer CSharp Extension 设置旁边的框。如果您尝试加载 .NET Framework 项目，C# Dev Kit 会自动显示一个通知，要求您选择将项目更新为 SDK 样式项目，或点击通知中的 Use C# Extension（使用 C# 扩展）让 C# 扩展加载您的项目或解决方案。此选项会自动选中 Prefer CSharp Extension 设置。请注意，您需要重新加载 VS Code 才能使此设置生效。

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

这通常是因为扩展版本不匹配。C# Dev Kit 需要 C# 扩展 2.0 或更高版本。如果您正在使用 v1 版本的 C# 扩展，C# Dev Kit 及其相关命令将无法正常工作。要解决此问题，请将 C# 扩展升级到最新版本。

项目系统报告运行出错

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

Failed to Restore Solution

选择 Open log（打开日志）按钮以打开显示问题发生位置的堆栈跟踪视图。选择并复制日志中的所有文本。通过 VS Code 报告问题，并务必附上从日志中复制的文本。

当我打开解决方案时，收到“Failed to restore solution”（无法还原解决方案）通知

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

解决方案资源管理器显示“A compatible .NET SDK was not found”（未找到兼容的 .NET SDK）

导致此错误最可能的原因是 global.json 文件指定了系统中未安装的 SDK 版本。

A compatible .NET SDK was not found

打开输出窗口并切换到 Projects（项目）窗格以查看更多信息。您应该会看到类似以下内容：

Output Window Projects Pane

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

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

也有可能是 SDK 安装在 C# Dev Kit 无法识别的位置。例如，如果 SDK 是通过包管理器而非 Microsoft 提供的安装程序安装的，就可能发生这种情况。要解决此问题，请通过包管理器卸载 SDK，然后通过 .NET 下载页面重新安装。

测试资源管理器

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

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

C# Dev Kit 还要求您在测试出现在测试资源管理器面板之前，已成功构建项目。此外，如果对您的项目/解决方案执行了 Clean（清理），测试 dll 将从测试资源管理器面板中移除。

一旦验证您的测试项目属于解决方案的一部分，请通过右键单击解决方案资源管理器中的解决方案并选择 Build（构建），或者使用 ⇧⌘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 可能无法被检测到，因为它们偏离了 Microsoft 的官方安装方法。我们建议遵循官方说明。
  • 构建输出：确认构建已完成并生成了相应的输出二进制文件，例如 .dll 或 .exe 文件。
  • 项目加载：确保所有项目均已完成加载。在解决方案资源管理器中，检查测试项目旁是否有测试图标，以确认它们已被识别。

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

确保您的测试目标是 .NET Core。C# Dev Kit 不支持 .NET Framework 项目，尽管 .NET Framework 项目可能会加载并看起来能运行，但 VS Code 中的调试器不支持 .NET Framework。

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

C# Dev Kit 要求您在测试出现在测试资源管理器面板之前，已成功构建项目。

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

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

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

  1. 提高测试资源管理器的详细程度：导航至 C# Dev Kit 设置，将“Test Explorer Verbosity”（测试资源管理器详细程度）设置从 minimal（最低）改为 diagnostic（诊断）。这将生成更详细的日志。
  2. 检查输出窗口：在 Visual Studio Code 中打开输出窗口，并从下拉菜单中选择 C# Dev Kit - Test Explorer。诊断消息将带有 [dev] 前缀。
  3. 收集以下信息：报告问题时，请确保包含：
    • 来自输出窗口的诊断日志。
    • 您的操作系统及版本（例如 Windows 10, macOS 13）。
    • 您正在使用的 C# Dev Kit 扩展的版本。进入扩展视图，将鼠标悬停在扩展上即可查看版本信息。

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

调试器

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

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

当我按 F5 时，它提示我“Select a Debugger”（选择调试器）。我怎么知道选哪一个？

如果您正在尝试调试 .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# 编辑器

如何让 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)) 并从下拉菜单中选择 Projects（项目）。这将显示与您的项目未完全加载相关的任何错误。复制输出面板中的所有文本并报告问题，务必包含复制的文本。

C# 扩展无法启动服务器

作为变通方法，您可以使用 dotnetAcquisitionExtension.existingDotnetPath 设置将 .NET 运行时获取扩展指向现有的 .NET 7 安装路径。

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

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

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

Configure Background Code Analysis

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

如果您没有看到足够的诊断信息，或者根本没有，很可能是因为您的项目没有完全加载。要检查是否如此，请参考如何让 IntelliSense 正常工作？部分，该部分提供了验证项目是否完全加载的说明。

Razor 编辑器

大部分或所有 Blazor 组件都显示警告

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

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

如果您的项目已正确加载，请验证文件系统中 obj\Debug\ 文件夹内是否存在 project.razor.vscode.bin 文件。由于它是二进制文件，直接验证其内容并不容易，但通常大多数 Razor 项目应生成至少 150KB 大小的文件。如果文件只有几千字节，则意味着标记助手 (Tag Helpers) 和/或组件可能未被正确识别。

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

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

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

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

IntelliCode

我没有获得整行补全

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

热重载 (Hot Reload)

开始调试后，热重载 (Hot Reload) 图标未出现

只有在 C# Dev Kit 调试器设置中启用了热重载选项，调试器才会启动热重载会话。如果该选项已启用，热重载图标应该在调试时出现在状态栏中。

Hot Reload icon in the bottom bar

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

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

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

5/3/2024
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.