Service discovery in .NET

In this article, you learn how to use the Microsoft.Extensions.ServiceDiscovery library. Service discovery is a way for developers to use logical names instead of physical addresses (IP address and port) to refer to external services.

Get Started

To get started with service discovery in .NET, install the Microsoft.Extensions.ServiceDiscovery NuGet package.

dotnet add package Microsoft.Extensions.ServiceDiscovery --prerelease

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Example usage

In the Program.cs file of your project, call the AddServiceDiscovery extension method to add service discovery to the host, configuring default service endpoint resolvers:

builder.Services.AddServiceDiscovery();

Add service discovery to an individual IHttpClientBuilder by calling the UseServiceDiscovery extension method:

builder.Services.AddHttpClient<CatalogServiceClient>(static client =>
    {
        client.BaseAddress = new("http://catalog");
    })
    .UseServiceDiscovery();

Alternatively, you can add service discovery to all HttpClient instances by default:

builder.Services.ConfigureHttpClientDefaults(static http =>
{
    // Turn on service discovery by default
    http.UseServiceDiscovery();
});

Resolve service endpoints from configuration

The AddServiceDiscovery extension method adds a configuration-based endpoint resolver by default. This resolver reads endpoints from the .NET configuration system. The library supports configuration through appsettings.json, environment variables, or any other IConfiguration source.

Here's an example demonstrating how to configure endpoints for the service named catalog via appsettings.json:

{
  "Services": {
      "catalog": [
        "localhost:8080",
        "10.46.24.90:80",
      ]
    }
}

The preceding example adds two endpoints for the service named catalog: localhost:8080, and "10.46.24.90:80". Each time the catalog is resolved, one of these endpoints is selected.

If service discovery was added to the host using the AddServiceDiscoveryCore extension method on IServiceCollection, the configuration-based endpoint resolver can be added by calling the AddConfigurationServiceEndPointResolver extension method on IServiceCollection.

Configuration

The configuration resolver is configured using the ConfigurationServiceEndPointResolverOptions class, which offers these configuration options:

  • SectionName: The name of the configuration section that contains service endpoints. It defaults to "Services".

  • ApplyHostNameMetadata: A delegate used to determine if host name metadata should be applied to resolved endpoints. It defaults to a function that returns false.

To configure these options, you can use the Configure extension method on the IServiceCollection within your application's Startup class or Program file:

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<ConfigurationServiceEndPointResolverOptions>(
    static options =>
    {
        options.SectionName = "MyServiceEndpoints";
    
        // Configure the logic for applying host name metadata
        options.ApplyHostNameMetadata = static endpoint =>
        {
            // Your custom logic here. For example:
            return endpoint.EndPoint is DnsEndPoint dnsEp
                && dnsEp.Host.StartsWith("internal");
        };
    });

The preceding example demonstrates setting a custom section name for your service endpoints and providing custom conditional logic for applying host name metadata.

Resolve service endpoints using platform-provided service discovery

Certain platforms, like Azure Container Apps and Kubernetes (when configured accordingly), offer service discovery capabilities without necessitating a service discovery client library. In cases where an application is deployed in such environments, using the platform's built-in functionality can be advantageous. The pass-through resolver is designed to facilitate this scenario. It enables the utilization of alternative resolvers, such as configuration, in different environments, such as a developer's machine. Importantly, this flexibility is achieved without the need for any code modifications or the implementation of conditional guards.

The pass-through resolver performs no external resolution and instead resolves endpoints by returning the input service name represented as a DnsEndPoint.

The pass-through provider is configured by-default when adding service discovery via the AddServiceDiscovery extension method.

If service discovery was added to the host using the AddServiceDiscoveryCore extension method on IServiceCollection, the pass-through provider can be added by calling the AddPassThroughServiceEndPointResolver extension method on IServiceCollection.

Load-balancing with endpoint selectors

Each time an endpoint is resolved via the HttpClient pipeline, a single endpoint is selected from the set of all known endpoints for the requested service. If multiple endpoints are available, it may be desirable to balance traffic across all such endpoints. To accomplish this, a customizable endpoint selector can be used. By default, endpoints are selected in round-robin order. To use a different endpoint selector, provide an IServiceEndPointSelector instance to the UseServiceDiscovery method call. For example, to select a random endpoint from the set of resolved endpoints, specify RandomServiceEndPointSelectorProvider.Instance as the endpoint selector:

builder.Services.AddHttpClient<CatalogServiceClient>(
        static client => client.BaseAddress = new("http://catalog")
    )
    .UseServiceDiscovery(RandomServiceEndPointSelectorProvider.Instance);

The Microsoft.Extensions.ServiceDiscovery package includes the following endpoint selector providers:

Endpoint selectors are created via an IServiceEndPointSelectorProvider instance, such as the providers previously listed. The provider's CreateSelector() method is called to create a selector, which is an instance of IServiceEndPointSelector. The IServiceEndPointSelector instance is given the set of known endpoints when they're resolved, using the IServiceEndPointSelector.SetEndPoints method. To choose an endpoint from the collection, the IServiceEndPointSelector.GetEndPoint method is called, returning a single ServiceEndPoint. The context value passed to GetEndPoint is used to provide extra context that may be useful to the selector. For example, in the HttpClient case, the HttpRequestMessage is passed. None of the provided implementations of IServiceEndPointSelector inspect the context, and it can be ignored unless you're using a selector, which does make use of it.

Resolution order

When service endpoints are being resolved, each registered resolver is called in the order of registration and given the opportunity to modify the collection of ServiceEndPoints which are returned back to the caller. The providers included in the Microsoft.Extensions.ServiceDiscovery series of packages skip resolution if there are existing endpoints in the collection when they're called. For example, consider a case where the following providers are registered: Configuration, DNS SRV, Pass-through. When resolution occurs, the providers are called in-order. If the Configuration providers discover no endpoints, the DNS SRV provider performs resolution and may add one or more endpoints. If the DNS SRV provider adds an endpoint to the collection, the Pass-through provider skips its resolution and returns immediately instead.

See also