From cc92e710b2d48ef765cf3d828aa5821c9e6beaba Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 10 Apr 2024 12:23:11 -0500 Subject: [PATCH 1/4] Fix up xref issues, and remove section --- docs/core/extensions/service-discovery.md | 34 ++++------------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/docs/core/extensions/service-discovery.md b/docs/core/extensions/service-discovery.md index 95f5c7edabc51..f10c56dfe5586 100644 --- a/docs/core/extensions/service-discovery.md +++ b/docs/core/extensions/service-discovery.md @@ -3,7 +3,7 @@ title: Service discovery in .NET description: Learn how to use the Microsoft.Extensions.ServiceDiscovery library to simplify the integration of service discovery patterns in .NET applications. author: IEvangelist ms.author: dapine -ms.date: 12/11/2023 +ms.date: 04/10/2024 ms.topic: overview --- @@ -34,7 +34,7 @@ For more information, see [dotnet add package](../tools/dotnet-add-package.md) o ## Example usage -In the _Program.cs_ file of your project, call the extension method to add service discovery to the host, configuring default service endpoint resolvers: +In the _Program.cs_ file of your project, call the extension method to add service discovery to the host, configuring default service endpoint resolvers: ```csharp builder.Services.AddServiceDiscovery(); @@ -80,11 +80,11 @@ Here's an example demonstrating how to configure endpoints for the service named 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 extension method on , the configuration-based endpoint resolver can be added by calling the extension method on `IServiceCollection`. +If service discovery was added to the host using the extension method on , the configuration-based endpoint resolver can be added by calling the extension method on `IServiceCollection`. ### Configuration -The configuration resolver is configured using the class, which offers these configuration options: +The configuration resolver is configured using the class, which offers these configuration options: - **SectionName**: The name of the configuration section that contains service endpoints. It defaults to `"Services"`. @@ -120,31 +120,7 @@ The pass-through resolver performs no external resolution and instead resolves e 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 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 instance to the method call. For example, to select a random endpoint from the set of resolved endpoints, specify as the endpoint selector: - -```csharp -builder.Services.AddHttpClient( - static client => client.BaseAddress = new("http://catalog") - ) - .UseServiceDiscovery(RandomServiceEndPointSelectorProvider.Instance); -``` - -The `Microsoft.Extensions.ServiceDiscovery` package includes the following endpoint selector providers: - -- : Pick-first, which always selects the first endpoint. -- : Round-robin, which cycles through endpoints. -- : Random, which selects endpoints randomly. -- : Power-of-two-choices, which attempt to pick the least used endpoint based on the _Power of Two Choices_ algorithm for distributed load balancing, degrading to randomly selecting an endpoint when either of the provided endpoints don't have the feature. - -Endpoint selectors are created via an instance, such as the providers previously listed. The provider's method is called to create a selector, which is an instance of . The `IServiceEndPointSelector` instance is given the set of known endpoints when they're resolved, using the method. To choose an endpoint from the collection, the 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 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 `ServiceEndPoint`s 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. +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 extension method on `IServiceCollection`. ## See also From 909be91b5f9533b0434c74981b055a67c5bd0d4f Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 10 Apr 2024 12:31:15 -0500 Subject: [PATCH 2/4] More fixes and corrections --- docs/core/extensions/service-discovery.md | 33 +++++++++++++++++++---- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/core/extensions/service-discovery.md b/docs/core/extensions/service-discovery.md index f10c56dfe5586..4846f2d7c683c 100644 --- a/docs/core/extensions/service-discovery.md +++ b/docs/core/extensions/service-discovery.md @@ -40,14 +40,14 @@ In the _Program.cs_ file of your project, call the by calling the `UseServiceDiscovery` extension method: +Add service discovery to an individual by calling the `AddServiceDiscovery` extension method: ```csharp builder.Services.AddHttpClient(static client => { - client.BaseAddress = new("http://catalog"); + client.BaseAddress = new("https://catalog"); }) - .UseServiceDiscovery(); + .AddServiceDiscovery(); ``` Alternatively, you can add service discovery to all instances by default: @@ -60,6 +60,27 @@ builder.Services.ConfigureHttpClientDefaults(static http => }); ``` +## Scheme selection when resolving HTTP(S) endpoints + +It is common to use HTTP while developing and testing a service locally and HTTPS when the service is deployed. Service Discovery supports this by allowing for a priority list of URI schemes to be specified in the input string given to Service Discovery. Service Discovery will attempt to resolve the services for the schemes in order and will stop after an endpoint is found. URI schemes are separated by a `+` character, for example: `"https+http://basket"`. Service Discovery will first try to find HTTPS endpoints for the `"basket"` service and will then fall back to HTTP endpoints. If any HTTPS endpoint is found, Service Discovery will not include HTTP endpoints. + +Schemes can be filtered by configuring the `AllowedSchemes` and `AllowAllSchemes` properties on `ServiceDiscoveryOptions`. The `AllowAllSchemes` property is used to indicate that all schemes are allowed. By default, `AllowAllSchemes` is `true` and all schemes are allowed. Schemes can be restricted by setting `AllowAllSchemes` to `false` and adding allowed schemes to the `AllowedSchemes` property. For example, to allow only HTTPS: + +```csharp +services.Configure(options => +{ + options.AllowAllSchemes = false; + options.AllowedSchemes = ["https"]; +}); +``` + +To explicitly allow all schemes, set the `ServiceDiscoveryOptions.AllowAllSchemes` property to `true`: + +```csharp +services.Configure( + options => options.AllowAllSchemes = true); +``` + ## Resolve service endpoints from configuration The `AddServiceDiscovery` extension method adds a configuration-based endpoint resolver by default. @@ -70,15 +91,17 @@ Here's an example demonstrating how to configure endpoints for the service named ```json { "Services": { + "https": { "catalog": [ "localhost:8080", - "10.46.24.90:80", + "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. +The preceding example adds two endpoints for the service named _catalog_: `https://localhost:8080`, and `"https://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 extension method on , the configuration-based endpoint resolver can be added by calling the extension method on `IServiceCollection`. From c020eea6af965c97ad48dfc0f55bd66ebfc98098 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 10 Apr 2024 12:43:39 -0500 Subject: [PATCH 3/4] Fix last UseServiceDiscovery --- docs/core/extensions/service-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/extensions/service-discovery.md b/docs/core/extensions/service-discovery.md index 4846f2d7c683c..7831d5d1fc2d8 100644 --- a/docs/core/extensions/service-discovery.md +++ b/docs/core/extensions/service-discovery.md @@ -56,7 +56,7 @@ Alternatively, you can add service discovery to all { // Turn on service discovery by default - http.UseServiceDiscovery(); + http.AddServiceDiscovery(); }); ``` From 0da76dd16da92fbb2536e5299e48fe74e68eba9a Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 10 Apr 2024 12:46:06 -0500 Subject: [PATCH 4/4] Fix JSON --- docs/core/extensions/service-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/extensions/service-discovery.md b/docs/core/extensions/service-discovery.md index 7831d5d1fc2d8..078669e10c31d 100644 --- a/docs/core/extensions/service-discovery.md +++ b/docs/core/extensions/service-discovery.md @@ -91,8 +91,8 @@ Here's an example demonstrating how to configure endpoints for the service named ```json { "Services": { - "https": { - "catalog": [ + "catalog": { + "https": [ "localhost:8080", "10.46.24.90:80" ]