Elasticsearch-NET 客户端安装与兼容性指南

Elasticsearch-NET 客户端安装与兼容性指南

elasticsearch-net This strongly-typed, client library enables working with Elasticsearch. It is the official client maintained and supported by Elastic. 项目地址: https://gitcode.com/gh_mirrors/el/elasticsearch-net

前言

Elasticsearch-NET 是 Elasticsearch 官方提供的 .NET 客户端库，它允许 .NET 开发者以类型安全的方式与 Elasticsearch 集群进行交互。本文将详细介绍如何安装该客户端以及其版本兼容性策略。

安装 Elasticsearch-NET 客户端

通过 .NET CLI 安装（推荐）

对于使用 SDK 风格的项目，最简单的方式是通过 .NET CLI 命令安装：

dotnet add package Elastic.Clients.Elasticsearch

这条命令会自动完成以下操作：

1. 获取最新稳定版本的客户端包
2. 将包引用添加到项目文件(.csproj)中
3. 解析并下载所有依赖项

手动添加包引用

如果你需要更精确地控制版本，可以直接编辑项目文件，添加 PackageReference：

<PackageReference Include="Elastic.Clients.Elasticsearch" Version="8.12.0" />

重要提示：版本号应替换为当前最新的稳定版本。你可以通过 NuGet 官方包源查询最新版本。

Visual Studio 安装方式

Visual Studio 用户可以通过以下两种方式安装：

1. 包管理器控制台：

Install-Package Elastic.Clients.Elasticsearch

2. NuGet 包管理器 UI：

• 右键点击项目
• 选择"管理 NuGet 包"
• 搜索"Elastic.Clients.Elasticsearch"
• 点击安装

版本兼容性详解

运行时兼容性

Elasticsearch-NET 客户端仅保证与当前维护的 .NET 运行时版本兼容。对于已结束支持的 .NET 运行时版本，不提供任何兼容性保证。

客户端与服务器兼容性策略

Elasticsearch-NET 客户端采用前向兼容策略：

1. 主版本一致时：客户端的小版本兼容其对应及更高的小版本

   • 例如：8.12 客户端兼容 8.12+ 的所有 Elasticsearch 服务器版本

2. 跨主版本时：客户端兼容下一个更高主版本的 Elasticsearch

   • 例如：9.x 客户端兼容 9.x 和 10.x 的 Elasticsearch 服务器
   • 但不兼容 8.x 服务器

兼容性矩阵示例：

| 客户端版本 | 兼容 ES 8.x | 兼容 ES 9.x | 兼容 ES 10.x | |----------|-----------|-----------|------------| | 9.x | ❌ 否 | ✅ 是 | ✅ 是 | | 8.x | ✅ 是 | ✅ 是 | ❌ 否 |

向后兼容性说明

• 小版本间：同一主版本下，客户端通常向后兼容较早的小版本（但不提供强保证）
• 主版本间：客户端绝不向后兼容较早主版本的 Elasticsearch

重要说明：兼容性不意味着功能对等。例如，8.12 客户端虽然兼容 8.13 服务器，但不支持 8.13 引入的新功能。

最佳实践建议

1. 版本选择：尽量使用客户端与服务器相同的主版本
2. 升级策略：先升级服务器，再升级客户端
3. 长期维护：关注 Elasticsearch 的支持政策，及时规划升级

后续步骤

安装完成后，下一步是配置客户端连接 Elasticsearch 集群。这包括设置集群节点地址、认证信息等连接参数。正确的连接配置是确保客户端正常工作的基础。

希望本指南能帮助你顺利开始使用 Elasticsearch-NET 客户端。如有任何兼容性问题，建议查阅官方支持政策获取最新信息。

elasticsearch-net This strongly-typed, client library enables working with Elasticsearch. It is the official client maintained and supported by Elastic. 项目地址: https://gitcode.com/gh_mirrors/el/elasticsearch-net