« CRUD 使用示例 故障排除 »
Elastic 文档 ›Elasticsearch .NET 客户端 [8.9] ›使用 .NET 客户端

迁移指南：从 NEST v7 到 .NET 客户端 v8

编辑

迁移指南：从 NEST v7 到 .NET 客户端 v8编辑

以下迁移指南解释了客户端的当前状态、缺失的功能、重大更改以及我们对引入的一些设计选择的理由。

版本 8 是一次更新编辑

需要强调的是，Elasticsearch .NET 客户端的 v8 版本代表着客户端设计的新起点。重要的是要回顾一下这可能会如何影响您的代码和使用。

随着时间的推移，成熟的代码变得越来越难以维护。主要版本允许我们简化语言客户端，并在设计方面更好地相互协调。在编程语言的统一性和每种语言的惯用问题之间找到合适的平衡至关重要。对于 .NET，我们通常会与 Java 和 Go 进行比较和对比，以确保我们的方法对每种语言都是等效的。我们还从 Microsoft 框架设计指南和更广泛的 .NET 社区的惯例中汲取了大量灵感。

新的 Elastic.Clients.Elasticsearch NuGet 包编辑

我们已经将新的代码生成的客户端作为 NuGet 包 发布，并使用新的根命名空间 Elastic.Clients.Elasticsearch。v8 客户端建立在 v7 NEST 客户端的基础之上，但也有一些变化。通过作为新包发布，预期可以通过分阶段方法管理迁移。

虽然这是一个新的包，但我们已经将主要版本 (v8.x.x) 与支持的 Elasticsearch 服务器版本对齐，以清楚地表明客户端/服务器兼容性。v8 客户端旨在与 Elasticsearch 版本 8 一起使用。

v7 NEST 客户端将继续得到支持，但不会获得新功能或对新 Elasticsearch 端点的支持。它应该被认为已被弃用，取而代之的是新的客户端。

有限的功能集编辑

版本 8 Elasticsearch .NET 客户端与之前的 v7 NEST 高级客户端没有功能对等。

如果您依赖的功能缺失（并且在下面没有明确记录为我们不打算重新引入的功能），请打开 问题 或对相关的现有问题发表评论，以向我们强调您的需求。这将帮助我们确定路线图的优先级。

代码生成编辑

鉴于当今 Elasticsearch API 表面的规模，手动维护数千种类型（请求、响应、查询、聚合等）已不再可行。为了确保语言客户端和 Elasticsearch 之间的一致性、准确性和及时性，8.x 客户端以及许多关联类型现在都是从 共享规范 自动生成的。这是在 SDK 和库（例如 Azure、AWS 和 Google Cloud Platform 的 SDK 和库）中维护客户端和服务器之间一致性的常见解决方案。

从规范生成代码不可避免地导致现有的 v7 NEST 类型与新的 v7 Elasticsearch .NET 客户端中可用的类型之间存在一些差异。对于版本 8，我们严格按照规范生成，在某些方面进行特殊处理以提高可用性或与语言习惯用法保持一致。

诸如 Properties、Aggregations 和 Queries 等概念的基本类型层次结构不再出现在生成的代码中，因为这些任意分组与公共服务器 API 的具体概念不一致。这些考虑因素并不排除在未来版本中根据具体情况为类型添加语法糖和可用性增强功能。

Elastic.Transport编辑

.NET 客户端包含一个传输层，负责抽象 HTTP 概念并提供诸如我们的请求管道之类的功能。这支持对节点的请求进行循环负载均衡、ping 失败的节点以及嗅探集群以了解节点角色。

在 v7 中，该层作为 Elasticsearch.Net 发布，并被认为是我们的低级客户端，可用于在客户端和服务器之间发送和接收原始 JSON 字节。

作为 8.0.0 工作的一部分，我们已将传输层移至 新的专用包 和 存储库 中，名为 Elastic.Transport。这支持在未来的客户端中重复使用，并允许具有极高性能要求的消费者在此基础上构建。

用于序列化 System.Text.Json编辑

v7 NEST 高级客户端使用内部化和修改版本的 Utf8Json 进行请求和响应序列化。引入它是为了改进 Json.NET（当时更常见的 JSON 框架）的性能。

虽然 Utf8Json 提供了很好的价值，但我们已经发现了一些需要随着时间的推移进行维护的小错误和性能问题。其中一些很难在不付出更大努力的情况下进行更改。该库不再维护，任何此类更改都不能轻易地贡献回原始项目。

在 .NET Core 3.0 中，Microsoft 发布了新的 System.Text.Json API，这些 API 包含在当前版本的 .NET 中。我们已采用 System.Text.Json 进行所有序列化。如果消费者更喜欢使用不同的序列化库，他们仍然可以为其文档类型定义和注册自己的 Serializer 实现。

通过采用 System.Text.Json，我们现在依赖于 Microsoft 提供的维护良好且受支持的库。System.Text.Json 从头开始设计，支持 .NET 中最新的性能优化，因此可以提供快速且低分配的序列化。

ElasticsearchClient 的可模拟性编辑

测试代码是软件开发的重要组成部分。我们建议消费者最好为其使用 Elasticsearch .NET 客户端引入抽象，作为将使用代码与客户端类型分离并支持单元测试的首选方法。

为了支持用户测试场景，我们取消了 ElasticsearchClient 类型的密封，并将其方法设为虚拟方法。这支持直接模拟类型以进行单元测试。与 NEST (v7) 中的原始 IElasticClient 接口相比，这是一个改进，后者仅支持模拟顶级客户端方法。

我们还在 Elastic.Transport 中引入了一个 TestableResponseFactory，以便更轻松地创建具有特定状态代码和有效性的响应实例，这些实例可以在单元测试期间使用。

