.NET Aspire and Visual Studio Code Dev Containers

The Dev Containers Visual Studio Code extension provides a way for development teams to develop within a containerized environment where all dependencies are preconfigured. With .NET Aspire 9.1, there's added logic to better support working with .NET Aspire within a Dev Container environment by automatically configuring port forwarding.

Before .NET Aspire 9.1, it possible to use .NET Aspire within a Dev Container, however more manual configuration was required.

Dev Containers vs. GitHub Codespaces

Using Dev Containers in Visual Studio Code is similar to using GitHub Codespaces. With the release of .NET Aspire 9.1, support for both Dev Containers in Visual Studio Code and GitHub Codespaces was enhanced. Although the experiences are similar, there are some differences. For more information on using .NET Aspire with GitHub Codespaces, see .NET Aspire and GitHub Codespaces.

Quick start using template repository

To configure Dev Containers in Visual Studio Code, use the _.devcontainer/devcontainer.json file in your repository. The simplest way to get started is by creating a new repository from our template repository. Consider the following steps:

1. Create a new repository using our template.

   

   Once you provide the details and select Create repository, the repository is created and shown in GitHub.

2. Clone the repository to your local developer workstation using the following command:

   git clone https://github.com/<org>/<username>/<repository>
   

3. Open the repository in Visual Studio Code. After a few moments Visual Studio Code detects the .devcontainer/devcontainer.json file and prompt to open the repository inside a container. Select whichever option is most appropriate for your workflow.

   

   After a few moments, the list of files become visible and the local build of the dev container will be completed.

   

4. Open a new terminal window in Visual Studio Code (Ctrl+Shift+`) and create a new .NET Aspire project using the dotnet command-line.

   dotnet new aspire-starter -n HelloAspire
   

   After a few moments, the project will be created and initial dependencies restored.

5. Open the ProjectName.AppHost/Program.cs file in the editor and select the run button on the top right corner of the editor window.

   

   Visual Studio Code builds and starts the .NET Aspire app host and automatically opens the .NET Aspire Dashboard. Because the endpoints hosted in the container are using a self-signed certificate the first time, you access an endpoint for a specific Dev Container you're presented with a certificate error.

   

   The certificate error is expected. Once you've confirmed that the URL being requested corresponds to the dashboard in the Dev Container you can ignore this warning.

   

   .NET Aspire automatically configures forwarded ports so that when you select on the endpoints in the .NET Aspire dashboard they're tunneled to processes and nested containers within the Dev Container.

6. Commit changes to the GitHub repository

   After successfully creating the .NET Aspire project and verifying that it launches and you can access the dashboard, it's a good idea to commit the changes to the repository.

Manually configuring devcontainer.json

The preceding walkthrough demonstrates the streamlined process of creating a Dev Container using the .NET Aspire Dev Container template. If you already have an existing repository and wish to utilize Dev Container functionality with .NET Aspire, add a devcontainer.json file to the .devcontainer folder within your repository:

└───📂 .devcontainer
     └─── devcontainer.json

The template repository contains a copy of the devcontainer.json file that you can use as a starting point, which should be sufficient for .NET Aspire. The following JSON represents the latest version of the .devcontainer/devcontainer.json file from the template:

// 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": ".NET Aspire",
    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
    "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
        "ghcr.io/devcontainers/features/powershell:1": {},
    },

    "hostRequirements": {
        "cpus": 8,
        "memory": "32gb",
        "storage": "64gb"
    },

    // 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",
    "onCreateCommand": "dotnet new install Aspire.ProjectTemplates::9.1.0 --force",
    "postStartCommand": "dotnet dev-certs https --trust",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-dotnettools.csdevkit",
                "GitHub.copilot-chat",
                "GitHub.copilot"
            ]
        }
    }
    // Configure tool-specific properties.
    // "customizations": {},

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