.NET Aspire Service Discovery

Aspire automatically injects environment variables to help microservices to discover each other without hardcoding locations or ports.

In cloud based systems microservices frequently scale or move around. Service discovery is how those microservices can locate each other. For example:

Service A needs to call Service B's REST endpoint, but cannot rely on a hardcoded host or port.

With ,NET Aspire we can rely on configuration that is injected automatically, making each service discoverable by name. When you reference a microservice in another microservices, aspire automatically generates the configuration entries so they can find each other.

Suppose you have a web frontend that relies on the catalogue and basket microservices:

var builder = DistributedApplication.CreateBuilder(args);

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

var catalog = builder.AddProject<Projects.CatalogService>("catalog");

var basket = builder.AddProject<Projects.BasketService>("basket");

var frontend = builder.AddProject<Projects.MyFrontend>("frontend")
       .WithExternalHttpEndpoints()
       .WithReference(cache)
       .WaitFor(cache)
       .WithReference(catalog)
       .WaitFor(catalog)
       .WithReference(basket)
       .WaitFor(basket);

builder.Build().Run();

This frontend depends on the cache container, catalog, and basket projects. Aspire will inject service discovery info for the cache basket and catalog into the frontend project via configuration. So that means the frontend project adds resources using the WithReference method in order to add a dependency on the Redis container, Catalog and Basket projects into the front end application.

Built-In resource types

There are four resource types we can add:

Method	Resource Type	Description
AddProject	Project Resource	A .NET project, for example an ASP.NER Core Web App.
AddContainer	Container Resource	A container image, such as a Docker image.
AddExecutable	ExecutableResource	An executable such as a Node.js app
AddParameter	ParameterResource	A pareameter resource that can be used to express external parameters.

In our example you can see that the front end project is getting references for a cache container, and the catalog basket projects.

First of all in the cache container injecting connection string which is a connection string underscore, essentially the Redis container reference is injecting a connection string environment variable into the web front end project:

Project to project references are handled differently than resources that have well-defined connection strings.

We can integrate all these reference services using the named registrations.

We can also configure container endpoints. For container resources, you can define named endpoints that will later be referenced by the microservices:

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer")
                             .WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReference(endpoint);

In the above example we basically add a container and specify the WidthHttpEndpoint and define an endpoint. After that we can reach this endpoint using the custom container GetEndpoint method. We can now paste this endpoint in to get a reference for the project to project reference and inject the service discovery name into our API service projects. This is an example of the configuring container endpoints explicitly.