这些更改是对我们现有支持的补充，可以使用 InMemoryConnection、虚拟化集群以及我们的 Elastic.Elasticsearch.Managed 库对真实的 Elasticsearch 实例进行集成测试。

迁移到 Elastic.Clients.Elasticsearch编辑

版本 8 客户端目前没有与 NEST 完全相同的功能。客户端的主要用例是供应用程序开发人员与 Elasticsearch 通信。

版本 8 客户端侧重于核心端点，更具体地说是常见的 CRUD 场景。我们的目标是在后续版本中缩小功能差距。在从 v7 NEST 客户端迁移之前，请仔细阅读本文档，以了解缺失的功能和减少的 API 表面细节！

选择代码生成 Elasticsearch .NET 客户端的新版本引入了一些重大的更改。

v8 客户端作为新的 NuGet 包 发布，可以与 v7 NEST 一起安装。一些消费者可能更喜欢在短时间内同时使用这两个包进行分阶段迁移，以管理复杂的迁移。此外，NEST 7.17.x 可以继续在与 Elasticsearch 8.x 服务器的 兼容模式 下使用，直到 v8 Elasticsearch .NET 客户端的功能与应用程序要求一致。

重大更改编辑

由于代码生成了大多数客户端类型，因此客户端的版本 8 包含多个重大更改。

我们努力保持核心基础相当相似，但通过代码生成的类型在 NEST (v7) 和新的 Elastic.Clients.Elasticsearch (v8) 包之间可能会发生变化。

命名空间编辑

v8 客户端的包和顶级命名空间已重命名为 Elastic.Clients.Elasticsearch。所有类型都属于此命名空间。如有必要，为了避免潜在的冲突，会根据 Elasticsearch 规范 将类型生成到合适的子命名空间中。使用 Elasticsearch .NET 客户端时，可能需要额外的 using 指令来访问此类类型。

传输层概念已移至新的 Elastic.Transport NuGet 包，并且相关类型在其命名空间下定义。某些配置和低级传输功能可能需要 Elastic.Transport 命名空间的 using 指令。

类型名称编辑

类型名称可能已从先前版本更改。由于潜在的大量细微差异，这些不会明确列出。类型名称现在将更接近于 JSON 中使用的名称以及 Elasticsearch 文档中记录的名称。

类成员编辑

类型可能包含根据 Elasticsearch 规范重命名的属性，这些属性与原始的 NEST 属性名称不同。由于代码生成，用于属性的类型也可能已更改。如果您发现缺少或类型错误的属性，请打开 问题 以提醒我们。

密封类编辑

.NET 生态系统中关于“默认密封”的观点往往两极分化。Microsoft 密封所有内部类型以获得潜在的性能提升，我们发现从 Elasticsearch .NET 客户端开始采用这种方法是有益的，即使对于我们的公共 API 表面也是如此。

虽然它阻止了继承，因此可能会抑制一些消费者场景，但默认密封旨在避免意外或无效地扩展类型，这些类型将来可能会无意中被破坏。

已删除的功能编辑

作为新客户端全新设计的 一部分，v8.0 客户端中删除了某些功能。这些列在下面

属性映射编辑

在 NEST 客户端的先前版本中，属性可用于配置用户类型的映射行为和推断。建议在配置客户端实例时通过 Fluent API 完成映射。System.Text.Json 属性可用于在源序列化期间重命名和忽略属性。

CAT API编辑

Elasticsearch 的 CAT API 旨在供人类可读使用，并且 v8 Elasticsearch .NET 客户端将不再支持。

接口移除编辑

删除了几个接口以简化库并避免了预期仅存在该接口的单个实现的接口，例如 NEST 中的 IElasticClient。在整个库中，抽象基类优于接口，因为这使得添加增强功能更容易，而不会对派生类型引入重大更改。

缺少的功能编辑

以下是一些尚未为 v8 客户端重新实现的主要功能。这些可能会在未来版本中进行审查和优先排序以包含在内。

  • 用于组合查询的查询 DSL 运算符。
  • 滚动助手。
  • 联合类型的 Fluent API。
  • 用于字段数据类型推断的 AutoMap。
  • 对 Properties 等类型的访问者模式支持。
  • 对影响 ChildrenAggregation 的 JoinField 的支持。
  • 无条件查询。
  • Elastic.Transport 中已删除 DiagnosticSources，以便为改进的诊断故事提供一个干净的基础。Elasticsearch .NET 客户端发出与 OpenTelemetry 兼容的 Activity spans，这些 spans 可以由 APM 代理（例如 适用于 .NET 的 Elastic APM 代理）使用。
  • 文档正在编写过程中，我们将在未来版本中扩展记录的场景。

减少的 API 表面编辑

在当前版本的代码生成的 .NET 客户端中，支持常用端点至关重要。某些特定查询和聚合需要进一步的工作才能正确生成代码，因此尚未包含在内。在迁移之前，请确保您正在使用的功能当前受支持。

所有受支持和不受支持的端点的最新列表可以在 GitHub 上找到。

缺少功能的解决方法编辑

如果您在使用 v8 客户端时遇到缺少的功能，则有几种方法可以暂时解决此问题，直到我们正式重新引入该功能。

在 v8 Elasticsearch .NET 客户端功能与应用程序要求一致之前，NEST 7.17.x 可以继续在与 Elasticsearch 8.x 服务器的 兼容模式 下使用。

作为最后的手段，可以使用低级客户端 Elastic.Transport 手动创建任何所需的请求

var body = """
	{
	  "name": "my-api-key",
	  "expiration": "1d",
	  "...": "..."
	}
	""";

var response = await client.Transport.RequestAsync<StringResponse>(HttpMethod.POST, "/_security/api_key", PostData.String(body));
« CRUD 使用示例 故障排除 »