为 GitHub Codespaces 设置 C#（.NET）项目

简介

本教程指南向您展示如何使用 Visual Studio Code Web 客户端在 GitHub Codespaces 中设置示例 C# (.NET) 项目。它将逐步指导您在代码空间中打开项目，以及添加和修改预定义的开发容器配置。

完成本教程后，您将能够使用 VS Code Web 客户端或 VS Code 桌面应用程序将开发容器配置添加到自己的存储库。

有关开发容器的更多信息，请参阅“开发容器简介”。

步骤 1：在代码空间中打开项目

1. 登录 GitHub.com，如果您尚未登录。

2. 转到 https://github.com/microsoft/vscode-remote-try-dotnet。

3. 单击“使用此模板”，然后单击“在代码空间中打开”。

   

创建代码空间时，您的项目将创建在一个专门用于您的远程虚拟机上。默认情况下，您的代码空间容器具有多种语言和运行时，包括 .NET。它还包括一组常见的工具，如 git、wget、rsync、openssh 和 nano。

您可以通过调整 vCPU 和 RAM 的数量、添加 dotfiles 来个性化您的环境，或修改已安装的工具和脚本来自定义您的代码空间。有关更多信息，请参阅“自定义您的代码空间”。

GitHub Codespaces 使用名为 devcontainer.json 的文件来配置您在代码空间中工作时使用的开发容器。每个存储库可以包含一个或多个 devcontainer.json 文件，以便为您提供在代码空间中处理代码所需的开发环境。

启动时，GitHub Codespaces 使用 devcontainer.json 文件以及构成开发容器配置的任何依赖文件来安装工具和运行时，并执行项目所需的其它设置任务。有关更多信息，请参阅“开发容器简介”。

步骤 2：添加开发容器配置

GitHub Codespaces 的默认开发容器或“开发容器”附带最新 .NET 版本和预安装的常用工具。但是，我们建议你配置自己的开发容器，以包含你的项目所需的所有工具和脚本。这将确保存储库中所有 GitHub Codespaces 用户拥有一个完全可再现的环境。

要设置你的存储库以使用自定义开发容器，你需要创建一个或多个 devcontainer.json 文件。你可以在 Visual Studio Code 中从预定义的配置模板添加这些文件，也可以自行编写。有关开发容器配置的详细信息，请参阅“开发容器简介”。

1. 访问 Visual Studio Code 命令面板（Shift+Command+P / Ctrl+Shift+P），然后开始键入“add dev”。单击Codespaces：添加开发容器配置文件。

   

2. 单击创建新配置。

3. 在此示例中，你从中创建 Codespace 的模板存储库已包含开发容器配置，因此会显示一条消息，告知你配置文件已存在。我们将覆盖现有配置文件，因此请单击继续。

4. 单击显示所有定义。

   

5. 键入 c# 并单击C#（.NET）。如果你的项目使用特定工具，则还有其他选项可用。例如，C# 和 MS SQL。

   

6. 选择你希望用于项目的 .NET 版本。在此情况下，选择标记为“（默认）”的版本。

   

7. 将显示其他功能的列表。我们将安装 .NET CLI，这是一个用于开发、构建、运行和发布 .NET 应用程序的命令行界面。要安装此工具，请键入 dotnet，选择Dotnet CLI，然后单击确定。

   

8. 将显示一条消息，告知你开发容器配置文件已存在。单击覆盖。

   将创建一个 devcontainer.json 文件，并在编辑器中将其打开。

自定义开发容器配置的详细信息

如果你在 Visual Studio Code 资源管理器中查看，你会看到已将 .devcontainer 目录添加到项目存储库的根目录中，其中包含 devcontainer.json 文件。这是从此存储库创建的 Codespaces 的主配置文件。

devcontainer.json

您添加的 devcontainer.json 文件将包含 name、image 和 features 属性的值。其中包含一些您可能觉得有用的其他属性，但已注释掉。

该文件将类似于此，具体取决于您选择的映像

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/dotnet
{
  "name": "C# (.NET)",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/dotnet:0-7.0",
  "features": {
    "ghcr.io/devcontainers/features/dotnet:1": {}
  }

  // Features to add to the dev container. More info: https://containers.dev/features.
  // "features": {},

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  // "forwardPorts": [5000, 5001],
  // "portsAttributes": {
  //   "5001": {
  //     "protocol": "https"
  //   }
  // }

  // Use 'postCreateCommand' to run commands after the container is created.
  // "postCreateCommand": "dotnet restore",

  // Configure tool-specific properties.
  // "customizations": {},

  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}

• name：您可以按自己的意愿为开发容器命名。已提供默认值。
• image：容器注册表（DockerHub、GitHub 容器注册表 或 Azure 容器注册表）中映像的名称，该映像将用于为代码空间创建开发容器。
• features：一个或多个对象的列表，每个对象都引用一个可用的开发容器功能。功能是自包含的、可共享的安装代码和开发容器配置单元。它们提供了一种简单的方法，可将更多工具、运行时或库功能添加到您的开发容器。您可以在 VS Code 中或 GitHub.com 上的 devcontainer.json 编辑器中添加功能。有关详细信息，请在“将功能添加到 devcontainer.json 文件”中单击 Visual Studio Code 或 Web 浏览器 选项卡。
• forwardPorts：此处列出的任何端口都将自动转发。有关详细信息，请参阅“在您的代码空间中转发端口”。
• portsAttributes - 此属性将指定端口映射到一个或多个默认选项。有关详细信息，请参阅开发容器网站上的 开发容器规范。
• postCreateCommand：使用此属性在创建代码空间后运行命令。这可以格式化为字符串（如上所述）、数组或对象。有关详细信息，请参阅开发容器网站上的 开发容器规范。
• customizations：此属性允许您在用于在代码空间中工作时自定义特定工具或服务。例如，您可以为 VS Code 配置特定设置和扩展。有关详细信息，请参阅开发容器网站上的“支持的工具和服务”。
• remoteUser：默认情况下，您以 vscode 用户身份运行，但可以选择将其设置为 root。

