Learn how to create a new .NET Aspire project

  • 5 minutes

Cloud-native development can require developers to connect together different micro-services like databases, messaging queues, and caches. .NET Aspire simplifies this process by providing a set of templates you can use to create and manage the connections between these services.

In this unit, learn how to create a new .NET Aspire project and understand the differences between the two starter project templates. Then explore the structure of the solution generated.

.NET Aspire prerequisites

Before you can create a new .NET Aspire project, there are some prerequisites you need to install locally:

In the next exercise, you'll go through the steps to install these prerequisites.

Choose the best .NET Aspire template for your project

There are two .NET Aspire starter templates currently available:

  • .NET Aspire Application: This template is a good starting point for new projects. It only includes the AspireSample.AppHost and AspireSample.ServiceDefaults projects. This template is useful when you want to start from scratch and add your own components and services.

  • .NET Aspire Starter Application: This template includes the AspireSample.AppHost and AspireSample.ServiceDefaults projects, but also includes an example Blazor App AspireSample.Web and an API that provides data to it AspireSample.ApiService. These projects are preconfigured with service discovery and other basic examples of common .NET Aspire functionality.

Both Aspire templates provide a dashboard to monitor the health of the services and the traffic between them. The dashboard helps improve your local development experience — as at a glance it gives you an overview of the state and structure of your app.

There are also three project templates available:

  • .NET Aspire App Host: A template that only contains an app host (orchestrator) project.
  • .NET Aspire Service Defaults: A template that only contains the service defaults project.
  • .NET Aspire Test Project: A template that only contains unit tests for the app host project.

Creating a new .NET Aspire project by using a .NET Aspire template

You can use the Visual Studio launch dialog to create a new .NET Aspire project, or File > New > Project. You can also use .NET CLI commands. To create a solution with the .NET Aspire Application template, you would use this command:

dotnet new aspire

Or to use the .NET Aspire Starter Application template, you would use this command:

dotnet new aspire-starter

A benefit of using Visual Studio is you choose your configuration options through dialogs. The .NET CLI commands are useful when you want to create a new .NET Aspire project with default settings, but you can alter the defaults with optional flags. In the next exercise, you'll see how to create a new .NET Aspire project using both methods.

Explore the structure of solutions generated by the .NET Aspire templates

The .NET Aspire templates generate a solution with a specific structure. This structure is a simplified diagram for the starter application, without the caching or testing options enabled:

────📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── ...
     │    │    ├───📂 Pages
     │    │    │    ├─── ...
     │    │    ├─── ...
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───...
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

Both templates add AppHost and ServiceDefaults projects. These projects are the core of an application built with .NET Aspire. The AppHost project is the entry point and is responsible for acting as the orchestrator.

The ServiceDefaults project contains the default configuration for the application. These configurations are reused across all the projects in your solution.

The above solution also includes Web and ApiService projects. The Web project is a Blazor WebAssembly app that has a counter and calls the ApiService to get forecast data. The ApiService is a simple API that returns forecast data.

Walk through the code structure

The AspireSample.AppHost project has the following code in Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireStarterSample_ApiService>("apiservice");

builder.AddProject<Projects.AspireStarterSample_Web>("webfrontend")
    .WithReference(cache)
    .WithReference(apiService);

builder.Build().Run();

Walking through the above code, line by line:

  • Create a builder variable that's a IDistributedApplicationBuilder.

  • Create a cache variable that's a IResourceBuilder<RedisResource>.

  • Call AddProject with a generic-type parameter containing the project's IServiceMetadata details, adding the AspireSample.ApiService project to the application model.

    This is a fundamental building block of .NET Aspire. The AddProject configures service discovery and communication between the projects in your app. The name argument apiservice is used to identify the project in the application model, and used later by projects that want to communicate with it.

  • Calls AddProject again, this time adding the AspireSample.Web project to the application model. It also chains multiple calls to WithReference passing the cache and apiservice variables.

    The WithReference API is another fundamental API of .NET Aspire, which injects either service discovery information or connection string configuration into the project being added to the application model.

  • Finally, the builder calls Build and Run to start the application.