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

简介

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

完成本教程后，你将能够使用 VS Code Web 客户端或 VS Code 桌面应用程序，将 dev 容器配置添加到自己的仓库中。

有关 dev 容器的更多信息，请参阅 dev 容器简介。

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

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

2. 前往 https://github.com/microsoft/vscode-remote-try-dotnet。

3. 点击 Use this template（使用此模板），然后点击 Open in a codespace（在代码空间中打开）。

   

当您创建代码空间时，您的项目会在专属于您的远程虚拟机上创建。默认情况下，代码空间的容器已预装多种语言和运行时，包括 .NET。它还包含常用工具，如 git、wget、rsync、openssh 和 nano。

你可以通过调整 vCPU 与 RAM 的配额、添加 dotfiles 来个性化环境，或修改已安装的工具和脚本来自定义代码空间。更多信息请参见 自定义你的代码空间。

GitHub Codespaces 使用名为 devcontainer.json 的文件来配置在代码空间中工作的开发容器。每个仓库可以包含一个或多个 devcontainer.json 文件，以提供恰好满足代码在代码空间中工作所需的开发环境。

启动时，GitHub Codespaces 会读取 devcontainer.json 文件及其所有依赖文件，安装所需的工具和运行时，并执行项目所需的其他设置任务。更多信息请参见 dev 容器简介。

步骤 2：添加 dev 容器配置

GitHub Codespaces 的默认开发容器（即 “dev container”）已预装最新的 .NET 版本和常用工具。不过，我们建议您自行配置开发容器，以包含项目所需的所有工具和脚本。这可确保您仓库中所有 GitHub Codespaces 用户拥有完全可复现的环境。

要让仓库使用自定义 dev 容器，需要创建一个或多个 devcontainer.json 文件。你可以在 Visual Studio Code 中从预定义的配置模板添加，也可以自行编写。有关 dev 容器配置的更多信息，请参见 dev 容器简介。

1. 打开 Visual Studio Code 命令面板（Shift+Command+P / Ctrl+Shift+P），开始输入 “add dev”。点击 Codespaces: Add Dev Container Configuration Files。

   

2. 点击 创建新配置。

3. 在本示例中，你创建代码空间时所使用的模板仓库已经包含了 dev 容器配置，因此会显示一条信息提示配置文件已存在。我们将覆盖现有配置文件，请点击 继续。

4. 点击 显示所有定义。

   

5. 输入 c# 并点击 C#（.NET）。如果您的项目使用特定工具，还可以选择其他选项，例如 C# 和 MS SQL。

   

6. 选择要用于项目的 .NET 版本。在本例中，选择标记为 “(default)” 的版本。

   

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

   

8. 系统提示 dev 容器配置文件已存在。点击 覆盖。

   已创建 devcontainer.json 文件，并在编辑器中打开。

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

在 Visual Studio Code 资源管理器中，你会看到项目根目录下新增了一个 .devcontainer 目录，里面包含 devcontainer.json 文件。这是从该仓库创建的代码空间的主要配置文件。

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.net.cn/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.net.cn/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: 你可以随意为 dev 容器命名，系统会提供一个默认值。
• image: 用于创建代码空间 dev 容器的容器镜像名称，来源于容器注册表（DockerHub、GitHub Container Registry 或 Azure Container Registry）。
• features: 一个或多个对象的列表，每个对象引用可用的 dev 容器功能之一。Features 是自包含、可共享的安装代码和容器配置单元，能够为你的开发容器轻松添加更多工具、运行时或库。你可以在 VS Code 中或在 GitHub 上的 devcontainer.json 编辑器中添加功能。更多信息请查看 Visual Studio Code 或 Web browser 选项卡 中的 “在 devcontainer.json 文件中添加功能”。
• forwardPorts: 此处列出的所有端口都会自动转发。更多信息请参见 代码空间端口转发。
• portsAttributes - 此属性将指定端口映射到一个或多个默认选项。更多信息请参阅开发容器网站上的 dev containers 规范。
• postCreateCommand: 使用此属性在代码空间创建后运行命令。它可以是字符串（如上所示）、数组或对象。更多信息请参阅 Development Containers 网站上的 dev containers 规范。
• customizations: 此属性允许在代码空间中使用特定工具或服务时进行自定义，例如为 VS Code 配置特定设置和扩展。更多信息请参阅 Development Containers 网站上的 Supporting tools and services。
• remoteUser: 默认情况下，你以 vscode 用户身份运行；如有需要，也可以将其设置为 root。

完整的可用属性列表请参见 Development Containers 网站上的 dev containers 规范。

其它 dev 容器配置文件

如果你熟悉 Docker，除了 devcontainer.json，还可以使用 Dockerfile 或 Docker Compose 来配置代码空间环境，只需将 Dockerfile 或 compose.yaml 与 devcontainer.json 放在同一目录下即可。更多信息请参考 Development Containers 网站上的 使用镜像、Dockerfile 与 Docker Compose。

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

在添加了 dev 容器配置并基本了解各属性作用后，你现在可以进一步自定义环境。本示例将添加以下属性：

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

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

   JSONC

     "features": {
       "ghcr.io/devcontainers/features/dotnet:1": {}
     },
   
     // Features to add to the dev container. More info: https://containers.net.cn/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.net.cn/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），输入 “rebuild”。点击 Codespaces: Rebuild Container。

   

   提示

   有时你可能需要执行完整的重建，以清除缓存并使用全新镜像重新构建容器。更多信息请参见 代码空间中的容器重建。在代码空间内部进行重建可以确保更改在提交到仓库前如预期般工作。如果出现故障，系统会将你置于带有恢复容器的代码空间，你可以从中重新构建以继续调整容器。

   在开发容器重新构建且代码空间再次可用后，postCreateCommand 将已执行，恢复所需的依赖项，并且 “Code Spell Checker” 扩展将可供使用。

步骤 4：运行你的应用程序

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

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

2. 应用启动后，点击 Ports 选项卡，右键单击 5000 端口并选择 Open in Browser（在浏览器中打开）。

   

步骤 5：提交你的更改

对代码空间进行更改后（无论是新代码还是配置），你都应提交这些更改。将配置提交到仓库可以确保以后任何人在此仓库创建代码空间时都能获得相同的配置。你所做的任何自定义（例如添加 VS Code 扩展）都将对所有用户生效。

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

相关信息请参阅 在代码空间中使用源代码管理。

后续步骤

现在，您应该可以为自己的 C#（.NET）项目添加自定义开发容器配置。

以下是一些面向更高级场景的补充资源。

• 向 devcontainer.json 文件添加功能
• 管理您针对 GitHub Codespaces 的帐户特定密钥
• 管理 GitHub Codespaces 的 GPG 验证
• 在代码空间中转发端口