From 8b5eb4c85644d11067ad2901176009d3894b8345 Mon Sep 17 00:00:00 2001 From: IEvangelist Date: Wed, 25 Mar 2026 18:44:32 -0500 Subject: [PATCH 1/2] Refresh devcontainer and codespaces docs Update the Dev Containers and GitHub Codespaces guides to use the current Aspire CLI-first setup, point to the dotnet/aspire-devcontainer template, move examples to .NET 10 images, and remove the remaining explicit dotnet new install guidance from those two pages only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/get-started/dev-containers.mdx | 66 ++++++++++--------- .../docs/get-started/github-codespaces.mdx | 58 ++++++++++++---- 2 files changed, 79 insertions(+), 45 deletions(-) diff --git a/src/frontend/src/content/docs/get-started/dev-containers.mdx b/src/frontend/src/content/docs/get-started/dev-containers.mdx index 12b307f20..780d4ac5c 100644 --- a/src/frontend/src/content/docs/get-started/dev-containers.mdx +++ b/src/frontend/src/content/docs/get-started/dev-containers.mdx @@ -15,17 +15,15 @@ import vscodeRunButton from '@assets/get-started/vscode-run-button.png'; import browserCertError from '@assets/get-started/browser-certificate-error.png'; import aspireDashboard from '@assets/get-started/aspire-dashboard-in-devcontainer.png'; -The [Dev Containers Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) 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. +The [Dev Containers Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) provides a way for development teams to work inside a containerized environment where dependencies are defined as part of the repository. Aspire automatically configures forwarded ports in Dev Containers so the dashboard and resource endpoints are easier to open from Visual Studio Code. ## 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](/get-started/github-codespaces/). +Using Dev Containers in Visual Studio Code is similar to using GitHub Codespaces. Although the experiences are similar, there are some differences. For more information on using Aspire with GitHub Codespaces, see [Aspire and GitHub Codespaces](/get-started/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](https://github.com/microsoft/aspire-devcontainer). Consider the following steps: +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 the [Aspire Dev Container template](https://github.com/dotnet/aspire-devcontainer). Consider the following steps: @@ -52,7 +50,7 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon alt="Screenshot showing VS Code prompt to open the 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. + After a few moments, the files become visible and the Dev Container finishes setting up. The template installs the Aspire CLI during setup, so you can create an app immediately without manually installing `Aspire.ProjectTemplates`. ) and create a new Aspire project using the Aspire CLI. - ```bash - aspire new aspire-starter -n HelloAspire - ``` + ```bash title="Aspire CLI — Create an Aspire starter app" + aspire new aspire-starter --name HelloAspire + ``` After a few moments, the project will be created and initial dependencies restored. @@ -88,7 +86,7 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon alt="Screenshot of the Aspire dashboard running successfully in the Dev Container." /> - 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. + Aspire automatically configures forwarded ports so that when you select the endpoints in the Aspire dashboard they're tunneled to processes and nested containers within the Dev Container. 1. Commit changes to the GitHub repository. @@ -98,14 +96,18 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon ## 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: +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 want to use Dev Containers with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository: - .devcontainer - devcontainer.json -The [template repository](https://github.com/microsoft/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire. +The [template repository](https://github.com/dotnet/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire. + +:::note +Install the Aspire CLI during container creation so `aspire new` is ready to use as soon as the container finishes building. +::: ## Dev Container scenarios @@ -115,11 +117,11 @@ The basic Aspire Dev Container template works well for simple scenarios, but you For simple Aspire projects that only use .NET project resources without external containers or complex orchestration, you can use a minimal Dev Container configuration: -```json +```json title="JSON — .devcontainer/devcontainer.json" { "name": "Aspire - Simple", - "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", - "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", "postStartCommand": "dotnet dev-certs https --trust", "customizations": { "vscode": { @@ -135,16 +137,16 @@ This minimal configuration is suitable for Aspire apps that orchestrate only .NE If your Aspire app includes Node.js resources, add the Node.js feature to your Dev Container: -```json +```json title="JSON — .devcontainer/devcontainer.json" { "name": "Aspire with Node.js", - "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", "features": { "ghcr.io/devcontainers/features/node:1": { "version": "lts" } }, - "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", "postStartCommand": "dotnet dev-certs https --trust", "customizations": { "vscode": { @@ -163,10 +165,10 @@ This configuration provides both .NET and Node.js development capabilities withi When your Aspire app orchestrates container resources, you need Docker-in-Docker (DinD) support. Here's a basic configuration: -```json +```json title="JSON — .devcontainer/devcontainer.json" { "name": "Aspire with Containers", - "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": { "version": "latest", @@ -179,7 +181,7 @@ When your Aspire app orchestrates container resources, you need Docker-in-Docker "memory": "16gb", "storage": "32gb" }, - "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", "postStartCommand": "dotnet dev-certs https --trust", "customizations": { "vscode": { @@ -193,10 +195,10 @@ When your Aspire app orchestrates container resources, you need Docker-in-Docker If you encounter networking issues between containers or need IPv6 support, you can add additional network configuration: -```json +```json title="JSON — .devcontainer/devcontainer.json" { "name": "Aspire with Advanced Networking", - "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": { "version": "latest", @@ -217,7 +219,7 @@ If you encounter networking issues between containers or need IPv6 support, you "memory": "32gb", "storage": "64gb" }, - "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", "postStartCommand": "dotnet dev-certs https --trust", "customizations": { "vscode": { @@ -241,17 +243,17 @@ For Aspire apps that integrate with Dapr, you can set up Dapr components in your #### Basic Dapr setup -```json +```json title="JSON — .devcontainer/devcontainer.json" { "name": "Aspire with Dapr", - "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", "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", + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", "postCreateCommand": "dotnet dev-certs https --trust && dapr init", "customizations": { "vscode": { @@ -265,10 +267,10 @@ For Aspire apps that integrate with Dapr, you can set up Dapr components in your For more complex Dapr scenarios that use external backends (Redis, PostgreSQL), you can use Docker Compose: -```json +```json title="JSON — .devcontainer/devcontainer.json" { "name": "Aspire with Dapr and Backends", - "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": { "enableNonRootDocker": true @@ -276,7 +278,7 @@ For more complex Dapr scenarios that use external backends (Redis, PostgreSQL), "ghcr.io/dapr/cli/dapr-cli:0": {} }, "runArgs": ["--sysctl", "net.ipv6.conf.all.disable_ipv6=0"], - "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", "postCreateCommand": [ "dotnet dev-certs https --trust", "docker compose up -d", @@ -307,7 +309,7 @@ When using Dev Containers with Aspire, keep the following considerations in mind **Networking** - IPv6 configuration may be required for container-to-container communication. -- Port forwarding is automatically handled by Aspire 9.1 and later versions. +- Port forwarding is automatically handled by Aspire. - External service connectivity depends on your container runtime configuration. **Performance** @@ -319,5 +321,5 @@ When using Dev Containers with Aspire, keep the following considerations in mind **Security** - Dev Containers run with elevated privileges when using Docker-in-Docker. -- SSL certificate trust is handled automatically in most scenarios. +- The development certificate is created and trusted in the container, but your browser might still show a warning the first time you open a forwarded HTTPS endpoint from the host. - Consider security implications when exposing ports in cloud environments. diff --git a/src/frontend/src/content/docs/get-started/github-codespaces.mdx b/src/frontend/src/content/docs/get-started/github-codespaces.mdx index f4d1df936..62a9f7c4c 100644 --- a/src/frontend/src/content/docs/get-started/github-codespaces.mdx +++ b/src/frontend/src/content/docs/get-started/github-codespaces.mdx @@ -16,20 +16,18 @@ import launchAppHost from '@assets/get-started/codespace-launch-apphost.png'; import debugConsole from '@assets/get-started/codespaces-debug-console.png'; import translatedUrls from '@assets/get-started/codespaces-translated-urls.png'; -[GitHub Codespaces](https://github.com/features/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 Aspire 9.1, comes logic to better support GitHub Codespaces including: +[GitHub Codespaces](https://github.com/features/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. Aspire works well in GitHub Codespaces and includes support for: -- Automatically configure port forwarding with the correct protocol. -- Automatically translate URLs in the Aspire dashboard. - -Before Aspire 9.1 it was still possible to use Aspire within a GitHub Codespace, however more manual configuration was required. +- Automatically configuring port forwarding with the correct protocol. +- Automatically translating URLs in the Aspire dashboard. ## GitHub Codespaces vs. Dev Containers -GitHub Codespaces builds upon Visual Studio Code and the [Dev Containers specification](https://containers.dev/implementors/spec/). In addition to supporting GitHub Codespaces, 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 [Aspire and Visual Studio Code Dev Containers](/get-started/dev-containers/). +GitHub Codespaces builds upon Visual Studio Code and the [Dev Containers specification](https://containers.dev/implementors/spec/). While the experiences are similar, there are some differences. For more information, see [Aspire and Visual Studio Code Dev Containers](/get-started/dev-containers/). ## Quick start using template repository -To configure GitHub Codespaces for 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](https://github.com/microsoft/aspire-devcontainer). Consider the following steps: +To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from the [Aspire Dev Container template](https://github.com/dotnet/aspire-devcontainer). Consider the following steps: @@ -43,7 +41,7 @@ To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.j Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. -1. From the new repository, select on the Code button and select the Codespaces tab and then select **Create codespace on main**. +1. From the new repository, select the **Code** button, open the **Codespaces** tab, and then select **Create codespace on main**. Screenshot showing the terminal prompt ready for use in the codespace. - At this point, the Aspire templates have been installed and the ASP.NET Core developer certificate has been added and accepted. + At this point, the Aspire CLI has been installed and the ASP.NET Core development certificate has been created and trusted inside the Codespace. You can use `aspire new` right away without manually installing `Aspire.ProjectTemplates`. 1. Create a new Aspire project using the starter template. - ```bash - dotnet new aspire-starter --name HelloAspire + ```bash title="Aspire CLI — Create an Aspire starter app" + aspire 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. @@ -130,14 +128,48 @@ To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.j ## Manually configuring devcontainer.json -The preceding walkthrough demonstrates the streamlined process of creating a GitHub Codespace using the Aspire Devcontainer template. If you already have an existing repository and wish to utilize Devcontainer functionality with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository: +The preceding walkthrough demonstrates the streamlined process of creating a GitHub Codespace using the Aspire Dev Container template. If you already have an existing repository and want to use Codespaces with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository: - .devcontainer - devcontainer.json -The [template repository](https://github.com/microsoft/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire. +The [template repository](https://github.com/dotnet/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire. + +The following `devcontainer.json` matches the current template repository and works well for most Aspire solutions in Codespaces: + +```json title="JSON — .devcontainer/devcontainer.json" +{ + "name": "Aspire", + "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": {}, + "ghcr.io/devcontainers/features/powershell:1": {}, + "ghcr.io/devcontainers/features/node:1": {}, + "ghcr.io/devcontainers/features/python:1": {}, + "ghcr.io/devcontainers-extra/features/uv:1": {} + }, + "hostRequirements": { + "cpus": 8, + "memory": "32gb", + "storage": "64gb" + }, + "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", + "postStartCommand": "dotnet dev-certs https --trust", + "customizations": { + "vscode": { + "extensions": [ + "ms-dotnettools.csdevkit", + "GitHub.copilot-chat", + "GitHub.copilot" + ] + } + } +} +``` + +This configuration installs the Aspire CLI during Codespace creation, so `aspire new` is ready to use as soon as the Codespace finishes building. ## Speed up Codespace creation From 50783aa9eed358b3e2d0402a7cd19e4576b273b1 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 25 Mar 2026 19:20:40 -0500 Subject: [PATCH 2/2] Update src/frontend/src/content/docs/get-started/dev-containers.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/frontend/src/content/docs/get-started/dev-containers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/get-started/dev-containers.mdx b/src/frontend/src/content/docs/get-started/dev-containers.mdx index 780d4ac5c..0ccce43d8 100644 --- a/src/frontend/src/content/docs/get-started/dev-containers.mdx +++ b/src/frontend/src/content/docs/get-started/dev-containers.mdx @@ -57,7 +57,7 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon alt="Screenshot showing the dev container build completed notification in VS Code." /> -1. Open a new terminal window in Visual Studio Code () and create a new Aspire project using the Aspire CLI. +1. Open a new terminal window in Visual Studio Code () and create a new Aspire project using the Aspire CLI. ```bash title="Aspire CLI — Create an Aspire starter app" aspire new aspire-starter --name HelloAspire