Update documentation (#8537) (#8544)

Co-authored-by: Florian Bernd <git@flobernd.de>

Author: github-actions[bot]

README.md

@@ -2,7 +2,6 @@
 
 Repository for **Elastic.Clients.Elasticsearch** the official .NET client for
 [Elasticsearch](https://github.com/elastic/elasticsearch).
-*Older branches include both previous clients, **NEST** and **Elasticsearch.Net**.*
 
 **[Download the latest version of Elasticsearch](https://www.elastic.co/downloads/elasticsearch)**
 or
@@ -61,40 +60,13 @@ for comprehensive information on installation, configuration and usage.
 
 The API reference documentation is available [here](https://elastic.github.io/elasticsearch-net).
 
-## Versions
-
-### Elasticsearch 8.x Clusters
-
-We have released the next generation of the .NET client for Elasticsearch, which
-aligns with v8 of Elasticsearch. We have renamed this library
-`Elastic.Clients.Elasticsearch`, and the packages are published on
-[NuGet](https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/). The
-8.0.x versions do not offer complete feature parity with the existing `NEST`
-client. We therefore recommend you thoroughly review our
-[release notes and migration guidance](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/release-notes-8.0.0.html)
-before attempting to migrate existing applications to the
-`Elastic.Clients.Elasticsearch` library.
-
-Until the new client supports all endpoints and features your application
-requires, you may continue to use the latest `7.17.x` client to communicate with
-Elasticsearch v8 servers. Please review
-[our documentation](https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html),
-which describes how to enable compatibility mode and secure communications with
-a v8 cluster.
-
-### Elasticsearch 7.x Clusters
-
-We recommend using the latest `7.17.x`
-[NEST client](https://www.nuget.org/packages/Nest) to communicate with
-Elasticsearch v7 servers.
-
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md)
 
 ## Copyright and License
 
-This software is Copyright (c) 2014-2022 by Elasticsearch BV.
+This software is Copyright (c) 2014-2025 by Elasticsearch BV.
 
 This is free software, licensed under
 [The Apache License Version 2.0](https://github.com/elastic/elasticsearch-net/blob/main/LICENSE.txt).

docs/reference/_options_on_elasticsearchclientsettings.md

@@ -20,7 +20,6 @@ The following is a list of available connection configuration options on `Elasti
     `Base64ApiKey` for Elastic Cloud style encoded api keys
     ```
 
-
 `ClientCertificate`
 :   Use the following certificates to authenticate all HTTP requests. You can also set them on individual request using `ClientCertificates`.
 
@@ -34,7 +33,6 @@ The following is a list of available connection configuration options on `Elasti
 
     For Core CLR, this setting applies to the `MaxConnectionsPerServer` property on the `HttpClientHandler` instances used by the `HttpClient` inside the default `IConnection` implementation.
 
-
 `DeadTimeout`
 :   The time to put dead nodes out of rotation (this will be multiplied by the number of times they’ve been dead).
 
@@ -43,13 +41,11 @@ The following is a list of available connection configuration options on `Elasti
 
     The client by default will use the value of a property named `Id` on a CLR type as the `_id` to send to {{es}}. Adding a type will disable this behaviour for that CLR type. If `Id` inference should be disabled for all CLR types, use `DefaultDisableIdInference`.
 
-
 `DefaultFieldNameInferrer`
 :   Specifies how field names are inferred from CLR property names.
 
     By default, the client camel cases property names. For example, CLR property `EmailAddress` will be inferred as "emailAddress" {{es}} document field name.
 
-
 `DefaultIndex`
 :   The default index to use for a request when no index has been explicitly specified and no default indices are specified for the given CLR type specified for the request.
 
@@ -82,7 +78,6 @@ The following is a list of available connection configuration options on `Elasti
 
     For Desktop CLR, sets `ServicePointManager`.`SetTcpKeepAlive`.
 
-
 `EnableTcpStats`
 :   Enable statistics about TCP connections to be collected when making a request.
 
@@ -110,8 +105,8 @@ The following is a list of available connection configuration options on `Elasti
 `OnRequestCompleted`
 :   Allows you to register a callback every time a an API call is returned.
 
-`OnRequestDataCreated`
-:   An action to run when the `RequestData` for a request has been created.
+`OnBeforeRequest`
+:   An action to run before a request is made.
 
 `PingTimeout`
 :   The timeout in milliseconds to use for ping requests, which are issued to determine whether a node is alive.
@@ -121,7 +116,6 @@ The following is a list of available connection configuration options on `Elasti
 
     Note: this is not a guarantee you will always get prettified json.
 
-
 `Proxy`
 :   If your connection has to go through proxy, use this method to specify the proxy url.
 
@@ -148,7 +142,6 @@ The following is a list of available connection configuration options on `Elasti
 
     Reasons for such exceptions could be search parser errors, index missing exceptions, and so on.
 
-
 `TransferEncodingChunked`
 :   Whether the request should be sent with chunked Transfer-Encoding.
 
@@ -171,5 +164,3 @@ var settings= new ElasticsearchClientSettings()
 
 var client = new ElasticsearchClient(settings);
 ```
-
-

docs/reference/aggregations.md

@@ -7,124 +7,127 @@ mapped_pages:
 
 This page demonstrates how to use aggregations.
 
-
 ## Top-level aggreggation [_top_level_aggreggation]
 
-
 ### Fluent API [_fluent_api]
 
 ```csharp
-var response = await client
-	.SearchAsync<Person>(search => search
-		.Index("persons")
-		.Query(query => query
-			.MatchAll(_ => {})
-		)
-		.Aggregations(aggregations => aggregations
-			.Add("agg_name", aggregation => aggregation
-				.Max(max => max
-					.Field(x => x.Age)
-				)
-			)
-		)
-		.Size(10)
-	);
+var response = await client.SearchAsync<Person>(search => search
+    .Indices("persons")
+    .Query(query => query
+        .MatchAll()
+    )
+    .Aggregations(aggregations => aggregations
+        .Add("agg_name", aggregation => aggregation
+            .Max(max => max
+                .Field(x => x.Age)
+            )
+        )
+    )
+    .Size(10)
+);
 ```
 
-
 ### Object initializer API [_object_initializer_api]
 
 ```csharp
 var response = await client.SearchAsync<Person>(new SearchRequest("persons")
 {
-	Query = Query.MatchAll(new MatchAllQuery()),
-	Aggregations = new Dictionary<string, Aggregation>
-	{
-		{ "agg_name", Aggregation.Max(new MaxAggregation
-		{
-			Field = Infer.Field<Person>(x => x.Age)
-		})}
-	},
-	Size = 10
+    Query = new Query
+    {
+        MatchAll = new MatchAllQuery()
+    },
+    Aggregations = new Dictionary<string, Aggregation>
+    {
+        { "agg_name", new Aggregation
+        {
+            Max = new MaxAggregation
+            {
+                Field = Infer.Field<Person>(x => x.Age)
+            }
+        }}
+    },
+    Size = 10
 });
 ```
 
-
 ### Consume the response [_consume_the_response]
 
 ```csharp
 var max = response.Aggregations!.GetMax("agg_name")!;
 Console.WriteLine(max.Value);
 ```
 
-
 ## Sub-aggregation [_sub_aggregation]
 
-
 ### Fluent API [_fluent_api_2]
 
 ```csharp
-var response = await client
-	.SearchAsync<Person>(search => search
-		.Index("persons")
-		.Query(query => query
-			.MatchAll(_ => {})
-		)
-		.Aggregations(aggregations => aggregations
-			.Add("firstnames", aggregation => aggregation
-				.Terms(terms => terms
-					.Field(x => x.FirstName)
-				)
-				.Aggregations(aggregations => aggregations
-					.Add("avg_age", aggregation => aggregation
-						.Max(avg => avg
-							.Field(x => x.Age)
-						)
-					)
-				)
-			)
-		)
-		.Size(10)
-	);
+var response = await client.SearchAsync<Person>(search => search
+    .Indices("persons")
+    .Query(query => query
+        .MatchAll(_ => {})
+    )
+    .Aggregations(aggregations => aggregations
+        .Add("firstnames", aggregation => aggregation <1>
+            .Terms(terms => terms
+                .Field(x => x.FirstName)
+            )
+            .Aggregations(aggregations => aggregations
+                .Add("avg_age", aggregation => aggregation <2>
+                    .Max(avg => avg
+                        .Field(x => x.Age)
+                    )
+                )
+            )
+        )
+    )
+    .Size(10)
+);
 ```
 
+1. The top level `Terms` aggregation with name `firstnames`.
+2. Nested aggregation of type `Max` with name `avg_age`.
 
 ### Object initializer API [_object_initializer_api_2]
 
 ```csharp
-var topLevelAggregation = Aggregation.Terms(new TermsAggregation
-{
-	Field = Infer.Field<Person>(x => x.FirstName)
-});
-
-topLevelAggregation.Aggregations = new Dictionary<string, Aggregation>
+var response = await client.SearchAsync<Person>(new SearchRequest<Person>
 {
-	{ "avg_age", new MaxAggregation
-	{
-		Field = Infer.Field<Person>(x => x.Age)
-	}}
-};
-
-var response = await client.SearchAsync<Person>(new SearchRequest("persons")
-{
-	Query = Query.MatchAll(new MatchAllQuery()),
-	Aggregations = new Dictionary<string, Aggregation>
-	{
-		{ "firstnames", topLevelAggregation}
-	},
-	Size = 10
+    Query = new Query
+    {
+        MatchAll = new MatchAllQuery()
+    },
+    Aggregations = new Dictionary<string, Aggregation>
+    {
+        { "firstnames", new Aggregation
+        {
+            Terms = new TermsAggregation
+            {
+                Field = Infer.Field<Person>(x => x.FirstName)
+            },
+            Aggregations = new Dictionary<string, Aggregation>
+            {
+                { "avg_age", new Aggregation
+                {
+                    Max = new MaxAggregation
+                    {
+                        Field = Infer.Field<Person>(x => x.Age)
+                    }
+                }}
+            }
+        }}
+    }
 });
 ```
 
-
 ### Consume the response [_consume_the_response_2]
 
 ```csharp
 var firstnames = response.Aggregations!.GetStringTerms("firstnames")!;
 foreach (var bucket in firstnames.Buckets)
 {
-	var avg = bucket.Aggregations.GetAverage("avg_age")!;
-	Console.WriteLine($"The average age for persons named '{bucket.Key}' is {avg}");
+    var avg = bucket.Aggregations.GetAverage("avg_age")!;
+    Console.WriteLine($"The average age for persons named '{bucket.Key}' is {avg}");
 }
 ```
-

docs/reference/configuration.md

@@ -6,5 +6,3 @@ mapped_pages:
 # Configuration [configuration]
 
 Connecting to {{es}} with the client is easy, but it’s possible that you’d like to change the default connection behaviour. There are a number of configuration options available on `ElasticsearchClientSettings` that can be used to control how the client interact with {{es}}.
-
-

docs/reference/connecting.md

@@ -10,10 +10,10 @@ This page contains the information you need to create an instance of the .NET Cl
 It’s possible to connect to your {{es}} cluster via a single node, or by specifying multiple nodes using a node pool. Using a node pool has a few advantages over a single node, such as load balancing and cluster failover support. The client provides convenient configuration options to connect to an Elastic Cloud deployment.
 
 ::::{important}
-Client applications should create a single instance of `ElasticsearchClient` that is used throughout your application for its entire lifetime. Internally the client manages and maintains HTTP connections to nodes, reusing them to optimize performance. If you use a dependency injection container for your application, the client instance should be registered with a singleton lifetime.
-::::
 
+Client applications should create a single instance of `ElasticsearchClient` that is used throughout your application for its entire lifetime. Internally the client manages and maintains HTTP connections to nodes, reusing them to optimize performance. If you use a dependency injection container for your application, the client instance should be registered with a singleton lifetime.
 
+::::
 
 ## Connecting to a cloud deployment [cloud-deployment]
 
@@ -36,8 +36,6 @@ var client = new ElasticsearchClient("<CLOUD_ID>", new ApiKey("<API_KEY>")); <1>
 
 1. Replace the placeholder string values above with your cloud ID and the API key configured for your application to access your deployment.
 
-
-
 ## Connecting to a single node [single-node]
 
 Single node configuration is best suited to connections to a multi-node cluster running behind a load balancer or reverse proxy, which is exposed via a single URL. It may also be convenient to use a single node during local application development. If the URL represents a single {{es}} node, be aware that this offers no resiliency should the server be unreachable or unresponsive.
@@ -92,7 +90,6 @@ var client = new ElasticsearchClient(settings);
 
 The preceding snippet demonstrates configuring the client to authenticate by providing a username and password with basic authentication. If preferred, you may also use `ApiKey` authentication as shown in the cloud connection example.
 
-
 ## Connecting to multiple nodes using a node pool [multiple-nodes]
 
 To provide resiliency, you should configure multiple nodes for your cluster to which the client attempts to communicate. By default, the client cycles through nodes for each request in a round robin fashion. The client also tracks unhealthy nodes and avoids sending requests to them until they become healthy.
@@ -107,9 +104,9 @@ using Elastic.Transport;
 
 var nodes = new Uri[]
 {
-	new Uri("https://myserver1:9200"),
-	new Uri("https://myserver2:9200"),
-	new Uri("https://myserver3:9200")
+    new Uri("https://myserver1:9200"),
+    new Uri("https://myserver2:9200"),
+    new Uri("https://myserver3:9200")
 };
 
 var pool = new StaticNodePool(nodes);
@@ -120,4 +117,3 @@ var settings = new ElasticsearchClientSettings(pool)
 
 var client = new ElasticsearchClient(settings);
 ```
-