You've found one of our experimental articles! Have ideas or feedback for how we can further improve this article? Let us know in the discussion.

Add a dev container to your project

This guide shows you how to add a dev container to define the Codespaces configuration for your C# (.NET) project. For other project languages, click the language button to the right.

Prerequisites

Step 1: Open your project in a codespace

  1. Under the repository name, use the Code drop-down menu, and in the Codespaces tab, click New codespace.

    New codespace button

    If you don’t see this option, Codespaces isn't available for your project. See Access to Codespaces for more information.

When you create a codespace, your project is created on a remote VM 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.

You can customize your codespace by adjusting the amount of vCPUs and RAM, adding dotfiles to personalize your environment, or by modifying the tools and scripts installed.

Codespaces uses a file called devcontainer.json to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "Introduction to dev containers."

Step 2: Add a dev container to your codespace from a template

The default codespaces container comes with the latest .NET version and common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.

To set up your project with a custom container, you will need to use a devcontainer.json file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "Introduction to dev containers".

  1. Access the Command Palette (Shift + Command + P / Ctrl + Shift + P), then start typing "dev container". Select Codespaces: Add Development Container Configuration Files.... Codespaces: Add Development Container Configuration Files... in the command palette

  2. For this example, click C# (.NET). If you need additional features you can select any container that’s specific to C# (.NET) or a combination of tools such as C# (.NET) and MS SQL.

    Select C# (.NET) option from the list

  3. Click the recommended version of .NET. .NET version selection

  4. Accept the default option to add Node.js to your customization. Add Node.js selection

  5. Select any additional features to install and click OK.

  6. Access the command palette (Shift + Command + P/ Ctrl + Shift + P), then start typing "rebuild". Select Codespaces: Rebuild Container. Rebuild container option

Anatomy of your dev container

Adding the C# (.NET) dev container template adds a .devcontainer folder to the root of your project's repository with the following files:

  • devcontainer.json
  • Dockerfile

The newly added devcontainer.json file defines a few properties that are described below.

name - You can name your dev container anything, this is just the default.

build - The build properties.

  • dockerfile - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
  • args
    • VARIANT: This file only contains one build argument, which is the .NET Core version that we want to use.

settings - These are Visual Studio Code settings that you can set.

  • terminal.integrated.shell.linux - While bash is the default here, you could use other terminal shells by modifying this.

extensions - These are extensions included by default.

  • ms-dotnettools.csharp - The Microsoft C# extension provides rich support for developing in C#, including features such as IntelliSense, linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more.

forwardPorts - Any ports listed here will be forwarded automatically.

postCreateCommand - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like dotnet restore, you can do that here.

remoteUser - By default, you’re running as the vscode user, but you can optionally set this to root.

Dockerfile

You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.

Step 3: Modify your devcontainer.json file

With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.

  1. In the Explorer, expand the .devcontainer folder and select the devcontainer.json file from the tree to open it.

    devcontainer.json file in the Explorer

  2. Update your the extensions list in your devcontainer.json file to add a few extensions that are useful when working with your project.

    "extensions": [ "ms-dotnettools.csharp", "streetsidesoftware.code-spell-checker", ],
  3. Uncomment the postCreateCommand to restore dependencies as part of the codespace setup process.

    // Use 'postCreateCommand' to run commands after the container is created. "postCreateCommand": "dotnet restore",
  4. Access the command palette (Shift + Command + P/ Ctrl + Shift + P), then start typing "rebuild". Select Codespaces: Rebuild Container. Rebuild container option Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.

  5. Check your changes were successfully applied by verifying the "Code Spell Checker" extension was installed.

    Extensions list

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 our dependencies now installed, we can run our application.

  1. Run your application by pressing F5 or entering dotnet watch run in your terminal.

  2. When your project starts, you should see a message in the bottom right corner with a prompt to connect to the port your project uses.

    Port forwarding toast

Step 5: Commit your changes

Once you've made changes to your codespace, either new code or configuration changes, you'll want to commit your changes. Committing changes to your repository ensures that anyone else who creates a codespace from this repository has the same configuration. This also means that any customization you do, such as adding Visual Studio Code extensions, will appear for all users.

For information, see "Using source control in your codespace."

bouncing octocatLoading...

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.