🚀 在 VS Code 中！

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

使用此常见问题解答 (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# 开发工具包未激活的原因有以下几种：

  1. 未安装 C# 扩展的 2.0+ 版本。 C# 开发工具包需要 C# 扩展的 2.0 或更高版本。 检查以确保您已安装 C# 扩展，并且版本为 2.0 或更高版本。
  2. 工作区首选 C# 扩展。 C# 开发工具包不支持 .NET Framework 项目，如果您已将 dotnet.preferCSharpExtension 设置为 true，则 C# 开发工具包将对该工作区禁用。 如果项目不是 .NET Framework 项目，请确保禁用此设置。
  3. 使用只读 OS。 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 的帮助 > 报告问题报告问题或提出建议。 选择是 Bug、功能请求还是性能问题，在扩展上提交，然后从扩展列表中选择 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 许可证获得许可。

本项目已采用 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# 开发工具包演练或 .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# 开发工具包中不受支持

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

Project Not Supported in Solution Explorer

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

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

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

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

这通常发生在扩展版本不匹配时。 C# 开发工具包需要 C# 扩展的 2.0 或更高版本。 如果您使用的是 C# 扩展的 v1 版本，则 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 是通过程序包管理器而不是通过 Microsoft 提供的安装程序安装的，则可能会发生这种情况。 要解决此问题，请通过程序包管理器卸载 SDK，然后通过 下载 .NET 安装它。

测试资源管理器

为什么我的测试未显示在“测试资源管理器”面板中？

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

C# 开发工具包还要求在测试出现在“测试资源管理器”面板中之前，它已成功构建您的项目。 此外，如果对您的项目/解决方案执行清理，则测试 dll 将从“测试资源管理器”面板中删除。

在您验证测试项目是解决方案的一部分后，通过右键单击“解决方案资源管理器”中的解决方案并选择生成或使用 ⇧⌘B（Windows、Linux Ctrl+Shift+B）来构建您的解决方案。 生成完成后，您的测试将出现在“测试资源管理器”面板中。

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

确保您的测试目标是 NET Core。 C# 开发工具包不支持 .NET Framework 项目，尽管 .NET Framework 项目可能会加载并显示为可以工作。 VS Code 中的调试器不支持 .NET Framework。

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

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

通过右键单击“解决方案资源管理器”中的解决方案并选择生成或 ⇧⌘B（Windows、Linux Ctrl+Shift+B）来构建您的解决方案。 生成完成后，您的测试将出现在“测试资源管理器”面板中。

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

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

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

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

调试器

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

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

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

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

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

macOS 默认禁用开发人员模式，如果程序要用作调试器，则会提示输入密码以保护用户。

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

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

为什么调试不起作用？

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

调试时，我的断点未绑定

您正在调试的进程不是在调试中构建的，请确保在调试进程之前构建为调试。

C# 编辑器

如何使 IntelliSense 正常工作？

确保您已打开项目或解决方案。 如果您有多个解决方案，扩展将自动打开一个解决方案或提示您打开一个解决方案。 接下来，在“设置”搜索栏中搜索“Trace”，然后从下拉列表中将 Dotnet > 服务器：设置为 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# 扩展无法启动服务器

作为一种解决方法，您可以将 .NET 运行时获取扩展指向现有的 .NET 7 安装，方法是使用 dotnetAcquisitionExtension.existingDotnetPath 设置

{
  "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 大小的文件。 如果文件只有几 KB，则意味着标记帮助程序和/或组件可能未被正确发现。

要强制文件重新生成，请关闭任何打开的 .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 补全功能。 您可以通过检查 Copilot 徽标是否出现在 VS Code 的右下角来验证 Copilot 是否已启用。

热重载

启动调试后，热重载图标未出现

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

Hot Reload icon in the bottom bar

您可以单击热重载图标，也可以通过打开 C# 热重载“输出”窗口来查看诊断信息。 如果您没有看到其中任何一个，则项目可能不受 C# 开发工具包扩展支持，请参阅 热重载支持的项目。

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

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

5/3/2024