Setting up a C# (.NET) project for GitHub Codespaces

Introduction

This tutorial guide shows you how to set up an example C# (.NET) project 在 Codespaces 中，使用 Visual Studio Code 桌面应用程序，或 VS Code Web 客户端。这样会向你演示在 codespace 中打开项目，以及添加和修改预定义开发容器配置的示例。

Step 1: Open the project in a codespace

Go to https://github.com/microsoft/vscode-remote-try-dotnet.
Click Use this template, then click Open in a codespace.

When you create a codespace, your project is created on a remote virtual machine that is dedicated to you. By default, the container for your codespace has many languages and runtimes, including .NET. It also includes a common set of tools like git, wget, rsync, openssh, and nano.

可以通过调整 vCPU 和 RAM 的数量、添加点文件来个性化环境或通过修改已安装的工具和脚本来自定义 codespace。

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

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

Step 2: Add a dev container configuration

The default development container, or "dev container," for GitHub Codespaces comes with the latest .NET version and common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.

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

访问 Visual Studio Code Command Palette (Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux))，然后开始键入“开发容器”。选择“代码空间: 添加开发容器配置文件...”。
Type c# and click C# (.NET). Other options are available if your project uses particular tools. For example, C# and MS SQL.
Click the latest version of .NET.
A list of additional features is displayed. We'll install the .NET CLI, a command-line interface for developing, building, running, and publishing .NET applications. To install this tool, type dotnet, select Dotnet CLI, then click OK.
A message is displayed telling you that the dev container configuration file already exists. Click Overwrite.

A devcontainer.json file is created and is opened in the editor.

Details of your custom dev container configuration

If you look in the Visual Studio Code Explorer you'll see that a .devcontainer directory has been added to the root of your project's repository containing the devcontainer.json file. This is the main configuration file for codespaces created from this repository.

devcontainer.json

The devcontainer.json file that you have added will contain values for the name, image, and features properties. Some additional properties that you may find useful are included but are commented out.

The file will look similar to this, depending on which image you chose:

// 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: You can name your dev container anything you want. A default value is supplied.
image: The name of an image in a container registry (DockerHub, GitHub Container registry, or Azure Container Registry) that will be used to create the dev container for the codespace.
features: A list of one or more objects, each of which references one of the available dev container features. Features are self-contained, shareable units of installation code and development container configuration. They provide an easy way to add more tooling, runtime, or library features to your development container. For more information, see "Available Dev Container Features" on the Development Containers website. You can add features by going to the VS Code Command Palette and typing features.
forwardPorts: Any ports listed here will be forwarded automatically. For more information, see "Forwarding ports in your codespace."
portsAttributes - This property maps a specified port to one or more default options. For more information, see the dev containers specification on the Development Containers website.
postCreateCommand: Use this property to run commands after your codespace is created.
customizations: This property allows you to customize a specific tool or service when it is used for working in a codespace. For example, you can configure specific settings and extensions for VS Code. For more information, see "Supporting tools and services" on the Development Containers website.
remoteUser: By default, you’re running as the vscode user, but you can optionally set this to root.

For a complete list of available properties, see the dev containers specification on the Development Containers website.

Additional dev container configuration files

If you are familiar with Docker, you may want to use a Dockerfile, or Docker Compose, to configure your codespace environment, in addition to the devcontainer.json file. You can do this by adding your Dockerfile or docker-compose.yml files alongside the devcontainer.json file. For more information, see "Using Images, Dockerfiles, and Docker Compose" on the Development Containers website.

Step 3: Modify your devcontainer.json file

With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties that will:

Forward the port on which the application runs on the remote machine to your local machine.
Run dotnet restore, after the dev container is created, to restore the dependencies required by the application.
Automatically install a VS Code extension in this codespace.

In the devcontainer.json file, add a comma after the features property, and delete the two commented out lines about features.

JSON

  "features": {
    "ghcr.io/devcontainers/features/dotnet:1": {}
  },

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

Uncomment the forwardPorts property and change its value to port 5000 only.

JSON

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

Uncomment the postCreateCommand property.

JSON

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

Uncomment the customizations property and edit it as follows to install the "Code Spell Checker" VS Code extension.

JSON

// 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"
    ]
  }
}

The devcontainer.json file should now look similar to this, depending on which image you chose:

// 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"
}

Save your changes.
访问 VS Code Command Palette (Shift+Command+P (Mac)/Ctrl+Shift+P (Windows/Linux))，然后开始键入“重新生成”。选择“代码空间: 重生成容器”。

提示：有时可能需要完全重新生成容器以清除缓存并使用新映像重新生成容器。有关详细信息，请参阅“完全重新生成容器”。

在代码空间内进行重建可确保在将更改提交到仓库之前，更改能够按预期工作。如果某些问题导致了故障，您将进入带有恢复容器的代码空间中，您可以从该容器进行重建以继续调整容器。
After the dev container is rebuilt, and your codespace becomes available again, the postCreateCommand will have been run, restoring the required dependencies, and the "Code Spell Checker" extension will be available for use.

Step 4: Run your application

In the previous section, you used the postCreateCommand to install a set of packages via the dotnet restore command. With the dependencies now installed, you can run the application.

Run the application by pressing F5 or entering dotnet watch run in the Terminal.
When the application starts, click the Ports tab, right-click port 5000 and click Open in Browser.

Step 5: Commit your changes

在对代码空间进行更改（无论是添加新代码还是更改配置）之后，您需要提交更改。将更改提交到仓库可确保从此仓库创建代码空间的其他任何人都具有相同的配置。这也意味着你所做的任何自定义，例如添加 VS Code 扩展，都会显示给所有用户。

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

Next steps

You should now be able to add a custom dev container configuration to your own C# (.NET) project.

Dec	JAN	Mar
	17
2022	2023	2024

Setting up a C# (.NET) project for GitHub Codespaces

本文内容

Introduction

Step 1: Open the project in a codespace

Step 2: Add a dev container configuration

Details of your custom dev container configuration

devcontainer.json

Additional dev container configuration files

Step 3: Modify your devcontainer.json file

Step 4: Run your application

Step 5: Commit your changes

Next steps