Skip to main content

Introducing .NET Aspire

What is .NET Aspire?​

.NET Aspire is an opinionated, cloud ready stack for building observable, production ready, distributed applications. .NET Aspire is delivered through a collection of NuGet packages that handle specific cloud-native concerns. Cloud-native apps often consist of small, interconnected pieces or microservices rather than a single, monolithic code base. Cloud-native apps generally consume a large number of services, such as databases, messaging, and caching.

A distributed application is one that uses computational resources across multiple nodes, such as containers running on different hosts. Such nodes must communicate over network boundaries to deliver responses to users. A cloud-native app is a specific type of distributed app that takes full advantage of the scalability, resilience, and manageability of cloud infrastructures.

.NET Aspire is designed to improve the experience of building .NET cloud-native apps. It provides a consistent, opinionated set of tools and patterns that help you build and run distributed apps. .NET Aspire is designed to help you with:

  • Orchestration: .NET Aspire provides features for running and connecting multi-project applications and their dependencies for local development environments.
  • Integrations: .NET Aspire integrations are NuGet packages for commonly used services, such as Redis or Postgres, with standardized interfaces ensuring they connect consistently and seamlessly with your app.
  • Tooling: .NET Aspire comes with project templates and tooling experiences for Visual Studio and the dotnet CLI help you create and interact with .NET Aspire apps.

Adding .NET Aspire​

Now we need to introduce the two main .NET Aspire projects in our solution.

To check that you have the .NET Aspire project templates installed run the following command:

dotnet new list aspire

Now cd into the src folder of our solution and create the .NET Aspire App Host by running:

dotnet new aspire-apphost -o Dometrain.Aspire.AppHost

This will create a new project called Dometrain.Aspire.AppHost.

We will also need a ServiceDefaults project. To create that run:

dotnet new aspire-servicedefaults -o Dometrain.Aspire.ServiceDefaults

We can now add the two projects in our solution.

Let's take a look at the two projects

Dometrain.Aspire.AppHost​

The Aspire AppHost project is responsible for running our system during local development. Please note the words "system" and "local development". Aspire won't be going to production. Instead, it is here to help us orchestrate running our cloud-native distributed system. From APIs, to background services, databases and caches, Aspire will be responsible for running everything we need, and it will make sure that our services can talk to each other.

As of now it only has the following 2 lines of code, but we will be adding many more.

var builder = DistributedApplication.CreateBuilder(args);
builder.Build().Run();

Dometrain.Aspire.ServiceDefaults​

The Aspire Service Defaults project is responsible for wiring up services, resilience and telemetry for our projects. It is being referred to by our main projects and the AddServiceDefaults and the MapDefaultEndpoints methods are used to do all the wiring for us.

Wiring .NET Aspire up​

To wire .NET Aspire up, first we need to refer Dometrain.Aspire.ServiceDefaults to the main API project.

Once that's done we can add the AddServiceDefaults call in the Program.cs:

builder.AddServiceDefaults();

Then we can add the Aspire endpoints by calling the MapDefaultEndpoints method under the Swagger calls:

app.MapDefaultEndpoints();

With all that now done we can wire up the API project to run through Aspire's AppHost project.

To do that we need the following inside AppHost's Program.cs:

var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.Dometrain_Monolith_Api>("dometrain-api");
builder.Build().Run();

This will enable us to run the Dometrain Api when the AppHost is started.

Since we will be running this project using http we will also need the following environment variable inside the launch profile:

"ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"

Now we can finally run the Aspire AppHost!