diff --git a/.gitignore b/.gitignore index 0ff3f64eef8..e52252f344e 100644 --- a/.gitignore +++ b/.gitignore @@ -30,7 +30,7 @@ test-results/* *.sbr *.DotSettings.user obj/ -[Rr]elease*/ +[Rr]elease/ _ReSharper*/ _NCrunch*/ [Tt]est[Rr]esult* diff --git a/docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc b/docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc index 4c7f30dac18..9010819d91f 100644 --- a/docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc +++ b/docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc @@ -33,7 +33,7 @@ but by exiting the pipeline. By default, the client won't throw on any `TransportException` but instead return an invalid response that can be detected by checking the `.IsValid` property on the response. You can change this behaviour with -by using `ThrowExceptions()` on <>. +by using `ThrowExceptions()` on <>. [source,csharp] ---- diff --git a/docs/client-concepts/high-level/getting-started.asciidoc b/docs/client-concepts/high-level/getting-started.asciidoc index 541e8386af5..4bd399f2c8f 100644 --- a/docs/client-concepts/high-level/getting-started.asciidoc +++ b/docs/client-concepts/high-level/getting-started.asciidoc @@ -41,7 +41,7 @@ var client = new ElasticClient(settings); ---- In this example, a default index was also specified to use if no other index is supplied for the request or can be inferred for the -POCO generic type parameter in the request. There are many other <> on `ConnectionSettings`. +POCO generic type parameter in the request. There are many other <> on `ConnectionSettings`. TIP: Specifying a default index is _optional_ but NEST may throw an exception if no index can be inferred for a given request. To understand more around how an index can be specified for a request, see <>. diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc new file mode 100644 index 00000000000..a577b3e40b6 --- /dev/null +++ b/docs/configuration.asciidoc @@ -0,0 +1,247 @@ +[[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}. + +=== Options on ElasticsearchClientSettings + +The following is a list of available connection configuration options on +`ElasticsearchClientSettings`: + +`Authentication`:: + +An implementation of `IAuthenticationHeader` describing what http header to use +to authenticate with the product. ++ + `BasicAuthentication` for basic authentication ++ + `ApiKey` for simple secret token ++ + `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`. + +`ClientCertificates`:: + +Use the following certificates to authenticate all HTTP requests. You can also +set them on individual request using `ClientCertificates`. + +`ConnectionLimit`:: + +Limits the number of concurrent connections that can be opened to an endpoint. +Defaults to 80 (see `DefaultConnectionLimit`). ++ +For Desktop CLR, this setting applies to the `DefaultConnectionLimit` property +on the `ServicePointManager` object when creating `ServicePoint` objects, +affecting the default `IConnection` implementation. ++ +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). + +`DefaultDisableIdInference`:: + +Disables automatic Id inference for given CLR types. ++ +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. + +`DefaultMappingFor`:: + +Specify how the mapping is inferred for a given CLR type. The mapping can infer +the index, id and relation name for a given CLR type, as well as control +serialization behaviour for CLR properties. + +`DisableAutomaticProxyDetection`:: + +Disabled proxy detection on the webrequest, in some cases this may speed up the +first connection your appdomain makes, in other cases it will actually increase +the time for the first connection. No silver bullet! Use with care! + +`DisableDirectStreaming`:: + +When set to true will disable (de)serializing directly to the request and +response stream and return a byte[] copy of the raw request and response. +Defaults to false. + +`DisablePing`:: + +This signals that we do not want to send initial pings to unknown/previously +dead nodes and just send the call straightaway. + +`DnsRefreshTimeout`:: + +DnsRefreshTimeout for the connections. Defaults to 5 minutes. + +`EnableDebugMode`:: + +Turns on settings that aid in debugging like `DisableDirectStreaming()` and +`PrettyJson()` so that the original request and response JSON can be inspected. +It also always asks the server for the full stack trace on errors. + +`EnableHttpCompression`:: + +Enable gzip compressed requests and responses. + +`EnableHttpPipelining`:: + +Whether HTTP pipelining is enabled. The default is `true`. + +`EnableTcpKeepAlive`:: + +Sets the keep-alive option on a TCP connection. ++ +For Desktop CLR, sets `ServicePointManager`.`SetTcpKeepAlive`. + +`EnableTcpStats`:: + +Enable statistics about TCP connections to be collected when making a request. + +`GlobalHeaders`:: + +Try to send these headers for every request. + +`GlobalQueryStringParameters`:: + +Append these query string parameters automatically to every request. + +`MaxDeadTimeout`:: + +The maximum amount of time a node is allowed to marked dead. + +`MaximumRetries`:: + +When a retryable exception occurs or status code is returned this controls the +maximum amount of times we should retry the call to {es}. + +`MaxRetryTimeout`:: + +Limits the total runtime including retries separately from `RequestTimeout`. +When not specified defaults to `RequestTimeout` which itself defaults to 60 +seconds. + +`MemoryStreamFactory`:: + +Provides a memory stream factory. + +`NodePredicate`:: + +Register a predicate to select which nodes that you want to execute API calls +on. Note that sniffing requests omit this predicate and always execute on all +nodes. When using an `IConnectionPool` implementation that supports reseeding of +nodes, this will default to omitting master only node from regular API calls. +When using static or single node connection pooling it is assumed the list of +node you instantiate the client with should be taken verbatim. + +`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. + +`PingTimeout`:: + +The timeout in milliseconds to use for ping requests, which are issued to +determine whether a node is alive. + +`PrettyJson`:: + +Provide hints to serializer and products to produce pretty, non minified json. ++ +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. + +`RequestTimeout`:: + +The timeout in milliseconds for each request to {es}. + +`ServerCertificateValidationCallback`:: + +Register a `ServerCertificateValidationCallback` per request. + +`SkipDeserializationForStatusCodes`:: + +Configure the client to skip deserialization of certain status codes, for +example, you run {es} behind a proxy that returns an unexpected json format. + +`SniffLifeSpan`:: + +Force a new sniff for the cluster when the cluster state information is older +than the specified timespan. + +`SniffOnConnectionFault`:: + +Force a new sniff for the cluster state every time a connection dies. + +`SniffOnStartup`:: + +Sniff the cluster state immediately on startup. + +`ThrowExceptions`:: + +Instead of following a c/go like error checking on response. `IsValid` do throw +an exception (except when `SuccessOrKnownError` is false) on the client when a +call resulted in an exception on either the client or the {es} server. ++ +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. + +`UserAgent`:: + +The user agent string to send with requests. Useful for debugging purposes to +understand client and framework versions that initiate requests to {es}. + + +==== ElasticsearchClientSettings with ElasticsearchClient + +Here's an example to demonstrate setting configuration options using the client. + +[source,csharp] +---- +var settings= new ElasticsearchClientSettings() + .DefaultMappingFor(i => i + .IndexName("my-projects") + .IdProperty(p => p.Name) + ) + .EnableDebugMode() + .PrettyJson() + .RequestTimeout(TimeSpan.FromMinutes(2)); + +var client = new ElasticsearchClient(settings); +---- diff --git a/docs/high-level.asciidoc b/docs/high-level.asciidoc index 440f8b04b0a..e44bfda44c0 100644 --- a/docs/high-level.asciidoc +++ b/docs/high-level.asciidoc @@ -52,8 +52,6 @@ include::{output-dir}/getting-started.asciidoc[] NEST uses sensible defaults for connecting to and interacting with an Elasticsearch cluster but provides numerous configuration options and components to change this behaviour -* <> - * <> * <> @@ -62,8 +60,6 @@ configuration options and components to change this behaviour * <> -include::client-concepts/connection/configuration-options.asciidoc[] - include::client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc[] include::client-concepts/connection/modifying-default-connection.asciidoc[] diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 296254867b9..5aae471854c 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -3,13 +3,8 @@ [[elasticsearch-net-reference]] = Elasticsearch .NET Client -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/index.asciidoc. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// +:net-client: Elasticsearch .NET Client + include::{asciidoc-dir}/../../shared/attributes.asciidoc[] @@ -19,6 +14,8 @@ include::install.asciidoc[] include::connecting.asciidoc[] +include::configuration.asciidoc[] + include::breaking-changes.asciidoc[] include::conventions.asciidoc[] @@ -32,3 +29,7 @@ include::search.asciidoc[] include::query-dsl.asciidoc[] include::aggregations.asciidoc[] + +include::redirects.asciidoc[] + +include::release-notes/release-notes.asciidoc[] \ No newline at end of file diff --git a/docs/install.asciidoc b/docs/install.asciidoc index 8ad222f6c9b..6dccb17a038 100644 --- a/docs/install.asciidoc +++ b/docs/install.asciidoc @@ -19,7 +19,7 @@ For SDK style projects, you can install the {es} client by running the following [source,text] ---- -dotnet add package Elastic.Clients.Elasticsearch -prerelease +dotnet add package Elastic.Clients.Elasticsearch --prerelease ---- This command adds a package reference to your project (csproj) file for the diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc new file mode 100644 index 00000000000..73832712f0e --- /dev/null +++ b/docs/redirects.asciidoc @@ -0,0 +1,9 @@ +["appendix",role="exclude",id="redirects"] += Deleted pages + +The following pages have moved or been deleted. + +[role="exclude",id="configuration-options"] +== Configuration options + +This page has moved. See <>. \ No newline at end of file diff --git a/docs/release-notes/breaking-change-policy.asciidoc b/docs/release-notes/breaking-change-policy.asciidoc new file mode 100644 index 00000000000..7e1eb4873b2 --- /dev/null +++ b/docs/release-notes/breaking-change-policy.asciidoc @@ -0,0 +1,30 @@ +[[breaking-changes-policy]] +== Breaking changes policy + +The {net-client} source code is generated from a https://github.com/elastic/elasticsearch-specification[formal specification of the Elasticsearch API]. This API specification is large, and although it is tested against hundreds of Elasticsearch test files, it may have discrepancies with the actual API that result in issues in the {net-client}. + +Fixing these discrepancies in the API specification results in code changes in the {net-client}, and some of these changes can require code updates in your applications. + +This section explains how these breaking changes are considered for inclusion in {net-client} releases. + +[discrete] +==== Breaking changes in patch releases + +Some issues in the API specification are properties that have an incorrect type, such as a `long` that should be a `string`, or a required property that is actually optional. These issues can cause the {net-client} to not work properly or even throw exceptions. + +When a specification issue is discovered and resolved, it may require code updates in applications using the {net-client}. Such breaking changes are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they introduce stability to APIs that may otherwise be unusable. + +[discrete] +==== Breaking changes in minor releases + +Along with these bug fixes, the API specification is constantly refined, more precise type definitions are introduced to improve developer comfort and remove ambiguities. The specification of often-used APIs is fairly mature, so these changes happen generally on less often used APIs. These changes can also cause breaking changes requiring code updates which are considered _acceptable in minor releases_ (e.g. 8.0 -> 8.1). + +[discrete] +==== Breaking changes in major releases + +Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {net-client}. These refactorings are considered carefully and done only when they unlock new important features or new developments. + +[discrete] +==== Elasticsearch API stability guarantees + +All Elasticsearch APIs have stability indicators, which imply potential changes. If an API is `stable` only additional non-breaking changes are added. In case of `experimental` APIs, breaking changes can be introduced any time, which means that these changes, will also be reflected in the {net-client}. \ No newline at end of file diff --git a/docs/release-notes/release-notes-8.0.0.asciidoc b/docs/release-notes/release-notes-8.0.0.asciidoc index cdec2bd2967..f69d8b57d94 100644 --- a/docs/release-notes/release-notes-8.0.0.asciidoc +++ b/docs/release-notes/release-notes-8.0.0.asciidoc @@ -2,7 +2,4 @@ [[release-notes-8.0.0]] == Release-Notes 8.0.0 -include::release-notes-8.0.0-human.asciidoc[] -include::release-notes-8.0.0-generated.asciidoc[] - - +Coming soon! diff --git a/docs/release-notes/release-notes.asciidoc b/docs/release-notes/release-notes.asciidoc index 258810203c4..dcad8ac40c3 100644 --- a/docs/release-notes/release-notes.asciidoc +++ b/docs/release-notes/release-notes.asciidoc @@ -1,15 +1,6 @@ [[release-notes]] = Release notes -[partintro] --- -Review important information about 8.0.x releases. - -* <> --- - - - -include::release-notes-8.0.0.asciidoc[] - +* <> +include::breaking-change-policy.asciidoc[]