From fb254fbdc1cbc2f85a435da10030f7f0f3e8a409 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 15 Aug 2023 10:51:38 +0200 Subject: [PATCH 01/19] Add basic NEST -> v8 migration guide --- docs/index.asciidoc | 2 + docs/migration-guide.asciidoc | 311 ++++++++++++++++++++++++++++++++++ 2 files changed, 313 insertions(+) create mode 100644 docs/migration-guide.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 6cb52216285..c70fe7f73a5 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -22,6 +22,8 @@ include::client-concepts/client-concepts.asciidoc[] include::usage/index.asciidoc[] +include::migration-guide.asciidoc[] + include::troubleshooting.asciidoc[] include::redirects.asciidoc[] diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc new file mode 100644 index 00000000000..2e37788c017 --- /dev/null +++ b/docs/migration-guide.asciidoc @@ -0,0 +1,311 @@ +[[migration-guide]] +== Migration guide NEST -> v8.* + +The following migration guide explains the current state of the client, missing +features, breaking changes and our rationale for some of the design choices we have introduced. + +[discrete] +=== Version 8 is a refresh + +[IMPORTANT] +-- +It is important to highlight that v8 of the {net-client} represents +a new start for the client design. It is important to review how this may affect +your code and usage. +-- + +Mature code becomes increasingly hard to maintain over time, and +our ability to make timely releases has diminished as code complexity has increased. +Major releases allow us to simplify and better align our language clients with +each other in terms of design. Here, it is crucial to find the right balance +between uniformity across programming languages and the idiomatic concerns of +each language. For .NET, we will typically compare and contrast with https://github.com/elastic/elasticsearch-java[Java] and https://github.com/elastic/go-elasticsearch[Go] +to make sure that our approach is equivalent for each of these. We also take +heavy inspiration from Microsoft framework design guidelines and the conventions +of the wider .NET community. + +[discrete] +==== New Elastic.Clients.Elasticsearch NuGet package + +We have shipped the new code-generated client as a +https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/[new NuGet package] +with a new root namespace, `Elastic.Clients.Elasticsearch`. +The new v8 client is built upon the foundations of the v7 `NEST` client, but there +are changes. By shipping as a new package, the expectation is that migration can +be managed with a phased approach. + +While this is a new package, we have aligned the major version (v8.x.x) with the +supported {es} server version to clearly indicate the client/server compatibility. +The v8 client is designed to work with version 8 of {es}. + +The v7 `NEST` client continues to be supported but will not gain new features or +support for new {es} endpoints. It should be considered deprecated in favour of +the new client. + +[discrete] +==== Limited feature set + +[CAUTION] +-- +The version 8 {net-client} does not have feature parity with the previous v7 `NEST` +high-level client. +-- + +If a feature you depend on is missing (and not explicitly documented below as a +feature that we do not plan to reintroduce), please open https://github.com/elastic/elasticsearch-net/issues/new/choose[an issue] +or comment on a relevant existing issue to highlight your need to us. This will +help us prioritise our roadmap. + +[discrete] +=== Code generation + +Given the size of the Elasticsearch API surface today, it is no longer practical +to maintain thousands of types (requests, responses, queries, aggregations, etc.) +by hand. To ensure consistent, accurate and timely alignment between language +clients and {es}, the 8.x clients, and many of the associated types are now +automatically code-generated from a https://github.com/elastic/elasticsearch-specification[shared specification]. This is a common solution to maintaining alignment between +client and server among SDKs and libraries, such as those for Azure, AWS and the +Google Cloud Platform. + +Code-generation from a specification has inevitably led to some differences +between the existing v7 `NEST` types and those available in the new v7 {net-client}. +For version 8, we generate strictly from the specification, special +casing a few areas to improve usability or to align with language idioms. + +The base type hierarchy for concepts such as `Properties`, `Aggregations` and +`Queries` is no longer present in generated code, as these arbitrary groupings do +not align with concrete concepts of the public server API. These considerations +do not preclude adding syntactic sugar and usability enhancements to types in future +releases on a case-by-case basis. + +[discrete] +=== Elastic.Transport + +The .NET client includes a transport layer responsible for abstracting HTTP +concepts and to provide functionality such as our request pipeline. This +supports round-robin load-balancing of requests to nodes, pinging failed +nodes and sniffing the cluster for node roles. + +In v7, this layer shipped as `Elasticsearch.Net` and was considered our low-level +client which could be used to send and receive raw JSON bytes between the client +and server. + +As part of the work for 8.0.0, we have moved the transport layer out into +a https://www.nuget.org/packages/Elastic.Transport[new dedicated package] and +https://github.com/elastic/elastic-transport-net[repository], named +`Elastic.Transport`. This supports reuse across future clients and allows +consumers with extremely high-performance requirements to build upon this foundation. + +[discrete] +=== System.Text.Json for serialization + +The v7 `NEST` high-level client used an internalized and modified version of +https://github.com/neuecc/Utf8Json[Utf8Json] for request and response +serialization. This was introduced for its performance improvements +over https://www.newtonsoft.com/json[Json.NET], the more common JSON framework at +the time. + +While Utf8Json provides good value, we have identified minor bugs and +performance issues that have required maintenance over time. Some of these +are hard to change without more significant effort. This library is no longer +maintained, and any such changes cannot easily be contributed back to the +original project. + +With .NET Core 3.0, Microsoft shipped new https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-apis[System.Text.Json APIs] +that are included in-the-box with current versions of .NET. We have adopted +`System.Text.Json` for all serialization. Consumers can still define and register +their own `Serializer` implementation for their document types should they prefer +to use a different serialization library. + +By adopting `System.Text.Json`, we now depend on a well-maintained and supported +library from Microsoft. `System.Text.Json` is designed from the ground up to support +the latest performance optimizations in .NET and, as a result, provides both fast and low-allocation serialization. + +[discrete] +=== Mockability of ElasticsearchClient + +Testing code is an important part of software development. We recommend +that consumers prefer introducing an abstraction for their use of the {net-client} +as the prefered way to decouple consuming code from client types and support unit +testing. + +In order to support user testing scenarios, we have unsealed the `ElasticsearchClient` +type and made its methods virtual. This supports mocking the type directly for unit +testing. This is an improvement over the original `IElasticClient` interface from +`NEST` (v7) which only supported mocking of top-level client methods. + +We have also introduced a `TestableResponseFactory` in `Elastic.Transport` to +make it easier to create response instances with specific status codes and validity +that can be used during unit testing. + +These changes are in addition to our existing support for testing with an +`InMemoryConnection`, virtualized clusters and with our +https://github.com/elastic/elasticsearch-net-abstractions/blob/master/src/Elastic.Elasticsearch.Managed[`Elastic.Elasticsearch.Managed`] library for integration +testing against real {es} instances. + +[discrete] +=== Migrating to Elastic.Clients.Elasticsearch + +[WARNING] +-- +The version 8 client does not currently have full-feature parity with `NEST`. The +client primary use case is for application developers communitating with {es}. +-- + +The version 8 client focuses on core endpoints, more specifically for common CRUD +scenarios. We intend to reduce the feature gap in subsequent versions. We recommend reviewing this documentation carefully to learn about the missing features and reduced API surface details before migrating from the v7 `NEST` client. + +The choice to code-generate a new evolution of the {net-client} introduces some +significant breaking changes. We consciously took the opportunity to refactor +and reconsider historic design choices as part of this major release, intending +to limit future breaking changes. + +The v8 client is shipped as a new https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/[NuGet package] +which can be installed alongside v7 `NEST`. We +anticipate that some consumers may prefer a phased migration with both +packages side-by-side for a short period of time to manage complex migrations. In addition, `NEST` 7.17.x can continue to be used in +https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html[compatibility mode] +with {es} 8.x servers until the v8 {net-client} features +align with application requirements. + +[discrete] +=== Breaking Changes + +[WARNING] +-- +As a result of code-generating a majority of the client types, version 8 of +the client includes multiple breaking changes. +-- + +We have strived to keep the core foundation reasonably similar, but types emitted +through code-generation are subject to change between `NEST` (v7) and the new +`Elastic.Clients.Elasticsearch` (v8) package. + +[discrete] +==== Namespaces + +We have renamed the package and top-level namespace for the v8 client to +`Elastic.Clients.Elasticsearch`. All types belong to this namespace. When +necessary, to avoid potential conflicts, types are generated into suitable +sub-namespaces based on the https://github.com/elastic/elasticsearch-specification[{es} specification]. Additional `using` directives may be required to access such types +when using the {net-client}. + +Transport layer concepts have moved to the new `Elastic.Transport` NuGet package +and related types are defined under its namespace. Some configuration and low-level transport functionality may require a `using` directive for the `Elastic.Transport` +namespace. + +[discrete] +==== Type names + +Type names may have changed from previous versions. We are not listing these +explicitly due to the potentially vast number of subtle differences. +Type names will now more closely align to those used in the JSON and as documented +in the {es} documentation. + +[discrete] +==== Class members + +Types may include renamed properties based on the {es} specification, +which differ from the original `NEST` property names. The types used for properties +may also have changed due to code-generation. If you identify missing or +incorrectly-typed properties, please open https://github.com/elastic/elasticsearch-net/issues/new/choose[an issue] to alert us. + +[discrete] +==== Sealing classes + +Opinions on "sealing by default" within the .NET ecosystem tend to be quite +polarized. Microsoft seal all internal types for potential performance gains +and we see a benefit in starting with that approach for the {net-client}, +even for our public API surface. + +While it prevents inheritance and, therefore, may inhibit a few consumer scenarios, +sealing by default is intended to avoid the unexpected or invalid +extension of types that could inadvertently be broken in the future. + +[discrete] +==== Removed features + +As part of the clean-slate redesign of the new client, we have opted to remove +certain features from the v8.0 client. These are listed below: + +[discrete] +===== Attribute mappings + +In previous versions of the `NEST` client, attributes could be used to configure +the mapping behaviour and inference for user types. We have removed support for +these attributes and recommend that mapping be completed via the fluent API when +configuring client instances. `System.Text.Json` attributes may be used to rename +and ignore properties during source serialization. + +[discrete] +===== CAT APIs + +The https://www.elastic.co/guide/en/elasticsearch/reference/current/cat.html[CAT APIs] +of {es} are intended for human-readable usage and will no longer be supported +via the v8 {net-client}. + +[discrete] +===== Interface removal + +We have removed several interfaces that previously shipped as part of `NEST`. This +is a design decision to simplify the library and avoid interfaces where only a +single implementation of that interface is expected to exist, such as +`IElasticClient` in `NEST`. We have also switched to prefer abstract base classes +over interfaces across the library, as this allows us to add enhancements more +easily without introducing breaking changes for derived types. + +[discrete] +==== Missing features + +While not an exhaustive list, the following are some of the main features which +have not been re-implemented for the v8 client. +These remain on our roadmap and will be reviewed and prioritized for inclusion in +future releases. + +* Query DSL operators for combining queries. +* Scroll Helper. +* Fluent API for union types. +* `AutoMap` for field datatype inference. +* Visitor pattern support for types such as `Properties`. +* Support for `JoinField` which affects `ChildrenAggregation`. +* Conditionless queries. +* DiagnosticSources have been removed in `Elastic.Transport` to provide a clean-slate +for an improved diagnostics story. The {net-client} emits https://opentelemetry.io/[OpenTelemetry] compatible `Activity` spans which can be consumed by APM agents such as the https://www.elastic.co/guide/en/apm/agent/dotnet/current/index.html[Elastic APM Agent for .NET]. +* Documentation is a work in progress, and we will expand on the documented scenarios +in future releases. + +[discrete] +=== Reduced API surface + +In the current versions of the code-generated .NET client, we have specifically +focused on supporting commonly used endpoints. We have also skipped specific +queries and aggregations which need further work to generate code correctly. +Before migrating, please ensure that the features you are using are currently +supported. + +An up to date list of all supported and unsupported endpoints can be found on https://github.com/elastic/elasticsearch-net/issues/7890[GitHub]. + +[discrete] +=== Workarounds for missing features + +If you encounter a missing feature with the v8 client, there are several ways to temporarily work around this issue until we officially reintroduce the feature. + +`NEST` 7.17.x can continue to be used in +https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html[compatibility mode] +with {es} 8.x servers until the v8 {net-client} features +align with application requirements. + +As a last resort, the low-level client `Elastic.Transport` can be used to create any desired request by hand: + +[source,csharp] +---- +var body = """ + { + "name": "my-api-key", + "expiration": "1d", + "...": "..." + } + """; + +var response = await client.Transport.RequestAsync(HttpMethod.POST, "/_security/api_key", PostData.String(body)); +---- \ No newline at end of file From fd6150d766f7088b26216b18153ada153426053e Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:53:52 +0200 Subject: [PATCH 02/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 2e37788c017..e1e4daab937 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -14,12 +14,11 @@ a new start for the client design. It is important to review how this may affect your code and usage. -- -Mature code becomes increasingly hard to maintain over time, and -our ability to make timely releases has diminished as code complexity has increased. +Mature code becomes increasingly hard to maintain over time. Major releases allow us to simplify and better align our language clients with -each other in terms of design. Here, it is crucial to find the right balance +each other in terms of design. It is crucial to find the right balance between uniformity across programming languages and the idiomatic concerns of -each language. For .NET, we will typically compare and contrast with https://github.com/elastic/elasticsearch-java[Java] and https://github.com/elastic/go-elasticsearch[Go] +each language. For .NET, we typically compare and contrast with https://github.com/elastic/elasticsearch-java[Java] and https://github.com/elastic/go-elasticsearch[Go] to make sure that our approach is equivalent for each of these. We also take heavy inspiration from Microsoft framework design guidelines and the conventions of the wider .NET community. From 9bd1900f65ce93bb4c1115727f4703666ee003c5 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:54:10 +0200 Subject: [PATCH 03/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index e1e4daab937..9a7bea1ad4e 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -27,9 +27,9 @@ of the wider .NET community. ==== New Elastic.Clients.Elasticsearch NuGet package We have shipped the new code-generated client as a -https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/[new NuGet package] +https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/[NuGet package] with a new root namespace, `Elastic.Clients.Elasticsearch`. -The new v8 client is built upon the foundations of the v7 `NEST` client, but there +The v8 client is built upon the foundations of the v7 `NEST` client, but there are changes. By shipping as a new package, the expectation is that migration can be managed with a phased approach. From 89e576a711724e000a1f3e734c717f9d422c7f7e Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:54:28 +0200 Subject: [PATCH 04/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 9a7bea1ad4e..b4ec6de3fff 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -51,7 +51,7 @@ high-level client. -- If a feature you depend on is missing (and not explicitly documented below as a -feature that we do not plan to reintroduce), please open https://github.com/elastic/elasticsearch-net/issues/new/choose[an issue] +feature that we do not plan to reintroduce), open https://github.com/elastic/elasticsearch-net/issues/new/choose[an issue] or comment on a relevant existing issue to highlight your need to us. This will help us prioritise our roadmap. From d39a6cf34dde88ac1fc13f1ab48f038910df3ff9 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:54:45 +0200 Subject: [PATCH 05/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index b4ec6de3fff..779d445484f 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -58,7 +58,7 @@ help us prioritise our roadmap. [discrete] === Code generation -Given the size of the Elasticsearch API surface today, it is no longer practical +Given the size of the {es} API surface today, it is no longer practical to maintain thousands of types (requests, responses, queries, aggregations, etc.) by hand. To ensure consistent, accurate and timely alignment between language clients and {es}, the 8.x clients, and many of the associated types are now From 8c54f81df0aecffaca03ffffd9fd770cd8818fe8 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:55:00 +0200 Subject: [PATCH 06/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 779d445484f..87502c55547 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -224,8 +224,8 @@ extension of types that could inadvertently be broken in the future. [discrete] ==== Removed features -As part of the clean-slate redesign of the new client, we have opted to remove -certain features from the v8.0 client. These are listed below: +As part of the clean-slate redesign of the new client, +certain features are removed from the v8.0 client. These are listed below: [discrete] ===== Attribute mappings From d9e0511350e6aec5faa46fa8f1ec5ff3857a933a Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:55:17 +0200 Subject: [PATCH 07/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 87502c55547..9ad77554bd1 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -60,7 +60,7 @@ help us prioritise our roadmap. Given the size of the {es} API surface today, it is no longer practical to maintain thousands of types (requests, responses, queries, aggregations, etc.) -by hand. To ensure consistent, accurate and timely alignment between language +by hand. To ensure consistent, accurate, and timely alignment between language clients and {es}, the 8.x clients, and many of the associated types are now automatically code-generated from a https://github.com/elastic/elasticsearch-specification[shared specification]. This is a common solution to maintaining alignment between client and server among SDKs and libraries, such as those for Azure, AWS and the From d5c5077d72c5a00a35182c1afaa6c9b956c53436 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:55:33 +0200 Subject: [PATCH 08/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 9ad77554bd1..72dc4891839 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -128,7 +128,7 @@ that consumers prefer introducing an abstraction for their use of the {net-clien as the prefered way to decouple consuming code from client types and support unit testing. -In order to support user testing scenarios, we have unsealed the `ElasticsearchClient` +To support user testing scenarios, we have unsealed the `ElasticsearchClient` type and made its methods virtual. This supports mocking the type directly for unit testing. This is an improvement over the original `IElasticClient` interface from `NEST` (v7) which only supported mocking of top-level client methods. From 958ec22b29e38a38b111aa7617d0bac17cdbf2f3 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:55:51 +0200 Subject: [PATCH 09/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 72dc4891839..4f8d246bd7b 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -148,7 +148,7 @@ testing against real {es} instances. [WARNING] -- The version 8 client does not currently have full-feature parity with `NEST`. The -client primary use case is for application developers communitating with {es}. +client primary use case is for application developers communicating with {es}. -- The version 8 client focuses on core endpoints, more specifically for common CRUD From 75839059b4bf8f5e25c0f00be85348770f3d9d67 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:56:22 +0200 Subject: [PATCH 10/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 4f8d246bd7b..a2eac1de368 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -152,7 +152,7 @@ client primary use case is for application developers communicating with {es}. -- The version 8 client focuses on core endpoints, more specifically for common CRUD -scenarios. We intend to reduce the feature gap in subsequent versions. We recommend reviewing this documentation carefully to learn about the missing features and reduced API surface details before migrating from the v7 `NEST` client. +scenarios. The intention is to reduce the feature gap in subsequent versions. Review this documentation carefully to learn about the missing features and reduced API surface details before migrating from the v7 `NEST` client! The choice to code-generate a new evolution of the {net-client} introduces some significant breaking changes. We consciously took the opportunity to refactor From 20e915c12f698c64f0631fa527cd5a5546b5b851 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:56:57 +0200 Subject: [PATCH 11/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index a2eac1de368..51fb5a24ec4 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -231,9 +231,9 @@ certain features are removed from the v8.0 client. These are listed below: ===== Attribute mappings In previous versions of the `NEST` client, attributes could be used to configure -the mapping behaviour and inference for user types. We have removed support for -these attributes and recommend that mapping be completed via the fluent API when -configuring client instances. `System.Text.Json` attributes may be used to rename +the mapping behaviour and inference for user types. It is recommended that +mapping be completed via the fluent API when configuring client instances. +`System.Text.Json` attributes may be used to rename and ignore properties during source serialization. [discrete] From 461b9fb33dbe554a2712dc05ca49a9ae16a5979c Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:57:35 +0200 Subject: [PATCH 12/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 51fb5a24ec4..62fdf04d554 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -246,12 +246,11 @@ via the v8 {net-client}. [discrete] ===== Interface removal -We have removed several interfaces that previously shipped as part of `NEST`. This -is a design decision to simplify the library and avoid interfaces where only a +Several interfaces are removed to simplify the library and avoid interfaces where only a single implementation of that interface is expected to exist, such as -`IElasticClient` in `NEST`. We have also switched to prefer abstract base classes -over interfaces across the library, as this allows us to add enhancements more -easily without introducing breaking changes for derived types. +`IElasticClient` in `NEST`. Abstract base classes are preferred +over interfaces across the library, as this makes it easier to add enhancements +without introducing breaking changes for derived types. [discrete] ==== Missing features From 2852e8778f76c4ee91771da65d423cf06cf3380c Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:58:05 +0200 Subject: [PATCH 13/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 62fdf04d554..4789f0509a2 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -155,9 +155,7 @@ The version 8 client focuses on core endpoints, more specifically for common CRU scenarios. The intention is to reduce the feature gap in subsequent versions. Review this documentation carefully to learn about the missing features and reduced API surface details before migrating from the v7 `NEST` client! The choice to code-generate a new evolution of the {net-client} introduces some -significant breaking changes. We consciously took the opportunity to refactor -and reconsider historic design choices as part of this major release, intending -to limit future breaking changes. +significant breaking changes. The v8 client is shipped as a new https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/[NuGet package] which can be installed alongside v7 `NEST`. We From 625e459f60e7388679938e00c56658f99b700e48 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:58:47 +0200 Subject: [PATCH 14/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 4789f0509a2..38a30ea956e 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -253,9 +253,9 @@ without introducing breaking changes for derived types. [discrete] ==== Missing features -While not an exhaustive list, the following are some of the main features which +The following are some of the main features which have not been re-implemented for the v8 client. -These remain on our roadmap and will be reviewed and prioritized for inclusion in +These might be reviewed and prioritized for inclusion in future releases. * Query DSL operators for combining queries. From 0f52c1efef419dcbc35a90cdeaac95e2ebb01918 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 17 Aug 2023 11:59:50 +0200 Subject: [PATCH 15/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 38a30ea956e..f14420b66f5 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -273,11 +273,10 @@ in future releases. [discrete] === Reduced API surface -In the current versions of the code-generated .NET client, we have specifically -focused on supporting commonly used endpoints. We have also skipped specific -queries and aggregations which need further work to generate code correctly. -Before migrating, please ensure that the features you are using are currently -supported. +In the current versions of the code-generated .NET client, supporting commonly used +endpoints is critical. Some specific queries and aggregations need further work to generate code correctly, +hence they are not included yet. +Ensure that the features you are using are currently supported before migrating. An up to date list of all supported and unsupported endpoints can be found on https://github.com/elastic/elasticsearch-net/issues/7890[GitHub]. From a4dcc8b0b1b092eb9ce732e5575339b337866c1c Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 22 Aug 2023 11:12:39 +0200 Subject: [PATCH 16/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index f14420b66f5..34019d342d5 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -1,5 +1,5 @@ [[migration-guide]] -== Migration guide NEST -> v8.* +== Migration guide: From NEST v7 to .NET Client v8 The following migration guide explains the current state of the client, missing features, breaking changes and our rationale for some of the design choices we have introduced. From 2d1577daf73f4c4164998ce064256eed0beda858 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 22 Aug 2023 11:13:26 +0200 Subject: [PATCH 17/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 34019d342d5..fd7702667c1 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -181,7 +181,7 @@ through code-generation are subject to change between `NEST` (v7) and the new [discrete] ==== Namespaces -We have renamed the package and top-level namespace for the v8 client to +The package and top-level namespace for the v8 client have been renamed to `Elastic.Clients.Elasticsearch`. All types belong to this namespace. When necessary, to avoid potential conflicts, types are generated into suitable sub-namespaces based on the https://github.com/elastic/elasticsearch-specification[{es} specification]. Additional `using` directives may be required to access such types From 3574517f378d1a9c1c951c43ee41f7e6b52a0d43 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 22 Aug 2023 11:13:45 +0200 Subject: [PATCH 18/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index fd7702667c1..1908643596f 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -158,8 +158,7 @@ The choice to code-generate a new evolution of the {net-client} introduces some significant breaking changes. The v8 client is shipped as a new https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/[NuGet package] -which can be installed alongside v7 `NEST`. We -anticipate that some consumers may prefer a phased migration with both +which can be installed alongside v7 `NEST`. Some consumers may prefer a phased migration with both packages side-by-side for a short period of time to manage complex migrations. In addition, `NEST` 7.17.x can continue to be used in https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html[compatibility mode] with {es} 8.x servers until the v8 {net-client} features From 1f24708d24ea0eaa7823ceaa427ae214204126c8 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 22 Aug 2023 11:13:53 +0200 Subject: [PATCH 19/19] Update docs/migration-guide.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/migration-guide.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc index 1908643596f..21f78589c19 100644 --- a/docs/migration-guide.asciidoc +++ b/docs/migration-guide.asciidoc @@ -193,8 +193,7 @@ namespace. [discrete] ==== Type names -Type names may have changed from previous versions. We are not listing these -explicitly due to the potentially vast number of subtle differences. +Type names may have changed from previous versions. These are not listed explicitly due to the potentially vast number of subtle differences. Type names will now more closely align to those used in the JSON and as documented in the {es} documentation.