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

请使用这个常见问题（常见问题）主题，了解更多关于C#开发套件扩展的信息，并排查您可能遇到的问题。

概述

什么是C#开发工具包？

C# 开发工具包是一个扩展，旨在提升您在 Visual Studio Code 中的 C# 开发体验。它旨在为 VS Code 带来更广泛、高效且可靠的 C# 体验。C# 开发工具包并未取代现有的 C# 扩展，而是在其提供的优秀语言服务功能基础上增加了新内容。开发者可以选择继续使用已更新的 C# 扩展，或通过添加 C# 开发工具包来提升体验。

目前支持哪些项目类型？

C# 开发工具包支持为 .NET Core 构建网页应用、控制台应用、类库项目和测试项目，通常也称为 .NET。.NET MAUI 扩展和 Unity 扩展基于 C# Dev Kit，提供额外支持 .NET 多平台应用界面（MAUI）应用和 Unity 应用。这些扩展支持现代.NET项目格式，也称为“sdk风格”项目。如果你正在构建非SDK格式的项目，如.NET Framework应用和Xamarin应用，请参见项目系统部分。

C# 开发套件包含哪些扩展？

如今，C# 开发套件家族中包含的扩展包括：

这些扩展的使用受C#开发套件扩展家族的EULA规范。

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

为什么 C# 开发套件无法激活/找不到 C# 开发套件命令？

C# Dev Kit 在编辑 C#Files时无法激活有几个原因。

  1. 未安装 C# 扩展 2.0+ 版本。C# 开发工具包需要 C# 扩展的版本 2.0 或更高。检查一下你是否安装了C#扩展，并且是2.0版本或更高版本。
  2. 工作区偏好C#扩展。C# 开发工具包不支持 .NET Framework项目，如果你设置了dotnet.preferCSharpExtension设置为 true，C# 开发工具包将在该工作区中被禁用。如果项目不是.NET Framework项目，务必禁用该设置。
  3. 使用只读作系统。C# 开发套件需要写入其自己的扩展文件夹和VS Code提供的扩展文件夹，才能在作系统中写任意状态，因此如果你使用的作系统是完全可读的，C# 开发套件无法使用。

如果您已检查这些，但 C# 开发套件命令仍未找到，请报告问题并在 C# 开发套件的输出窗口中提供相关信息。

授权与贡献

谁能用C#开发工具包？

C# 开发工具包通过社区许可证供符合条件的人使用，同时也作为现有 Visual Studio 订阅的附加内容。这意味着 C# 开发工具包现已供拥有有效 Visual Studio 订阅的开发者使用。

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

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

用户可以通过VS Code的“帮助>举报问题”来报告问题或建议。选择是 bug、功能请求还是性能问题，文件设置为 A 扩展，并从扩展列表中选择 C# 开发套件。

帮助>报告问题图片

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

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

我该如何贡献？

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
}

Error acquiring .NET SDK

Error acquiring .NET SDK

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

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

将 .NET 运行时获取扩展指向已有的 .NET SDK 安装

我该如何手动安装.NET？

如果.NET安装失败，或者你想重用已有的.NET安装，你可以使用dotnetAcquisitionExtension.existingDotnetPath环境。.NET 可以从 C# 开发工具包攻略或 .NET 官网手动安装。要将扩展导向该安装，请更新设置，使用扩展ID和如下图所示的路径：

窗户

