.NET Aspire templates

Article
11/12/2024

There are a number of .NET Aspire project templates available to you. You can use these templates to create full .NET Aspire solutions, or add individual projects to existing .NET Aspire solutions.

The .NET Aspire templates are available in the 📦 Aspire.ProjectTemplates NuGet package.

Install the .NET Aspire templates

To install the .NET 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:

Open Visual Studio.
Go to Tools > NuGet Package Manager > Package Manager Console.
Run the following command to install the templates:

dotnet new install Aspire.ProjectTemplates

For Visual Studio 17.12 or later, the .NET 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.0.0

Tip

If you already have the .NET Aspire workload installed, you need to pass the --force flag to overwrite the existing templates. Feel free to uninstall the .NET Aspire workload.

List the .NET Aspire templates

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

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:

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

To verify that the .NET 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
---------------------------------  ----------------------  --------  -------------------------------------------------------
.NET Aspire App Host               aspire-apphost          [C#]      Common/.NET Aspire/Cloud
.NET Aspire Empty App              aspire                  [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service
.NET Aspire Service Defaults       aspire-servicedefaults  [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service
.NET Aspire Starter App            aspire-starter          [C#]      Common/.NET Aspire/Blazor/Web/Web API/API/Service/Cloud
.NET Aspire Test Project (MSTest)  aspire-mstest           [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test
.NET Aspire Test Project (NUnit)   aspire-nunit            [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test
.NET Aspire Test Project (xUnit)   aspire-xunit            [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test

Available templates

The .NET Aspire templates allow you to create new apps pre-configured with the .NET Aspire solutions structure and default settings. These projects also provide a unified debugging experience across the different resources of your app.

.NET Aspire templates are available in two categories: solution templates and project templates. Solution templates create a new .NET Aspire solution with multiple projects, while project templates create individual projects that can be added to an existing .NET Aspire solution.

Solution templates

The following .NET Aspire solution templates are available, assume the solution is named AspireSample:

.NET Aspire Empty App: A minimal .NET Aspire project that includes the following:
- AspireSample.AppHost: An orchestrator project designed to connect and configure the different projects and services of your app.
- AspireSample.ServiceDefaults: A .NET Aspire shared project to manage configurations that are reused across the projects in your solution related to resilience, service discovery, and telemetry.

.NET Aspire Starter App: In addition to the .AppHost and .ServiceDefaults projects, the .NET Aspire Starter App also includes the following:
- AspireSample.ApiService: An ASP.NET Core Minimal API project is used to provide data to the frontend. This project depends on the shared AspireSample.ServiceDefaults project.
- AspireSample.Web: An ASP.NET Core Blazor App project with default .NET Aspire service configurations, this project depends on the AspireSample.ServiceDefaults project.
- AspireSample.Test: Either an MSTest, NUnit, or xUnit test project with project references to the AspireSample.AppHost and an example WebTests.cs file demonstrating an integration test.

Project templates

The following .NET Aspire project templates are available:

.NET Aspire App Host: A standalone .AppHost project that can be used to orchestrate and manage the different projects and services of your app.

.NET Aspire Test projects: These project templates are used to create test projects for your .NET Aspire app, and they're intended to represent functional and integration tests. The test projects include the following templates:
- MSTest: A project that contains MSTest integration of a .NET Aspire AppHost project.
- NUnit: A project that contains NUnit integration of a .NET Aspire AppHost project.
- xUnit: A project that contains xUnit.net integration of a .NET Aspire AppHost project.
For more information on the test templates, see Testing in .NET Aspire.

.NET Aspire Service Defaults: A standalone .ServiceDefaults project that can be used to manage configurations that are reused across the projects in your solution related to resilience, service discovery, and telemetry.

Important

The service defaults project template takes a FrameworkReference dependency on Microsoft.AspNetCore.App. This may not be ideal for some project types. For more information, see .NET Aspire service defaults.

Create solutions and projects using templates

To create a .NET Aspire solution or project, use Visual Studio, Visual Studio Code, or the .NET CLI, and base it on the available templates. Explore additional .NET Aspire templates in the .NET Aspire samples repository.

To create a .NET Aspire project using Visual Studio, search for Aspire in the Visual Studio new project window and select your desired template.

Follow the prompts to configure your project or solution from the template, and then select Create.

To create a .NET Aspire project using Visual Studio Code, search for Aspire in the Visual Studio Code new project window and select your desired template.

Select the desired location, enter a name, and select Create.

To create a .NET Aspire solution or project using the .NET CLI, use the dotnet new command and specify which template you would like to create. Consider the following examples:

To create a basic .NET Aspire app host project targeting the latest .NET version:

dotnet new aspire-apphost

To create a .NET Aspire starter app, which is a full solution with a sample UI and backing API included:

dotnet new aspire-starter

Tip

.NET Aspire templates default to using the latest .NET version, even when using an earlier version of the .NET CLI. To manually specify the .NET version, use the --framework <tfm> option, e.g. to create a basic .NET Aspire app host project targeting .NET 8:

dotnet new aspire-apphost --framework net8.0

Share via