From 6135c1cc9973c7974e19cf411d50a45bb7b365cb Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 13 Apr 2023 08:24:44 +0100 Subject: [PATCH] Improve introduction documentation (#7652) --- docs/index.asciidoc | 2 +- docs/install.asciidoc | 17 +++++++++++------ docs/intro.asciidoc | 39 +++++++++++++++++++++++++++++++++++++-- 3 files changed, 49 insertions(+), 9 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index c6684a15d7b..48afe9daf15 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -5,8 +5,8 @@ include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :doc-tests-src: {docdir}/../tests/Tests/Documentation - :net-client: Elasticsearch .NET Client +:latest-version: 8.1.0 include::intro.asciidoc[] diff --git a/docs/install.asciidoc b/docs/install.asciidoc index dfb22ee5db7..bed347276f6 100644 --- a/docs/install.asciidoc +++ b/docs/install.asciidoc @@ -5,10 +5,14 @@ This page shows you how to install the .NET client for {es}. IMPORTANT: The v8 client for .NET does not have complete feature parity with the v7 `NEST` client. It may not be suitable for for all applications until -additional endpoints and features are supported. We therefore recommend you thoroughly review our <> 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 7.17.x release of the client to communicate with v8 -Elasticsearch servers using compatibility mode. Refer to the -https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html[Connecting to Elasticsearch v8.x using the v7.17.x client documentation] for guidance on configuring the 7.17.x client. +additional endpoints and features are supported. We therefore recommend you thoroughly +review our <> 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 7.17.x https://www.nuget.org/packages/NEST[NEST] client +to communicate with v8 Elasticsearch servers using compatibility mode. Refer to the +https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html[Connecting to Elasticsearch v8.x using the v7.17.x client documentation] +for guidance on configuring the 7.17.x client. [discrete] [[dot-net-client]] @@ -30,10 +34,11 @@ file: [source,shell] ---- - + ---- _NOTE: The version number should reflect the latest published version from -https://www.nuget.org/packages/Elastic.Clients.Elasticsearch[NuGet.org]. To install a different version, modify the version as necessary._ +https://www.nuget.org/packages/Elastic.Clients.Elasticsearch[NuGet.org]. To install +a different version, modify the version as necessary._ For Visual Studio users, the .NET client can also be installed from the Package Manager Console inside Visual Studio using the following command: diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index ee05451c24f..919b9f9dff1 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -1,8 +1,24 @@ +:github: https://github.com/elastic/elasticsearch-net + [[introduction]] == Introduction -This is the documentation for the .NET client for {es}. This page gives you a -quick overview of the main features of the client. +*Rapidly develop applications with the .NET client for {es}.* + +Designed for .NET client-application developers, you can utilize the .NET language client +library, which provides a strongly-typed API and query DSL to interact with {es}. +The .NET client library is designed to make it easy to use {es} from your .NET +applications. The .NET client includes higher-level abstractions, such as +helpers for coordinating bulk indexing and update operations. It also comes with +built-in, configurable cluster failover retry mechanisms. + +The {es} .NET client is available as a https://www.nuget.org/packages/Elastic.Clients.Elasticsearch[NuGet] +package that can be used in .NET Core, .NET 5+ and .NET Framework (4.6.1 and higher) +applications. + +_NOTE: This documentation relates to the v8 .NET client for {es}, designed for use +with {es} 8.x versions. To develop applications targetting {es} v7, you should +use the https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17[v7 (NEST) client]._ [discrete] [[features]] @@ -11,6 +27,7 @@ quick overview of the main features of the client. * One-to-one mapping with REST API. * Strongly typed requests and responses for {es} APIs. * Fluent API for building requests. +* Query DSL to assist with constructing search queries. * Helpers for common tasks such as bulk indexing of documents. * Pluggable serialization of requests and responses based on System.Text.Json. * Diagnostics, auditing, and .NET activity integration. @@ -19,3 +36,21 @@ The .NET {es} client is built upon the Elastic Transport library which provides: * Connection management and load balancing across all available nodes. * Request retries and dead connections handling. + +[discrete] +=== {es} version compatibility + +Language clients are forward compatible; meaning that clients support communicating +with greater or equal minor versions of {es}. {es} language clients are only +backwards compatible with default distributions and without guarantees made. + +[discrete] +=== Questions, bugs, comments, feature requests + +Bug reports and feature requests are more than welcome on the +{github}/issues[github issues pages]! + +For more general questions and comments, we monitor questions and discussions +opened on our community forum, https://discuss.elastic.co/c/elasticsearch[discuss.elastic.co]. +Mentioning `.NET` in the title helps folks quickly identify what +the question is about. \ No newline at end of file