From 90fbaf3c8d48e01c8162417884ace3b25c7c64a6 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 10:26:38 +0000 Subject: [PATCH 01/11] Add usage sub-section and move examples --- docs/index.asciidoc | 2 +- docs/{ => usage}/examples.asciidoc | 0 docs/usage/index.asciidoc | 16 ++++++++++++++++ docs/usage/recommendations.asciidoc | 4 ++++ 4 files changed, 21 insertions(+), 1 deletion(-) rename docs/{ => usage}/examples.asciidoc (100%) create mode 100644 docs/usage/index.asciidoc create mode 100644 docs/usage/recommendations.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 9dc75e2cda7..a0560e47a3e 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -17,7 +17,7 @@ include::connecting.asciidoc[] include::configuration.asciidoc[] -include::examples.asciidoc[] +include::usage/index.asciidoc[] include::troubleshooting.asciidoc[] diff --git a/docs/examples.asciidoc b/docs/usage/examples.asciidoc similarity index 100% rename from docs/examples.asciidoc rename to docs/usage/examples.asciidoc diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc new file mode 100644 index 00000000000..902b41e5267 --- /dev/null +++ b/docs/usage/index.asciidoc @@ -0,0 +1,16 @@ +[[usage]] +== Using the .NET Client + +The sections below provide tutorials on the most frequently used and some less obvious features of {es}. + +For a full reference, see the {es-docs}/[Elasticsearch documentation] and in particular the {es-docs}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there. + +If you're new to {es}, make sure also to read {es-docs}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. + +* <> +* <> + +NOTE: This is still a work in progress, more sections will be added in the near future. + +include::examples.asciidoc[] +include::recommendations.asciidoc[] diff --git a/docs/usage/recommendations.asciidoc b/docs/usage/recommendations.asciidoc new file mode 100644 index 00000000000..f78c4989a3b --- /dev/null +++ b/docs/usage/recommendations.asciidoc @@ -0,0 +1,4 @@ +[[recommendations]] +== Usage recommendations + +TODO \ No newline at end of file From 245107e0eeef85614f2dc52ba1e5e52badf282f9 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 12:32:00 +0000 Subject: [PATCH 02/11] Reorder items --- docs/index.asciidoc | 2 +- docs/usage/index.asciidoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index a0560e47a3e..a4aad3da31d 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -4,9 +4,9 @@ = Elasticsearch .NET Client :net-client: Elasticsearch .NET Client +:es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch} :ref-current: {ref} - include::{asciidoc-dir}/../../shared/attributes.asciidoc[] include::intro.asciidoc[] diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 902b41e5267..6d0a29fb34e 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -7,10 +7,10 @@ For a full reference, see the {es-docs}/[Elasticsearch documentation] and in par If you're new to {es}, make sure also to read {es-docs}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. -* <> * <> +* <> NOTE: This is still a work in progress, more sections will be added in the near future. -include::examples.asciidoc[] include::recommendations.asciidoc[] +include::examples.asciidoc[] From 84edb0475f08852e54ea5f8f22ee48e481b1dd09 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 12:37:54 +0000 Subject: [PATCH 03/11] Stub out sections and fix headings --- docs/usage/examples.asciidoc | 12 ++++++------ docs/usage/recommendations.asciidoc | 12 +++++++++++- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/usage/examples.asciidoc b/docs/usage/examples.asciidoc index b483919c588..e787739d550 100644 --- a/docs/usage/examples.asciidoc +++ b/docs/usage/examples.asciidoc @@ -1,5 +1,5 @@ [[examples]] -== Examples +=== Examples This page helps you to understand how to perform various basic {es} CRUD operations using the .NET client. It demonstrates how to create a document by @@ -45,7 +45,7 @@ using the ID specified by the value of this property. [discrete] [[indexing-net]] -=== Indexing a document +==== Indexing a document Documents can be indexed by creating an instance representing a tweet and indexing it via the client. In these examples, we will work with an index named @@ -77,7 +77,7 @@ operation succeeded. [discrete] [[getting-net]] -=== Getting a document +==== Getting a document [source,csharp] ---- @@ -91,7 +91,7 @@ accessible on the response via the `Source` property. [discrete] [[searching-net]] -=== Searching for documents +==== Searching for documents The client exposes a fluent interface and a powerful query DSL for searching. @@ -146,7 +146,7 @@ search operation. [discrete] [[updating-net]] -=== Updating documents +==== Updating documents Documents can be updated in several ways, including by providing a complete replacement for an existing document ID. @@ -169,7 +169,7 @@ if (response.IsValid) [discrete] [[deleting-net]] -=== Deleting documents +==== Deleting documents Documents can be deleted by providing the ID of the document to remove. diff --git a/docs/usage/recommendations.asciidoc b/docs/usage/recommendations.asciidoc index f78c4989a3b..7406ae57489 100644 --- a/docs/usage/recommendations.asciidoc +++ b/docs/usage/recommendations.asciidoc @@ -1,4 +1,14 @@ [[recommendations]] -== Usage recommendations +=== Usage recommendations + +TODO + +[discrete] +==== Instantiating the client + +TODO + +[discrete] +==== Choosing between synchronous and asynchronous APIs TODO \ No newline at end of file From b3f2e72436cb0ff1a5e2cbd26c7c805e1fce595e Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 13:32:26 +0000 Subject: [PATCH 04/11] Add additional dependency --- docs/index.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index a4aad3da31d..b00282d28d8 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -8,6 +8,7 @@ :ref-current: {ref} include::{asciidoc-dir}/../../shared/attributes.asciidoc[] +include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] include::intro.asciidoc[] From 18e1c27778f5fa57efeb51447c8326701fcce7f1 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 14:06:59 +0000 Subject: [PATCH 05/11] Reorder includes --- docs/index.asciidoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index b00282d28d8..d81e09efc71 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,14 +1,13 @@ -:title-separator: | - [[elasticsearch-net-reference]] = Elasticsearch .NET Client +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] +include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] + :net-client: Elasticsearch .NET Client :es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch} :ref-current: {ref} - -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] +:title-separator: | include::intro.asciidoc[] From e99bbef124211946e1d96ead8a50010a6ec41570 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 14:31:40 +0000 Subject: [PATCH 06/11] Update to ref-current for docs links --- docs/index.asciidoc | 9 ++++----- docs/usage/index.asciidoc | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index d81e09efc71..2d4df5e5186 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,13 +1,12 @@ +:title-separator: | + [[elasticsearch-net-reference]] = Elasticsearch .NET Client -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] - :net-client: Elasticsearch .NET Client -:es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch} :ref-current: {ref} -:title-separator: | + +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] include::intro.asciidoc[] diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 6d0a29fb34e..67202d34c3b 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -3,9 +3,9 @@ The sections below provide tutorials on the most frequently used and some less obvious features of {es}. -For a full reference, see the {es-docs}/[Elasticsearch documentation] and in particular the {es-docs}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there. +For a full reference, see the {ref-current}/[Elasticsearch documentation] and in particular the {ref-current}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there. -If you're new to {es}, make sure also to read {es-docs}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. +If you're new to {es}, make sure also to read {ref-current}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. * <> * <> From a08a47c22d8ec0e57c88a14058bb259e66b8563e Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 15:41:14 +0000 Subject: [PATCH 07/11] Add initial recommendations --- docs/usage/examples.asciidoc | 2 +- docs/usage/index.asciidoc | 2 +- docs/usage/recommendations.asciidoc | 12 ++++++++---- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/usage/examples.asciidoc b/docs/usage/examples.asciidoc index e787739d550..753df5377b3 100644 --- a/docs/usage/examples.asciidoc +++ b/docs/usage/examples.asciidoc @@ -1,5 +1,5 @@ [[examples]] -=== Examples +=== CRUD usage examples This page helps you to understand how to perform various basic {es} CRUD operations using the .NET client. It demonstrates how to create a document by diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 67202d34c3b..3b6d661e7fa 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -8,7 +8,7 @@ For a full reference, see the {ref-current}/[Elasticsearch documentation] and in If you're new to {es}, make sure also to read {ref-current}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. * <> -* <> +* <> NOTE: This is still a work in progress, more sections will be added in the near future. diff --git a/docs/usage/recommendations.asciidoc b/docs/usage/recommendations.asciidoc index 7406ae57489..f1b94138517 100644 --- a/docs/usage/recommendations.asciidoc +++ b/docs/usage/recommendations.asciidoc @@ -1,14 +1,18 @@ [[recommendations]] === Usage recommendations -TODO - [discrete] ==== Instantiating the client -TODO +When working with the {net-client} we recommend that consumers reuse a single instance of `ElasticsearchClient`. When reusing the same instance: + +- initialization overhead is limited to the first usage. +- resources such as TCP connections can be pooled and reused to improve efficiency +- serialization overhead is reduced, improving performance. + +The `ElasticsearchClient` type is thread-safe and can be shared and reused across multiple threads in consuming applications. We recommend instantiating a single instance to be used across all application call sites. Client reuse can be achieved by creating a singleton static instance or by registering the type as a singleton with dependency injection containers. [discrete] ==== Choosing between synchronous and asynchronous APIs -TODO \ No newline at end of file +The {net-client} exposes synchronous and asynchronous methods on the `ElasticsearchClient`. We recommend always preferring the asynchronous methods, which have the `Async` suffix. Using the {net-client} requires sending HTTP requests to {es} servers. Access to {es} is sometimes slow or delayed, and some complex queries may take several seconds to return. If such operations are blocked by calling the synchronous methods, the thread must wait until the HTTP request is complete. In high-load scenarios, this can cause significant thread usage, potentially affecting the throughput and performance of consuming applications. By preferring the asynchronous methods, application threads can continue with other work that doesn't depend on the web resource until the potentially blocking task completes. \ No newline at end of file From 7d1f833ee00726b52c30c0e991798d4be59e4593 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 16:37:21 +0000 Subject: [PATCH 08/11] Update recommendations --- docs/usage/examples.asciidoc | 8 ++++---- docs/usage/recommendations.asciidoc | 31 +++++++++++++++++++++++------ 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/usage/examples.asciidoc b/docs/usage/examples.asciidoc index 753df5377b3..a882f5db587 100644 --- a/docs/usage/examples.asciidoc +++ b/docs/usage/examples.asciidoc @@ -2,10 +2,10 @@ === CRUD usage examples This page helps you to understand how to perform various basic {es} CRUD -operations using the .NET client. It demonstrates how to create a document by -indexing an object into {es}, read a document back, retrieving it by ID or -performing a search, update one of the fields in a document and delete a -specific document. +(create, read, update, delete) operations using the .NET client. It demonstrates +how to create a document by indexing an object into {es}, read a document back, +retrieving it by ID or performing a search, update one of the fields in a +document and delete a specific document. These examples assume you have an instance of the `ElasticsearchClient` accessible via a local variable named `client` and several using directives in diff --git a/docs/usage/recommendations.asciidoc b/docs/usage/recommendations.asciidoc index f1b94138517..70c01c87b5d 100644 --- a/docs/usage/recommendations.asciidoc +++ b/docs/usage/recommendations.asciidoc @@ -1,18 +1,37 @@ [[recommendations]] === Usage recommendations +To achieve the most efficient use of the {net-client}, we recommend following +the guidance defined in this article. + [discrete] -==== Instantiating the client +==== Reuse the same client instance -When working with the {net-client} we recommend that consumers reuse a single instance of `ElasticsearchClient`. When reusing the same instance: +When working with the {net-client} we recommend that consumers reuse a single +instance of `ElasticsearchClient` for the entire lifetime of the application. +When reusing the same instance: - initialization overhead is limited to the first usage. -- resources such as TCP connections can be pooled and reused to improve efficiency +- resources such as TCP connections can be pooled and reused to improve +efficiency. - serialization overhead is reduced, improving performance. -The `ElasticsearchClient` type is thread-safe and can be shared and reused across multiple threads in consuming applications. We recommend instantiating a single instance to be used across all application call sites. Client reuse can be achieved by creating a singleton static instance or by registering the type as a singleton with dependency injection containers. +The `ElasticsearchClient` type is thread-safe and can be shared and reused +across multiple threads in consuming applications. Client reuse can be achieved +by creating a singleton static instance or by registering the type with a +singleton lifetime when using dependency injection containers. [discrete] -==== Choosing between synchronous and asynchronous APIs +==== Prefer asynchronous methods -The {net-client} exposes synchronous and asynchronous methods on the `ElasticsearchClient`. We recommend always preferring the asynchronous methods, which have the `Async` suffix. Using the {net-client} requires sending HTTP requests to {es} servers. Access to {es} is sometimes slow or delayed, and some complex queries may take several seconds to return. If such operations are blocked by calling the synchronous methods, the thread must wait until the HTTP request is complete. In high-load scenarios, this can cause significant thread usage, potentially affecting the throughput and performance of consuming applications. By preferring the asynchronous methods, application threads can continue with other work that doesn't depend on the web resource until the potentially blocking task completes. \ No newline at end of file +The {net-client} exposes synchronous and asynchronous methods on the +`ElasticsearchClient`. We recommend always preferring the asynchronous methods, +which have the `Async` suffix. Using the {net-client} requires sending HTTP +requests to {es} servers. Access to {es} is sometimes slow or delayed, and some +complex queries may take several seconds to return. If such operations are +blocked by calling the synchronous methods, the thread must wait until the HTTP +request is complete. In high-load scenarios, this can cause significant thread +usage, potentially affecting the throughput and performance of consuming +applications. By preferring the asynchronous methods, application threads can +continue with other work that doesn't depend on the web resource until the +potentially blocking task completes. \ No newline at end of file From 9ea7152eb54281c22e71fd96475e7ab59df71d4a Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 16:39:38 +0000 Subject: [PATCH 09/11] Attempt to fix generated URLs --- docs/connecting.asciidoc | 2 +- docs/index.asciidoc | 8 +++----- docs/usage/index.asciidoc | 4 ++-- 3 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/connecting.asciidoc b/docs/connecting.asciidoc index 72637e739fb..bb7357f66e7 100644 --- a/docs/connecting.asciidoc +++ b/docs/connecting.asciidoc @@ -112,7 +112,7 @@ SHA256 Fingerprint= ---- Visit the -{ref-current}/configuring-stack-security.html[Connect clients to {es}] documentation for more information. +{ref}/configuring-stack-security.html[Connect clients to {es}] documentation for more information. The following snippet shows you how to create a client instance that connects to your {es} cluster via a single node, using the CA fingerprint: diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 2d4df5e5186..8b4372fafca 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,13 +1,11 @@ -:title-separator: | - [[elasticsearch-net-reference]] = Elasticsearch .NET Client -:net-client: Elasticsearch .NET Client -:ref-current: {ref} - include::{asciidoc-dir}/../../shared/attributes.asciidoc[] +:net-client: Elasticsearch .NET Client +:title-separator: | + include::intro.asciidoc[] include::install.asciidoc[] diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 3b6d661e7fa..893806774ef 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -3,9 +3,9 @@ The sections below provide tutorials on the most frequently used and some less obvious features of {es}. -For a full reference, see the {ref-current}/[Elasticsearch documentation] and in particular the {ref-current}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there. +For a full reference, see the {ref}/[Elasticsearch documentation] and in particular the {ref}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there. -If you're new to {es}, make sure also to read {ref-current}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. +If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. * <> * <> From 1907618c22e27df7e394a3b23849b32fdc9f1595 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 16:52:56 +0000 Subject: [PATCH 10/11] Update includes --- docs/index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 8b4372fafca..5e4dcb223ae 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,10 +1,10 @@ [[elasticsearch-net-reference]] = Elasticsearch .NET Client +include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :net-client: Elasticsearch .NET Client -:title-separator: | include::intro.asciidoc[] From 0cbf53622b16c0a8984561c750e9c08e543bf611 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 17 Nov 2022 17:08:46 +0000 Subject: [PATCH 11/11] Fix connecting link --- docs/connecting.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/connecting.asciidoc b/docs/connecting.asciidoc index bb7357f66e7..13d706ba04d 100644 --- a/docs/connecting.asciidoc +++ b/docs/connecting.asciidoc @@ -112,7 +112,8 @@ SHA256 Fingerprint= ---- Visit the -{ref}/configuring-stack-security.html[Connect clients to {es}] documentation for more information. +{ref}/configuring-stack-security.html[Start the Elastic Stack with security enabled automatically] +documentation for more information. The following snippet shows you how to create a client instance that connects to your {es} cluster via a single node, using the CA fingerprint: