Edit

Share via

Aspire setup and tooling

Aspire includes tooling to help you create and configure cloud-native apps. The tooling includes useful starter project templates and other features to streamline getting started with Aspire for Visual Studio, Visual Studio Code, and CLI workflows. In the sections ahead, you learn how to work with Aspire tooling and explore the following tasks:

  • Install Aspire and its dependencies
  • Create starter project templates using Visual Studio, Visual Studio Code, or the .NET CLI
  • Install Aspire integrations
  • Work with the Aspire dashboard

Install Aspire prerequisites

To work with Aspire, you need the following installed locally:

Tip

Alternatively, you can develop Aspire solutions using GitHub Codespaces or Dev Containers.

Visual Studio 2022 17.9 or higher includes the latest Aspire SDK by default when you install the Web & Cloud workload.

Aspire templates

Aspire provides a set of solution and project templates. These templates are available in your favorite .NET developer integrated environment. You can use these templates to create full Aspire solutions, or add individual projects to existing Aspire solutions.

Install the Aspire templates

To install the Aspire templates in Visual Studio, you need to manually install them unless you're using Visual Studio 17.12 or later. For Visual Studio 17.9 to 17.11, follow these steps:

  1. Open Visual Studio.
  2. Go to Tools > NuGet Package Manager > Package Manager Console.
  3. Run the following command to install the templates:
dotnet new install Aspire.ProjectTemplates

For Visual Studio 17.12 or later, the Aspire templates are installed automatically.

To install these templates, use the dotnet new install command, passing in the Aspire.ProjectTemplates NuGet identifier.

dotnet new install Aspire.ProjectTemplates

To install a specific version, append the version number to the package name:

dotnet new install Aspire.ProjectTemplates::9.4.0

List the Aspire templates

The Aspire templates are installed automatically when you install Visual Studio 17.9 or later. To see what Aspire templates are available, select File > New > Project in Visual Studio, and search for "Aspire" in the search bar (Alt+S). You see a list of available Aspire project templates:

Visual Studio: Create new project and search for 'Aspire'.

To view the available templates in Visual Studio Code with the C# DevKit installed, select the Create .NET Project button when no folder is opened in the Explorer view:

Visual Studio Code: Create .NET Project button.

Then, search for "Aspire" in the search bar to see the available Aspire project templates:

Visual Studio Code: Create new project and search for 'Aspire'.

To verify that the Aspire templates are installed, use the dotnet new list command, passing in the aspire template name:

dotnet new list aspire

Your console output should look like the following:

dotnet new list aspire
These templates matched your input: 'aspire'

