| title | description | ms.date |
|---|---|---|
Dev Containers in Visual Studio Code | Learn how to use .NET Aspire with Dev Containers in Visual Studio Code. | 02/25/2025 |
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.
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.
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:
Create a new repository using our template.
:::image source="media/new-repository-from-template.png" lightbox="media/new-repository-from-template.png" alt-text="Create new repository.":::
Once you provide the details and select Create repository, the repository is created and shown in GitHub.
Clone the repository to your local developer workstation using the following command:
git clone https://github.com/<org>/<username>/<repository>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.
:::image source="media/reopen-in-container.png" lightbox="media/reopen-in-container.png" alt-text="Prompt to open repository inside a container.":::
After a few moments, the list of files become visible and the local build of the dev container will be completed.
:::image source="media/devcontainer-build-completed.png" lightbox="media/devcontainer-build-completed.png" alt-text="Dev Container build completed.":::
Open a new terminal window in Visual Studio Code (Ctrl+Shift+`) and create a new .NET Aspire project using the
dotnetcommand-line.dotnet new aspire-starter -n HelloAspireAfter a few moments, the project will be created and initial dependencies restored.
Open the ProjectName.AppHost/Program.cs file in the editor and select the run button on the top right corner of the editor window.
:::image source="media/vscode-run-button.png" lightbox="media/vscode-run-button.png" alt-text="Run button in editor.":::
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.
:::image source="media/browser-certificate-error.png" lightbox="media/browser-certificate-error.png" alt-text="Browser 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.
:::image source="media/aspire-dashboard-in-devcontainer.png" lightbox="media/aspire-dashboard-in-devcontainer.png" alt-text=".NET Aspire dashboard running in Dev Container.":::
.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.
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.
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:
:::code language="json" source="~/aspire-devcontainer/.devcontainer/devcontainer.json":::
