skip to content

In an Aspire service, how does an HttpClient whose BaseAddress is https+http://rating-engine reach a real address?

level: middleimportance: should knowfreq 46%

answer

  1. a logical name, not a host
  2. services__rating-engine__https__0
  3. the Services configuration section
  4. first scheme with endpoints wins
  5. AllowAllSchemes defaults to true

basics

~20 s

The service-discovery handler that ConfigureHttpClientDefaults adds rewrites the logical URI: it looks up rating-engine in the Services configuration the AppHost injected, prefers HTTPS endpoints, falls back to HTTP only when none exist, and picks one endpoint per request.

solid answer

~40 s

`AddServiceDefaults` calls `Services.AddServiceDiscovery()` and adds `AddServiceDiscovery()` to every client through `ConfigureHttpClientDefaults`, so each `IHttpClientFactory` client gets a resolving handler. When the quotes API calls `https+http://rating-engine/price`, the handler asks the resolver for `rating-engine` with the scheme list `https`, `http`. The configuration provider reads the `Services:rating-engine` section, which the AppHost filled through variables such as `services__rating-engine__https__0` when the API was given `WithReference(ratingEngine)`. Schemes are tried in order and the first one with endpoints wins, so HTTP is used only when no HTTPS endpoint exists. With several endpoints, a round-robin selector picks one per request. If configuration has no entry, a pass-through provider hands the host name to DNS. `ServiceDiscoveryOptions.AllowAllSchemes` is `true` by default, and `AllowedSchemes` only filters once it is set to `false`.

code

csharp · 13 lines
csharp
builder.AddServiceDefaults();

builder.Services.AddHttpClient<RatingClient>(client =>
    client.BaseAddress = new("https+http://rating-engine"));

if (!builder.Environment.IsDevelopment())
{
    builder.Services.Configure<ServiceDiscoveryOptions>(options =>
    {
        options.AllowAllSchemes = false;
        options.AllowedSchemes = ["https"];
    });
}

go deeper

for a junior

Recall that https+http://rating-engine names an AppHost resource, and that the AppHost injects its addresses as Services configuration.

for a middle

Walk through resolution: the resolving handler, the configuration section, the scheme priority, round-robin selection and the pass-through fallback to DNS.

for a senior

Show that you know the HTTP fallback is silent, that AllowedSchemes needs AllowAllSchemes = false, and that only factory clients resolve logical names.

for a principal

Weigh configuration-driven discovery against platform DNS or a mesh for each deployment target, and decide where scheme policy should be enforced.