Template Name                      Short Name              Language  Tags
---------------------------------  ----------------------  --------  -------------------------------------------------------
Aspire AppHost               aspire-apphost          [C#]      Common/Aspire/Cloud
Aspire Empty App              aspire                  [C#]      Common/Aspire/Cloud/Web/Web API/API/Service
Aspire Service Defaults       aspire-servicedefaults  [C#]      Common/Aspire/Cloud/Web/Web API/API/Service
Aspire Starter App            aspire-starter          [C#]      Common/Aspire/Blazor/Web/Web API/API/Service/Cloud
Aspire Test Project (MSTest)  aspire-mstest           [C#]      Common/Aspire/Cloud/Web/Web API/API/Service/Test
Aspire Test Project (NUnit)   aspire-nunit            [C#]      Common/Aspire/Cloud/Web/Web API/API/Service/Test
Aspire Test Project (xUnit)   aspire-xunit            [C#]      Common/Aspire/Cloud/Web/Web API/API/Service/Test

For more information, see Aspire templates.

Container runtime

Aspire can run containers using several OCI-compatible runtimes, including Docker Desktop and Podman. While some users have reported success using Rancher Desktop—particularly when configured to use the Docker CLI—this isn't an officially supported or regularly tested scenario. It might be possible to use Rancher Desktop with the default installation, but it's not an officially supported or validated approach. If you encounter issues with Rancher Desktop, please let us know, but be aware that fixes might not be prioritized.

  • Docker Desktop is the most popular container runtime among Aspire developers, offering a familiar and widely supported environment for building and running containers.
  • Podman is an open-source, daemonless alternative to Docker. It supports building and running Open Container Initiative (OCI) containers, making it a flexible choice for developers who prefer a lightweight solution.

If your host environment has a Docker and Podman installed, Aspire defaults to using Docker. You can instruct Aspire to use Podman instead, by setting the ASPIRE_CONTAINER_RUNTIME environment variable to podman:

export ASPIRE_CONTAINER_RUNTIME=podman

For more information, see Install Podman on Linux.

WSL (Windows Subsystem for Linux) considerations

When using Podman with WSL, ensure that the podman executable is available in your PATH and not just defined as a shell alias. Aspire resolves container runtimes by searching for the executable in the system PATH, and shell aliases aren't recognized during this process.

Common issues and solutions:

  • Podman installed in a separate WSL distribution: If Podman is installed in a different WSL distribution than your Aspire application, the podman command might not be available in your current distribution's PATH.

    Solution: Install Podman directly in the WSL distribution where you're running your Aspire application, or create a symbolic link to the Podman executable in a directory that's in your PATH (such as /usr/local/bin).

  • Using shell aliases: If you have a shell alias like alias podman='podman-remote-static-linux_amd64' in your ~/.bash_aliases or similar file, Aspire won't be able to find the container runtime.

    Solution: Instead of using an alias, create a symbolic link or add the directory containing the Podman executable to your PATH:

    # Option 1: Create a symbolic link
sudo ln -s /path/to/podman-remote-static-linux_amd64 /usr/local/bin/podman

# Option 2: Add to PATH in your shell profile
echo 'export PATH="/path/to/podman/directory:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify your setup: You can verify that Podman is correctly configured by running:

which podman
podman --version

Both commands should succeed and return valid results before running your Aspire application.

Tip

If you encounter issues with Podman in WSL environments, see Container runtime 'podman' could not be found in WSL for specific troubleshooting guidance.

Aspire dashboard

Aspire templates that expose the AppHost project also include a useful developer dashboard that's used to monitor and inspect various aspects of your app, such as logs, traces, and environment configurations. This dashboard is designed to improve the local development experience and provides an overview of the overall state and structure of your app.

The Aspire dashboard is only visible while the app is running and starts automatically when you start the *.AppHost project. Visual Studio and Visual Studio Code launch both your app and the Aspire dashboard for you automatically in your browser. If you start the app using the .NET CLI, copy and paste the dashboard URL from the output into your browser, or hold Ctrl and select the link (if your terminal supports hyperlinks).

A screenshot showing how to launch the dashboard using the CLI.

The left navigation provides links to the different parts of the dashboard, each of which you explore in the following sections.

A screenshot of the Aspire dashboard Projects page.

The Aspire dashboard is also available in a standalone mode. For more information, see Standalone Aspire dashboard.

Visual Studio tooling

Visual Studio provides extra features for working with Aspire integrations and the AppHost orchestrator project. Not all of these features are currently available in Visual Studio Code or through the CLI.

Add an integration package

You add Aspire integrations to your app like any other NuGet package using Visual Studio. However, Visual Studio also provides UI options to add Aspire integrations directly.

  1. In Visual Studio, right select on the project you want to add an Aspire integration to and select Add > Aspire package....

    The Visual Studio context menu displaying the Add Aspire Component option.

  2. The package manager opens with search results preconfigured (populating filter criteria) for Aspire integrations, allowing you to easily browse and select the desired integration.

    The Visual Studio context menu displaying the Add Aspire integration options.

For more information on Aspire integrations, see Aspire integrations overview.

Add hosting packages

Aspire hosting packages are used to configure various resources and dependencies an app might depend on or consume. Hosting packages are differentiated from other integration packages in that they're added to the *.AppHost project. To add a hosting package to your app, follow these steps:

  1. In Visual Studio, right select on the *.AppHost project and select Add > Aspire package....

    The Visual Studio context menu displaying the Add Aspire Hosting Resource option.

  2. The package manager opens with search results preconfigured (populating filter criteria) for Aspire hosting packages, allowing you to easily browse and select the desired package.

    The Visual Studio context menu displaying the Add Aspire resource options.

Add orchestration projects

You can add Aspire orchestration projects to an existing app using the following steps:

  1. In Visual Studio, right select on an existing project and select Add > Aspire Orchestrator Support...

    The Visual Studio context menu displaying the Add Aspire Orchestrator Support option.

  2. A dialog window opens with a summary of the *.AppHost and *.ServiceDefaults projects that are added to your solution.

    A screenshot showing the Visual Studio add Aspire orchestration summary.

  3. Select OK and the following changes are applied:

    • The *.AppHost and *.ServiceDefaults orchestration projects are added to your solution.
    • A call to builder.AddServiceDefaults will be added to the Program.cs file of your original project.
    • A reference to your original project will be added to the AppHost.cs file of the *.AppHost project.

For more information on Aspire orchestration, see Aspire orchestration overview.

Enlist in orchestration

Visual Studio provides the option to Enlist in Aspire orchestration during the new project workflow. Select this option to have Visual Studio create *.AppHost and *.ServiceDefaults projects alongside your selected project template.

A screenshot showing how to enlist in Aspire orchestration.

Create test project

When you're using Visual Studio, and you select the Aspire Start Application template, you have the option to include a test project. This test project is an xUnit project that includes a sample test that you can use as a starting point for your tests.

A screenshot of Visual Studio displaying the option to create a test project.

For more information, see Write your first Aspire test.

Visual Studio Code tooling

You can use Visual Studio Code, with the C# Dev Kit extension, to create and develop Aspire projects. To create a new Aspire project in Visual Studio Code, select the Create .NET Project button in the Explorer view, then select one of the Aspire templates:

A screenshot showing how to create a new Aspire project in Visual Studio Code.

Once you create a new Aspire project, you run and debug the app, stepping through breakpoints, and inspecting variables using the Visual Studio Code debugger:

A screenshot showing how to debug an Aspire project in Visual Studio Code.

Aspire CLI

The Aspire CLI (aspire command) is a cross-platform tool that provides command-line functionality to create, manage, run, and publish polyglot Aspire projects. Use the Aspire CLI to streamline development workflows and coordinate services for distributed applications.

For more information, see Aspire CLI Overview and Install Aspire CLI.

See also