Service discovery

In this article, you learn how service discovery works within an Aspire project. Aspire includes functionality for configuring service discovery at development and testing time. Service discovery functionality works by providing configuration in the format expected by the configuration-based endpoint resolver from the Aspire AppHost project to the individual service projects added to the application model. For more information, see Service discovery in .NET.

Implicit service discovery by reference

Configuration for service discovery is only added for services that are referenced by a given project. For example, consider the following AppHost program:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

In the preceding example, the frontend project references the catalog project and the basket project. The two WithReference calls instruct the Aspire project to pass service discovery information for the referenced projects (catalog, and basket) into the frontend project.

Named endpoints

Some services expose multiple, named endpoints. Named endpoints can be resolved by specifying the endpoint name in the host portion of the HTTP request URI, following the format scheme://_endpointName.serviceName. For example, if a service named “basket” exposes an endpoint named “dashboard”, then the URI https+http://_dashboard.basket can be used to specify this endpoint, for example:

builder.Services.AddHttpClient<BasketServiceClient>(
    static client => client.BaseAddress = new("https+http://basket"));

builder.Services.AddHttpClient<BasketServiceDashboardClient>(
    static client => client.BaseAddress = new("https+http://_dashboard.basket"));

In the preceding example, two HttpClient classes are added, one for the core basket service and one for the basket service’s dashboard.

Named endpoints using configuration

With the configuration-based endpoint resolver, named endpoints can be specified in configuration by prefixing the endpoint value with _endpointName., where endpointName is the endpoint name. For example, consider this appsettings.json configuration which defined a default endpoint (with no name) and an endpoint named “dashboard”:

{
  "Services": {
    "basket": {
      "https": "https://10.2.3.4:8080", /* the https endpoint, requested via https://basket */
      "dashboard": "https://10.2.3.4:9999" /* the "dashboard" endpoint, requested via https://_dashboard.basket */
    }
  }
}

In the preceding JSON:

• The default endpoint, when resolving https://basket is 10.2.3.4:8080.
• The “dashboard” endpoint, resolved via https://_dashboard.basket is 10.2.3.4:9999.

Named endpoints in Aspire

Named endpoints can also be exposed by code in the App Host. For instance the previous example can be modeled as:

var basket = builder.AddProject<Projects.BasketService>("basket")
    .WithHttpsEndpoint(port: 9999, name: "dashboard");

Named endpoints in Kubernetes using DNS SRV

When deploying to Kubernetes, the DNS SRV service endpoint resolver can be used to resolve named endpoints. For example, the following resource definition will result in a DNS SRV record being created for an endpoint named “default” and an endpoint named “dashboard”, both on the service named “basket”.

apiVersion: v1
kind: Service
metadata:
  name: basket
spec:
  selector:
    name: basket-service
  clusterIP: None
  ports:
  - name: default
    port: 8080
  - name: dashboard
    port: 9999

To configure a service to resolve the “dashboard” endpoint on the “basket” service, add the DNS SRV service endpoint resolver to the host builder as follows:

builder.Services.AddServiceDiscoveryCore();
builder.Services.AddDnsSrvServiceEndpointProvider();

For more information, see AddServiceDiscoveryCore and AddDnsSrvServiceEndpointProvider.

The special port name “default” is used to specify the default endpoint, resolved using the URI https://basket.

As in the previous example, add service discovery to an HttpClient for the basket service:

builder.Services.AddHttpClient<BasketServiceClient>(
    static client => client.BaseAddress = new("https://basket"));

Similarly, the “dashboard” endpoint can be targeted as follows:

builder.Services.AddHttpClient<BasketServiceDashboardClient>(
    static client => client.BaseAddress = new("https://_dashboard.basket"));