.NET Aspire and GitHub Codespaces

Article
02/25/2025

GitHub Codespaces offers a cloud-hosted development environment based on Visual Studio Code. It can be accessed directly from a web browser or through Visual Studio Code locally, where Visual Studio Code acts as a client connecting to a cloud-hosted backend. With .NET Aspire 9.1, comes logic to better support GitHub Codespaces including:

Automatically configure port forwarding with the correct protocol.
Automatically translate URLs in the .NET Aspire dashboard.

Before .NET Aspire 9.1 it was still possible to use .NET Aspire within a GitHub Codespace, however more manual configuration was required.

GitHub Codespaces vs. Dev Containers

GitHub Codespaces builds upon Visual Studio Code and the Dev Containers specification. In addition to supporting GitHub Codespaces, .NET Aspire 9.1 enhances support for using Visual Studio Code and locally hosted Dev Containers. While the experiences are similar, there are some differences. For more information, see .NET Aspire and Visual Studio Code Dev Containers.

Quick start using template repository

To configure GitHub Codespaces for .NET Aspire, 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.

Once you provide the details and select Create repository, the repository is created and shown in GitHub.
From the new repository, select on the Code button and select the Codespaces tab and then select Create codespace on main.

After you select Create codespace on main, you navigate to a web-based version of Visual Studio Code. Before you use the Codespace, the containerized development environment needs to be prepared. This process happens automatically on the server and you can review progress by selecting the Building codespace link on the notification in the bottom right of the browser window.

When the container image has finished being built the Terminal prompt appears which signals that the environment is ready to be interacted with.

At this point, the .NET Aspire templates have been installed and the ASP.NET Core developer certificate has been added and accepted.
Create a new .NET Aspire project using the starter template.
```
dotnet new aspire-starter --name HelloAspire
```
This results in many files and folders being created in the repository, which are visible in the Explorer panel on the left side of the window.
Launch the app host via the HelloAspire.AppHost/Program.cs file, by selecting the Run project button near the top-right corner of the Tab bar.

After a few moments the Debug Console panel is displayed, and it includes a link to the .NET Aspire dashboard exposed on a GitHub Codespaces endpoint with the authentication token.
Open the .NET Aspire dashboard by selecting the dashboard URL in the Debug Console. This opens the .NET Aspire dashboard in a separate tab within your browser.

You notice on the dashboard that all HTTP/HTTPS endpoints defined on resources have had their typical localhost address translated to a unique fully qualified subdomain on the app.github.dev domain.

Traffic to each of these endpoints is automatically forwarded to the underlying process or container running within the Codespace. This includes development time tools such as PgAdmin and Redis Insight.

Note

In addition to the authentication token embedded within the URL of the dashboard link of the Debug Console, endpoints also require authentication via your GitHub identity to avoid port forwarded endpoints being accessible to everyone. For more information on port forwarding in GitHub Codespaces, see Forwarding ports in your codespace.
Commit changes to the GitHub repository.

GitHub Codespaces doesn't automatically commit your changes to the branch you're working on in GitHub. You have to use the Source Control panel to stage and commit the changes and push them back to the repository.

Working in a GitHub Codespace is similar to working with Visual Studio Code on your own machine. You can checkout different branches and push changes just like you normally would. In addition, you can easily spin up multiple Codespaces simultaneously if you want to quickly work on another branch without disrupting your existing debug session. For more information, see Developing in a codespace.
Clean up your Codespace.

GitHub Codespaces are temporary development environments and while you might use one for an extended period of time, they should be considered a disposable resource that you recreate as needed (with all of the customization/setup contained within the devcontainer.json and associated configuration files).

To delete your GitHub Codespace, visit the GitHub Codespaces page. This shows you a list of all of your Codespaces. From here you can perform management operations on each Codespace, including deleting them.

GitHub charges for the use of Codespaces. For more information, see Managing the cost of GitHub Codespaces in your organization.

Note

.NET Aspire supports the use of Dev Containers in Visual Studio Code independent of GitHub Codespaces. For more information on how to use Dev Containers locally, see .NET Aspire and Dev Containers in Visual Studio Code.

Manually configuring devcontainer.json

The preceding walkthrough demonstrates the streamlined process of creating a GitHub Codespace using the .NET Aspire Devcontainer template. If you already have an existing repository and wish to utilize Devcontainer 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"
}

Speed up Codespace creation

Creating a GitHub Codespace can take some time as it prepares the underlying container image. To expedite this process, you can utilize prebuilds to significantly reduce the creation time to approximately 30-60 seconds (exact timing might vary). For more information on GitHub Codespaces prebuilds, see GitHub Codespaces prebuilds.

Share via

.NET Aspire and GitHub Codespaces

GitHub Codespaces vs. Dev Containers

Quick start using template repository

Manually configuring devcontainer.json

Speed up Codespace creation

Additional resources