{
  "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 项目。

项目未被解决方案资源管理器支持

要解决这个问题，你有两个选择。

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

或者，你也可以在设置编辑器中的“偏好 CSharp 扩展工作区”设置中，将项目和解决方案的加载委托给 C# 扩展。请注意，有些 C# 开发套件功能不会在这个设置下使用。要访问该设置，进入设置编辑器，选择工作区标签。然后，在搜索栏中搜索“偏好 CSharp”，并勾选“偏好 CSharp 扩展”设置旁的选项。如果你试图加载一个 .NET Framework 项目，C# 开发工具包会自动显示通知，要求你将项目更新为 SDK 风格的项目，或者通过通知中选择使用 C# 扩展来加载你的项目或解决方案。该选项会自动选择“偏好CSharp扩展”设置。注意你需要重新加载 VS Code 才能让这个设置生效。

我点击了“创建.NET项目”按钮，但什么都没发生

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

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

当项目系统内部出现错误时，你通常会在 VS Code 的某个角落看到类似的通知：

无法恢复解决方案

选择“打开日志”按钮，打开显示问题发生位置的堆栈追踪视图。选择并复制日志中的所有文本。通过VS Code报告问题，并确保包含日志中复制的文字。

当我打开我的解决方案时，会收到“无法恢复解决方案”的通知。

选择显示错误。这会打开NuGet的输出面板。请仔细阅读错误，了解为什么软件包还原无法完成。如果无法解决问题，请通过VS Code报告问题。

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

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

未找到兼容的.NET SDK

打开输出窗口，切换到项目面板以查找更多信息。你应该看看类似这样的内容：

输出窗口项目面板

要解决问题，要么更新global.json指定已安装的 SDK 或从 Download .NET 页面安装指定的 SDK。

接着关闭并重新打开工作区。

也有可能SDK未安装在C# Dev Kit已知的位置。例如，如果SDK是由包管理器安装，而不是通过Microsoft提供的安装程序安装的，就会发生这种情况。解决方法是通过包管理器卸载 SDK，然后通过 Download .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可能无法被检测，因为它们偏离了Microsoft官方的安装方法。我们建议遵循官方说明。
  • 构建输出：确认构建已完成并生成了相应的输出二进制文件，例如.dll或.exe文件。
  • 项目加载：确保所有项目都已完成加载。在解决方案资源管理器中，寻找测试项目旁边的测试图标，以确认它们已被检测到。

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

确保你的测试目标是 NET Core。C# 开发工具包不支持 .NET Framework 项目，尽管 .NET Framework 项目可能加载并看似正常。VS Code 中的调试器不支持 .NET Framework。

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

C# 开发套件要求它必须成功构建你的项目，测试才会出现在测试资源管理器面板中。

在解决方案资源管理器中右键点击解决方案，选择构建或⇧⌘B（Windows，Linux Ctrl+Shift+B）来构建你的解决方案。构建完成后，你的测试会显示在测试资源管理器面板中。

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

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

  1. 增加测试探索器的冗长内容： 进入 C# 开发工具包设置，从以下调高测试资源管理器的冗长度设置极简到诊断.这样可以生成更详细的日志。
  2. 查看输出窗口： 在Visual Studio Code中打开输出窗口，从下拉菜单中选择C#开发工具包 - 测试资源管理器。诊断信息将以[开发者]前缀。
  3. 收集以下信息： 报告问题时，请确保包含：
    • 输出窗口的诊断日志。
    • 你的作系统和版本（例如，Windows 10，macOS 13）。
    • 你正在使用的C#开发工具包扩展版本。进入扩展视图，将鼠标悬停在扩展上即可查看版本信息。

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

调试器

当我F5时，什么都没发生

确保你开着一个C#项目，或者当前文档是.cs或剃刀档案。如果调试器仍然加载失败，确保C#开发套件和C#扩展都已激活。

当我F5时，它会让我“选择一个调试器”。我怎么知道该选哪一个？

如果你想调试.NET控制台应用程序、Blazor Server Apps、Blazor WebAssembly或Web Applications，务必选择C#选项。其他选项可能属于其他扩展，如用于JavaScript调试的Node或用于Python调试的Python，这些都不包含在C# Dev Kit中。

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

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

如果您想禁用这些提示，可以执行以下命令：

  • DevToolsSecurity --enable
  • 须藤DSCL。附加 /Groups/_developer Group会员$USER

为什么调试不起作用？

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

调试时，断点没有绑定

你调试的进程不是在调试中构建的，所以在调试进程之前一定要先构建为调试。

C# 编辑器

我该如何让IntelliSense正常工作？

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

设置 Dotnet Server 进行追踪

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

C# 扩展无法启动服务器

作为一个变通方法，你可以将 .NET 运行时获取扩展指向已有的 .NET 7 安装，使用dotnetAcquisitionExtension.existingDotnetPath地点：

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

我有太多诊断，或者诊断不够

C#扩展允许你配置各种后台代码分析设置。要访问设置，请进入设置>文件 偏好设置>或使用键盘快捷键（⌘，（Windows，Linux Ctrl+，））。在搜索栏输入“分析”以缩小与代码分析相关的设置范围。在“运行后台代码分析for：”下拉菜单“中，你可以选择分析范围。默认设置是分析已打开的文件，但你可以自定义为完整解决方案、无解决方案或未打开文档。

配置后台代码分析

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

如果你没有看到足够的诊断，甚至根本没有，可能是你的项目没有完全加载。要确认是否如此，请参阅“如何让IntelliSense正常工作？”这一部分。它提供了如何验证项目是否已满载的说明。

剃刀编辑器

大部分或全部Blazor组件都会显示警告

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

为了提升性能，扩展有时会推迟生成或加载该文件，直到你打开第一个文件剃刀或.cshtml档案。为了确保你想使用的项目的解决方案管理器中没有错误，请仔细检查。

如果你的项目加载正确，请确认project.razor.vscode.bin文件存在于obj\Debug\<tfm>文件夹。由于是二进制文件，直接验证文件内容并不容易，但大多数 Razor 项目通常会得到至少 150KB 大小的文件。如果文件只有几千字节，说明标签辅助器和/或组件可能没有被正确发现。

要强制文件再生，关闭所有已打开的文件剃刀或.cshtml文件，重新加载 VS Code 窗口，项目正确加载后，打开任意剃刀或.cshtml文件以触发再生过程。

目标框架错误在Razor文件中被提及

Razor 语言服务器通常没有“解决方案”的概念，而是基于project.razor.vscode.bin项目中的档案obj\Debug\<tfm>文件夹。有时，来自已不再使用的目标框架的旧文件会导致混淆，使 Razor 服务器误以为项目是多目标的，或者某些组件仍然被引用，但实际上并非如此。

要解决这个问题，请清除目标全部文件夹或清除。然后，重新加载 VS Code 窗口并打开一个剃刀档案。这样可以确保生成新的JSON文件，并删除旧的。

IntelliCode

我没有收到整行的补足

启用GitHub Copilot扩展后，整行补全功能会被禁用，以便利用更先进的AI补全功能。你可以通过检查 VS Code 右下角是否有 Copilot 标志来验证 Copilot 是否已启用。

热装填

开始调试后热装填图标没有出现

调试器只有在 C# 开发套件调试器设置中启用热重载选项时，才会启动热加载会话。如果启用该选项，调试时状态栏中会出现热装填图标：

底部栏的热换弹图标

你可以点击热装填图标，或者打开C#热装填输出窗口查看诊断信息。如果你没有看到这些，说明该项目可能不被 C# 开发套件扩展支持，请参见 Hot Reload 支持项目。

热装填支持哪些类型的编辑？

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