Dev Containers in Visual Studio Code

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 Aspire 9.1, there’s added logic to better support working with Aspire within a Dev Container environment by automatically configuring port forwarding.

Before Aspire 9.1, it was possible to use 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 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 Aspire with GitHub Codespaces, see 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 prompts 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 ( Command + Shift + Backslash CmdShift\ Control + Shift + Backslash CtrlShift\ Control + Shift + Backslash CtrlShift\ ) and create a new Aspire project using the Aspire CLI.

   aspire new aspire-starter -n HelloAspire

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

5. Open the HelloAspire.AppHost/AppHost.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 Aspire AppHost and automatically opens the 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.

   

   Aspire automatically configures forwarded ports so that when you select on the endpoints in the 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 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 Aspire Dev Container template. If you already have an existing repository and wish to utilize Dev Container functionality with Aspire, add a devcontainer.json file to the .devcontainer folder within your repository:

• Ordner.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 Aspire.

Dev Container scenarios

The basic Aspire Dev Container template works well for simple scenarios, but you might need additional configuration depending on your specific requirements. The following sections provide examples for various common scenarios.

Stateless .NET apps only

For simple Aspire projects that only use .NET project resources without external containers or complex orchestration, you can use a minimal Dev Container configuration:

{
  "name": "Aspire - Simple",
  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
  "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
  "postStartCommand": "dotnet dev-certs https --trust",
  "customizations": {
    "vscode": {
      "extensions": ["ms-dotnettools.csdevkit"]
    }
  }
}

This minimal configuration is suitable for Aspire apps that orchestrate only .NET services without external dependencies.

Adding Node.js resources

If your Aspire app includes Node.js resources, add the Node.js feature to your Dev Container:

{
  "name": "Aspire with Node.js",
  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "lts"
    }
  },
  "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
  "postStartCommand": "dotnet dev-certs https --trust",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-dotnettools.csdevkit",
        "ms-vscode.vscode-typescript-next"
      ]
    }
  }
}

This configuration provides both .NET and Node.js development capabilities within the same container environment.

Container orchestration with Docker-in-Docker

When your Aspire app orchestrates container resources, you need Docker-in-Docker (DinD) support. Here’s a basic configuration:

{
  "name": "Aspire with Containers",
  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "version": "latest",
      "enableNonRootDocker": true,
      "moby": true
    }
  },
  "hostRequirements": {
    "cpus": 4,
    "memory": "16gb",
    "storage": "32gb"
  },
  "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
  "postStartCommand": "dotnet dev-certs https --trust",
  "customizations": {
    "vscode": {
      "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-docker"]
    }
  }
}

Advanced container networking

If you encounter networking issues between containers or need IPv6 support, you can add additional network configuration:

{
  "name": "Aspire with Advanced Networking",
  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "version": "latest",
      "enableNonRootDocker": true,
      "moby": true
    }
  },
  "runArgs": [
    "--sysctl",
    "net.ipv6.conf.all.disable_ipv6=0",
    "--sysctl",
    "net.ipv6.conf.default.forwarding=1",
    "--sysctl",
    "net.ipv6.conf.all.forwarding=1"
  ],
  "hostRequirements": {
    "cpus": 8,
    "memory": "32gb",
    "storage": "64gb"
  },
  "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
  "postStartCommand": "dotnet dev-certs https --trust",
  "customizations": {
    "vscode": {
      "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-docker"]
    }
  }
}

Docker-in-Docker considerations

• Docker-in-Docker requires higher resource allocation including increased CPU, memory, and storage.
• The advanced networking configuration above includes IPv6 forwarding settings that may be needed for complex container-to-container communication scenarios.
• This configuration works with Docker Desktop but may have limitations with Rancher Desktop.
• Network connectivity between containers might require additional configuration depending on your specific use case.

Dapr integration examples

For Aspire apps that integrate with Dapr, you can set up Dapr components in your Dev Container. For more information, see Aspire Dapr integration.

Basic Dapr setup

{
  "name": "Aspire with Dapr",
  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "enableNonRootDocker": true
    },
    "ghcr.io/dapr/cli/dapr-cli:0": {}
  },
  "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
  "postCreateCommand": "dotnet dev-certs https --trust && dapr init",
  "customizations": {
    "vscode": {
      "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-dapr"]
    }
  }
}

Dapr with external backends

For more complex Dapr scenarios that use external backends (Redis, PostgreSQL), you can use Docker Compose:

{
  "name": "Aspire with Dapr and Backends",
  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "enableNonRootDocker": true
    },
    "ghcr.io/dapr/cli/dapr-cli:0": {}
  },
  "runArgs": ["--sysctl", "net.ipv6.conf.all.disable_ipv6=0"],
  "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
  "postCreateCommand": [
    "dotnet dev-certs https --trust",
    "docker compose up -d",
    "dapr init"
  ],
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-dotnettools.csdevkit",
        "ms-azuretools.vscode-dapr",
        "ms-azuretools.vscode-docker"
      ]
    }
  }
}

Common considerations

When using Dev Containers with Aspire, keep the following considerations in mind:

Resource requirements

• Basic .NET apps: Standard Dev Container resources are sufficient for simple scenarios.
• Container orchestration: A minimum of 8 CPUs, 32GB memory, and 64GB storage is recommended.
• Complex scenarios with Dapr/Kubernetes: Higher resource allocation is recommended for optimal performance.

Networking

• IPv6 configuration may be required for container-to-container communication.
• Port forwarding is automatically handled by Aspire 9.1 and later versions.
• External service connectivity depends on your container runtime configuration.

Performance

• Docker-in-Docker scenarios incur performance overhead compared to native Docker.
• Consider using Docker outside of Docker (DooD) for production workflows.
• Local development and deployment scenarios may require different configurations.

Security

• Dev Containers run with elevated privileges when using Docker-in-Docker.
• SSL certificate trust is handled automatically in most scenarios.
• Consider security implications when exposing ports in cloud environments.