## A logical name instead of a host Across five services of an insurance-quoting platform, nobody wants port numbers in code. The quotes API registers its typed client with `client.BaseAddress = new("https+http://rating-engine")`. `rating-engine` is the **resource name** from the AppHost, not a DNS host, and `https+http` is not a real URI scheme: it is a **priority list** of schemes separated by `+`. Nothing in plain `HttpClient` understands that URI. It works because `AddServiceDefaults` registers two things from `Microsoft.Extensions.ServiceDiscovery`: - `Services.AddServiceDiscovery()` adds the resolver plus the **configuration** and **pass-through** endpoint providers; - `ConfigureHttpClientDefaults(http => http.AddServiceDiscovery())` puts a resolving delegating handler on every client created by `IHttpClientFactory`: named, typed and the default `HttpClient` from DI. A client created with `new HttpClient()` gets neither, so the same base address fails there. ## Where the endpoints come from In the AppHost, `quotesApi.WithReference(ratingEngine)` injects the rating engine's endpoints into the quotes API's environment, one variable per endpoint: `services__rating-engine__https__0`, `services__rating-engine__http__0`, and so on. .NET configuration turns `__` into `:`, so the API sees a section `Services:rating-engine:https` holding a list of URLs. The configuration provider reads the section named by `ConfigurationServiceEndpointProviderOptions.SectionName`, which defaults to `"Services"`, so a hand-written `appsettings.json` block works exactly like the injected variables. ## How `https+http` is resolved 1. The handler parses the URI into a service name, `rating-engine`, and the schemes `https` and `http`. 2. The configuration provider looks for a `default` endpoint section first, then for a section per listed scheme, and keeps the first that exists. 3. Among the endpoints found, only the earliest-listed scheme is kept: if any HTTPS endpoint exists, HTTP endpoints are not used. 4. A `RoundRobinServiceEndpointSelector` picks one endpoint for this request, which spreads calls across replicas. 5. The handler rewrites the request URI to that endpoint's scheme, host and port. A name such as `https://_grpc.rating-engine` asks for the endpoint named `grpc` instead of a scheme-named one. Results are watched for changes, and providers without change notifications are polled every `ServiceDiscoveryOptions.RefreshPeriod`, 60 seconds by default. ## When configuration has nothing The **pass-through** provider runs last and only if earlier providers found nothing. It turns the host part into a `DnsEndPoint`, so `rating-engine` is resolved by DNS, as in a container network or a cluster where the service name is also a host name. For a `+` URI the handler then uses the **first** listed scheme, so `https+http://rating-engine` becomes `https://rating-engine` on the scheme's default port. ## Restricting schemes | Setting | Default | Effect | |---|---|---| | `AllowAllSchemes` | `true` | every requested scheme is allowed | | `AllowedSchemes` | empty list | consulted only when `AllowAllSchemes` is `false` | | `RefreshPeriod` | 60 seconds | polling interval for providers without change tokens | The template contains a commented block that sets `options.AllowedSchemes = ["https"]`. In the 10.10.1 library that alone changes nothing, because `AllowAllSchemes` is still `true`; to forbid the HTTP fallback in production, set `AllowAllSchemes = false` as well. ## Why `https+http` Local runs often expose both an HTTPS and an HTTP endpoint, while some deployment targets terminate TLS elsewhere and expose only HTTP inside the network. The priority list lets one base address prefer encryption where it exists without a code change per environment. The price is that a missing HTTPS endpoint silently downgrades the call, which is exactly what the scheme restriction is for. ## Diagnosing a resolution failure When the quotes API cannot reach the rating engine, the checks run in the order the resolver works: - **Is the client a factory client?** A `new HttpClient()` or a client built outside DI never resolves logical names. - **Is the configuration there?** Print `builder.Configuration.GetSection("Services:rating-engine")` at startup, or inspect the environment the dashboard shows for the API; a missing `WithReference` in the AppHost leaves the section empty. - **Does the name match?** The key is the AppHost resource name, so a rename on one side breaks resolution on the other. - **Which scheme won?** An HTTPS-only listener with an `http` endpoint configured, or the reverse, shows up as connection errors rather than resolution errors. ## Interview angle The common weak answer is that the AppHost acts as a registry the service queries. It does not: the AppHost writes configuration once, when it starts the process, and resolution happens in-process from that configuration. That is also why a running service does not notice an endpoint added after it started, unless its configuration source changes.

  • What does the quotes API call if the AppHost injected only an HTTP endpoint for rating-engine?
    `http://` on the injected host and port. With no `https` section in `Services:rating-engine`, the configuration provider falls through to the `http` section and the handler uses that endpoint's scheme. Only restricting schemes with `AllowAllSchemes = false` and `AllowedSchemes = ["https"]` turns this silent fallback into a failure.
  • How does a service call a specific named endpoint, such as a gRPC port, of another resource?
    Put the endpoint name in the host with an underscore prefix: `https://_grpc.rating-engine`. The resolver then reads the `grpc` endpoint section of `Services:rating-engine` instead of choosing by scheme, and the pass-through provider strips the `_grpc.` prefix when it falls back to DNS.

  • https+http:// sends each request over HTTPS and retries it over HTTP on failure.
  • Setting AllowedSchemes to https alone blocks the HTTP fallback.
  • Service discovery asks the AppHost over the network for addresses at run time.
  • new HttpClient() gets service discovery once AddServiceDefaults has run.
  • Without a configuration entry, a logical name like rating-engine can never resolve.