有关可用属性的完整列表，请参阅开发容器网站上的 开发容器规范。

其他开发容器配置文件

如果您熟悉 Docker，则除了 devcontainer.json 文件外，您可能还想使用 Dockerfile 或 Docker Compose 来配置您的 Codespace 环境。您可以通过将 Dockerfile 或 docker-compose.yml 文件与 devcontainer.json 文件一起添加来执行此操作。有关更多信息，请参阅开发容器网站上的“使用映像、Dockerfile 和 Docker Compose”。

步骤 3：修改您的 devcontainer.json 文件

在添加了开发容器配置并对所有内容的基本了解后，您现在可以进行更改以进一步自定义您的环境。在此示例中，您将添加以下属性

• 将应用程序在远程计算机上运行的端口转发到您的本地计算机。
• 在创建开发容器后运行 dotnet restore，以还原应用程序所需的依赖项。
• 在此 Codespace 中自动安装 VS Code 扩展。

1. 在 devcontainer.json 文件中，在 features 属性后添加一个逗号，并删除有关功能的两条注释行。

   JSONC

     "features": {
       "ghcr.io/devcontainers/features/dotnet:1": {}
     },
   
     // Features to add to the dev container. More info: https://containers.dev/features.
     // "features": {},
   

2. 取消注释 forwardPorts 属性，并仅将其值更改为端口 5000。

   JSONC

   // Use 'forwardPorts' to make a list of ports inside the container available locally.
   "forwardPorts": [5000],
   

3. 取消注释 postCreateCommand 属性。

   JSONC

   // Use 'postCreateCommand' to run commands after the container is created.
   "postCreateCommand": "dotnet restore",
   

4. 取消注释 customizations 属性，并按如下方式对其进行编辑以安装“Code Spell Checker”VS Code 扩展。

   JSONC

   // Configure tool-specific properties.
   "customizations": {
     // Configure properties specific to VS Code.
     "vscode": {
       // Add the IDs of extensions you want installed when the container is created.
       "extensions": [
         "streetsidesoftware.code-spell-checker"
       ]
     }
   }
   

   devcontainer.json 文件现在应与此类似，具体取决于您选择的映像

   // For format details, see https://aka.ms/devcontainer.json. For config options, see the
   // README at: https://github.com/devcontainers/templates/tree/main/src/dotnet
   {
     "name": "C# (.NET)",
     // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
     "image": "mcr.microsoft.com/devcontainers/dotnet:0-7.0",
     "features": {
       "ghcr.io/devcontainers/features/dotnet:1": {}
     },
   
     // Use 'forwardPorts' to make a list of ports inside the container available locally.
     "forwardPorts": [5000],
     // "portsAttributes": {
     //   "5001": {
     //     "protocol": "https"
     //   }
     // }
   
     // Use 'postCreateCommand' to run commands after the container is created.
     "postCreateCommand": "dotnet restore",
   
     // Configure tool-specific properties.
     "customizations": {
       // Configure properties specific to VS Code.
       "vscode": {
         // Add the IDs of extensions you want installed when the container is created.
         "extensions": [
           "streetsidesoftware.code-spell-checker"
         ]
       }
     }
   
     // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
     // "remoteUser": "root"
   }
   

5. 保存您的更改。

6. 访问 VS Code 命令面板（Shift+Command+P / Ctrl+Shift+P），然后开始键入“重建”。单击Codespaces：重建容器。

   

   提示：您可能偶尔需要执行完全重建以清除缓存并使用新映像重建您的容器。有关更多信息，请参阅“在 Codespace 中重建容器”。

   在代码空间内重建可确保在将更改提交到存储库之前，更改按预期工作。如果确实导致失败，你将被置于一个具有恢复容器的代码空间中，你可以从中进行重建，以继续调整容器。

   在重新构建开发容器后，代码空间再次可用，postCreateCommand 将运行，恢复所需的依赖项，并且“代码拼写检查器”扩展将可供使用。

步骤 4：运行应用程序

在上一部分中，你使用 postCreateCommand 通过 dotnet restore 命令安装了一组包。现在已安装依赖项，你可以运行应用程序。

1. 按 F5 或在终端中输入 dotnet watch run 来运行应用程序。

2. 当应用程序启动时，单击端口选项卡，右键单击端口 5000，然后单击在浏览器中打开。

   

步骤 5：提交更改

当你对代码空间进行更改（新代码或配置更改）时，你将希望提交更改。将配置更改提交到存储库可确保从该存储库创建代码空间的任何其他人都具有相同的配置。你所做的任何自定义（例如添加 VS Code 扩展）都将对所有用户可用。

对于本教程，你从模板存储库创建了代码空间，因此代码空间中的代码尚未存储在存储库中。你可以通过将当前分支发布到 GitHub.com 来创建存储库。

有关信息，请参阅“在代码空间中使用源代码管理”。

后续步骤

你现在应该能够向自己的 C#（.NET）项目添加自定义开发容器配置。

以下是一些针对更高级方案的附加资源。

• "向 devcontainer.json 文件添加功能"
• "管理 GitHub Codespaces 的特定于帐户的机密"
• "管理 GitHub Codespaces 的 GPG 验证"
• "在 Codespace 中转发端口"