diff --git a/docs/connecting.asciidoc b/docs/connecting.asciidoc index 72637e739fb..13d706ba04d 100644 --- a/docs/connecting.asciidoc +++ b/docs/connecting.asciidoc @@ -112,7 +112,8 @@ SHA256 Fingerprint= ---- Visit the -{ref-current}/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: diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 9dc75e2cda7..5e4dcb223ae 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,14 +1,11 @@ -:title-separator: | - [[elasticsearch-net-reference]] = Elasticsearch .NET Client -:net-client: Elasticsearch .NET Client -:ref-current: {ref} - - +include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] +:net-client: Elasticsearch .NET Client + include::intro.asciidoc[] include::install.asciidoc[] @@ -17,7 +14,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 91% rename from docs/examples.asciidoc rename to docs/usage/examples.asciidoc index b483919c588..a882f5db587 100644 --- a/docs/examples.asciidoc +++ b/docs/usage/examples.asciidoc @@ -1,11 +1,11 @@ [[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 -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 @@ -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/index.asciidoc b/docs/usage/index.asciidoc new file mode 100644 index 00000000000..893806774ef --- /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 {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}/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::recommendations.asciidoc[] +include::examples.asciidoc[] diff --git a/docs/usage/recommendations.asciidoc b/docs/usage/recommendations.asciidoc new file mode 100644 index 00000000000..70c01c87b5d --- /dev/null +++ b/docs/usage/recommendations.asciidoc @@ -0,0 +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] +==== Reuse the same client 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. +- serialization overhead is reduced, improving performance. + +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] +==== 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