Github: https://github.com/elastic/elasticsearch-net
官方文档: https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html
其他: Elasticsearch .net client NEST 5.x 使用总结

示例说明

本示例了解如何使用 .NET 客户端执行各种基本的Elasticsearch CRUD 操作。演示了如何通过将对象索引到 Elasticsearch、读回文档、通过 ID 检索文档或执行搜索、更新文档中的某个字段以及删除特定文档来创建文档。

创建项目

创建一个名为ES.NET.Client.Demo的Web API项目,目录结构如下
1665108538408.png

安装 .NET 客户端

  1. Install-Package Elastic.Clients.Elasticsearch -IncludePrerelease

公共部分

  1. {
  2.   "Logging": {
  3.     "LogLevel": {
  4.       "Default": "Information",
  5.       "Microsoft.AspNetCore": "Warning"
  6.     }
  7.   },
  8.   "AllowedHosts": "*",
  9.   "AppSetting": {
  10.     "SqlServerSetting": {
  11.       "Connection": "Server=192.168.3.40;Database=webdemo;User=sa;Password=longfuchu;"
  12.     },
  13.     "MysqlSetting": {
  14.       "Connection": "server=192.168.3.40;port=3306;user=root;password=123456;database=webdemo;charset=utf8;Allow Zero Datetime=true;sslmode=none;Old Guids=true;Allow User Variables=True"
  15.     },
  16.     "PostgreSqlSetting": {
  17.       "Connection": "HOST=192.168.3.40;PORT=5432;DATABASE=test_db;USER ID=postgres;PASSWORD=123456;Pooling = false"
  18.     },
  19.     "RedisSetting": {
  20.       "Connection": "192.168.3.40:6379,password=",
  21.       "Database": "test"
  22.     },
  23.     "RabbitMQSetting": {
  24.       "HostName": "localhost",
  25.       "UserName": "admin",
  26.       "Password": "admin",
  27.       "Port": 5672
  28.     },
  29.     "MongoDbSetting": {
  30.       "Connection": "mongodb://192.168.3.40:2717", ///?replicaSet=rs0
  31.       "Database": "test"
  32.     },
  33.     "KafkaSetting": {
  34.       "Servers": "kafka1:9091,kafka2:9092,kafka3:9093"
  35.     },
  36.     "ElasticSetting": {
  37.       "Uri": "http://192.168.3.40:9200",
  38.       "Fingerprint": "14:0C:36:4D:47:5F:23:23:FF:30:FD:92:9D:25:C2:1B:F5:56:61:73:56:C5:5F:45:F9:B8:E7:D5:40:BB:65:59",
  39.       "CloudId": "",
  40.       "ApiKey": "ZpNle_iRTSmSzk7iAln0DQ",
  41.       "UserName": "elastic",
  42.       "Password": "F3SXEhBp3Jysfd9OyhJX",
  43.       "IndexSetting": {
  44.         "TweetIndex": "my-tweet-index",
  45.         "BOutIndex": "mssql_blood_boutitem"
  46.       }
  47.     }
  48.   }
  49. }
  1. namespace ES.NET.Client.Demo.Models;
  3. /// <summary>
  4. /// mongodb setting
  5. /// </summary>
  6. public class AppSetting
  7. {
  8.     /// <summary>
  9.     /// SqlServerSetting
  10.     /// </summary>
  11.     public SqlServerSetting SqlServerSetting { get; set; }
  12.     /// <summary>
  13.     /// MysqlSetting
  14.     /// </summary>
  15.     public MysqlSetting MysqlSetting { get; set; }
  16.     /// <summary>
  17.     /// RedisSetting
  18.     /// </summary>
  19.     public RedisSetting RedisSetting { get; set; }
  20.     /// <summary>
  21.     /// RabbitMQSetting
  22.     /// </summary>
  23.     public RabbitMQSetting RabbitMQSetting { get; set; }
  25.     /// <summary>
  26.     /// MongoDbSetting
  27.     /// </summary>
  28.     public MongoDbSetting MongoDbSetting { get; set; }
  30.     /// <summary>
  31.     /// KafkaSetting
  32.     /// </summary>
  33.     public KafkaSetting KafkaSetting { get; set; }
  35.     /// <summary>
  36.     /// ElasticSetting
  37.     /// </summary>
  38.     public ElasticSetting ElasticSetting { get; set; }
  39. }
  40. public class RabbitMQSetting
  41. {
  42.     /// <summary>
  43.     /// HostName
  44.     /// </summary>
  45.     public string HostName { get; set; } = "localhost";
  47.     /// <summary>
  48.     /// Password
  49.     /// </summary>
  50.     public string Password { get; set; }
  52.     /// <summary>
  53.     /// Username
  54.     /// </summary>
  55.     public string UserName { get; set; }
  57.     /// <summary>
  58.     /// The port to connect on.
  59.     /// </summary>
  60.     public int Port { get; set; } = 5672;
  61. }
  62. public class RedisSetting
  63. {
  64.     /// <summary>
  65.     /// connection string
  66.     /// </summary>
  67.     public string Connection { get; set; }
  68.     /// <summary>
  69.     /// database name
  70.     /// </summary>
  71.     public string Database { get; set; }
  72. }
  73. public class MongoDbSetting
  74. {
  75.     /// <summary>
  76.     /// connection string
  77.     /// </summary>
  78.     public string Connection { get; set; }
  79.     /// <summary>
  80.     /// database name
  81.     /// </summary>
  82.     public string Database { get; set; }
  83. }
  84. public class SqlServerSetting
  85. {
  86.     /// <summary>
  87.     /// connection string
  88.     /// </summary>
  89.     public string Connection { get; set; }
  90. }
  91. public class MysqlSetting
  92. {
  93.     /// <summary>
  94.     /// connection string
  95.     /// </summary>
  96.     public string Connection { get; set; }
  97. }
  98. public class KafkaSetting
  99. {
  100.     /// <summary>
  101.     /// Servers
  102.     /// </summary>
  103.     public string Servers { get; set; }
  104. }
  106. public class ElasticSetting
  107. {
  108.     /// <summary>
  109.     /// Uri
  110.     /// </summary>
  111.     public string Uri { get; set; }
  113.     public string Fingerprint { get; set; }
  115.     public string CloudId { get; set; }
  117.     public string ApiKey { get; set; }
  119.     public string UserName { get; set; }
  121.     public string Password { get; set; }
  123.     public IndexSetting IndexSetting { get; set; }
  125. }
  127. public class IndexSetting {
  128.     public string TweetIndex { get; set; }
  129.     public string BOutIndex { get; set; }
  130. }
  1. using Microsoft.AspNetCore.Mvc;
  3. namespace ES.NET.Client.Demo.Controllers;
  5. /// <summary>
  6. /// 基础控制器
  7. /// </summary>
  8. [Route("api/[area]/[controller]/[action]")]
  9. [ApiController]
  10. public abstract class BaseController : ControllerBase
  11. {
  12. }
  1. using ES.NET.Client.Demo.Controllers;
  2. using Microsoft.AspNetCore.Mvc;
  4. namespace ES.NET.Client.Demo.Controllers.ES;
  6. /// <summary>
  7. /// 域控制器
  8. /// </summary>
  9. [Area("ES")]
  10. public abstract class AreaController : BaseController
  11. {
  12. }
  1. using ES.NET.Client.Demo.Models;
  2. using ES.NET.Client.Demo.Services;
  3. using System;
  5. var builder = WebApplication.CreateBuilder(args);
  7. // Add services to the container.
  9. builder.Services.AddControllers();
  10. builder.Services.AddEndpointsApiExplorer();
  11. builder.Services.AddSwaggerGen();
  13. var appSetting = new AppSetting();
  14. builder.Configuration.GetSection("AppSetting").Bind(appSetting);
  16. //把AppSetting实体注入到容器,方便在构造函数里使用IOptionsSnapshot<AppSetting> options
  17. builder.Services.Configure<AppSetting>(builder.Configuration.GetSection("AppSetting"));
  19. //[FromServices] ESClientConnHelp esClientConnHelp
  20. builder.Services.AddScoped<IESClientConnHelp,ESClientConnHelp>();
  22. var app = builder.Build();
  24. // Configure the HTTP request pipeline.
  25. if (app.Environment.IsDevelopment())
  26. {
  27.     app.UseSwagger();
  28.     app.UseSwaggerUI();
  29. }
  31. app.UseHttpsRedirection();
  33. app.UseAuthorization();
  35. app.MapControllers();
  37. app.Run();

初始化ESClient

  1. using Elastic.Clients.Elasticsearch;
  3. namespace ES.NET.Client.Demo.Services;
  5. public abstract class IElasticSearchHelper
  6. {
  7.     public ElasticsearchClient ESClient { get; set; }
  8. }
  1. using Elastic.Clients.Elasticsearch;
  2. using Elastic.Transport;
  3. using ES.NET.Client.Demo.Models;
  4. using Microsoft.Extensions.Options;
  6. namespace ES.NET.Client.Demo.Services;
  9. public class ElasticSearchHelper: IElasticSearchHelper
  10. {
  11.     //ES连接
  13.     /// <summary>
  14.     /// ElasticSearchConn
  15.     /// builder.Services.Configure<AppSetting>(builder.Configuration.GetSection("AppSetting"));
  16.     /// </summary>
  17.     /// <param name="options"></param>
  18.     public ElasticSearchHelper(IOptionsSnapshot<AppSetting> options)
  19.     {
  20.         if (options == null || options.Value == null)
  21.             throw new ArgumentNullException(nameof(options));
  23.         if (this.ESClient == null)
  24.         {
  25.             ElasticSetting elasticSetting = options.Value.ElasticSetting;
  26.             var settings = new ElasticsearchClientSettings(new Uri(elasticSetting.Uri))
  27.                 .CertificateFingerprint(elasticSetting.Fingerprint)
  28.                 .Authentication(new BasicAuthentication(elasticSetting.UserName, elasticSetting.Password));
  29.             //.Authentication(new ApiKey(elasticSetting.ApiKey));
  31.             this.ESClient = new ElasticsearchClient(settings);
  32.         }
  33.     }
  36. }

简单示例

新建一个实体Tweet和控制器TweetController

  1. namespace ES.NET.Client.Demo.Models;
  3. public class Tweet
  4. {
  5.     public int Id { get; set; }
  6.     public string User { get; set; }
  7.     public DateTime PostDate { get; set; }
  8.     public string Message { get; set; }
  9. }

创建索引

  1.     /// <summary>
  2.     /// 创建索引
  3.     /// </summary>
  4.     /// <param name="tweet"></param>
  5.     /// <returns></returns>
  6.     [HttpPut]
  7.     public async Task<IActionResult> IndexAsync(Tweet entity)
  8.     {
  9.         if (entity == null || entity.Id <= 0) return NoContent();
  11.         var response = await esClient.IndexAsync(entity, request => request.Index(elasticSetting.IndexSetting.TweetIndex));
  13.         if (response.IsValid)
  14.         {
  15.             Console.WriteLine($"Index document with ID {response.Id} succeeded.");
  16.         }
  18.         return Ok(response);
  19.     }

获取文档

  1.     /// <summary>
  2.     /// 获取文档
  3.     /// </summary>
  4.     /// <param name="id"></param>
  5.     /// <returns></returns>
  6.     [HttpGet]
  7.     public async Task<IActionResult> GetAsync(string id)
  8.     {
  9.         var response = await esClient.GetAsync<Tweet>(id, idx => idx.Index(elasticSetting.IndexSetting.TweetIndex));
  10.         var entity = response.Source;
  12.         return Ok(entity);
  13.     }

使用弹性搜索 JSON 响应进行 1 对 1 映射。GetResponse 原始文档被反序列化为 Tweet 类的实例，可通过属性在响应上访问。Source

搜索文档

  1.     /// <summary>
  2.     /// 搜索文档(lambda方式)
  3.     /// </summary>
  4.     /// <param name="userName"></param>
  5.     /// <returns></returns>
  6.     [HttpGet]
  7.     public async Task<IActionResult> SearchAsync(string userName)
  8.     {
  9.         var response = await esClient.SearchAsync<Tweet>(s => s
  10.                             .Index(elasticSetting.IndexSetting.TweetIndex)
  11.                             .From(0)
  12.                             .Size(10)
  13.                             .Query(q => q
  14.                                 .Term(t => t.User, userName)
  15.                             )
  16.                         );
  18.         if (response.IsValid)
  19.         {
  20.             var tweet = response.Documents.FirstOrDefault();
  21.             return Ok(tweet);
  22.         }
  23.         else
  24.         {
  25.             return NotFound();
  26.         }
  27.     }

泛型类型参数指定类，该类在反序列化响应中的命中时使用。Tweet 如果在 上配置了 索引，或者在映射此类型时配置了特定索引，则可以省略该索引。DefaultIndexElasticsearchClientSettings 针对该字段执行术语查询，搜索由用户 stevejgordon 撰写的推文。user 可通过 上的 collection 属性访问与查询匹配的文档。DocumentsSearchResponse

如果 lambda 不是您的对象，您可能更喜欢对请求使用对象初始值设定项语法

  1.     /// <summary>
  2.     /// 搜索文档(实体对象方式)
  3.     /// </summary>
  4.     /// <param name="userName"></param>
  5.     /// <returns></returns>
  6.     [HttpGet]
  7.     public async Task<IActionResult> SearchRequestAsync(string userName)
  8.     {
  9.         var request = new SearchRequest(elasticSetting.IndexSetting.TweetIndex)
  10.         {
  11.             From = 0,
  12.             Size = 10,
  13.             Query = new TermQuery("user") { Value = userName }
  14.         };
  15.         var response = await esClient.SearchAsync<Tweet>(request);
  17.         if (response.IsValid)
  18.         {
  19.             var entity = response.Documents.FirstOrDefault();
  20.             return Ok(entity);
  21.         }
  22.         else
  23.         {
  24.             return NotFound();
  25.         }
  26.     }

更新文档

  1.     /// <summary>
  2.     /// 更新文档
  3.     /// </summary>
  4.     /// <param name="entity"></param>
  5.     /// <returns></returns>
  6.     [HttpPost]
  7.     public async Task<IActionResult> UpdateAsync(Tweet entity)
  8.     {
  9.         if (entity == null || entity.Id <= 0) return NoContent();
  11.         var response = await esClient.UpdateAsync<Tweet, object>(elasticSetting.IndexSetting.TweetIndex, entity.Id.ToString(), u => u
  12.          .Doc(entity));
  14.         if (response.IsValid)
  15.         {
  16.             Console.WriteLine("Update document succeeded.");
  17.         }
  18.         return Ok(response);
  19.     }

更新现有推文实例上的属性。
在更新请求中发送更新的推文对象。

删除文档

可以通过提供要删除的文档的 ID 来删除文档。

  1.     /// <summary>
  2.     /// 删除文档
  3.     /// </summary>
  4.     /// <param name="id"></param>
  5.     /// <returns></returns>
  6.     [HttpPost]
  7.     public async Task<IActionResult> DeleteAsync(string id)
  8.     {
  9.         if (string.IsNullOrWhiteSpace(id)) return NoContent();
  11.         var response = await esClient.DeleteAsync(elasticSetting.IndexSetting.TweetIndex, id);
  13.         if (response.IsValid)
  14.         {
  15.             Console.WriteLine("Delete document succeeded.");
  16.         }
  17.         return Ok(response);
  18.     }

完整TweetController

  2. using Elastic.Clients.Elasticsearch;
  3. using Elastic.Clients.Elasticsearch.QueryDsl;
  4. using ES.NET.Client.Demo.Models;
  5. using ES.NET.Client.Demo.Services;
  6. using Microsoft.AspNetCore.Mvc;
  7. using Microsoft.Extensions.Options;
  8. using System;
  11. namespace ES.NET.Client.Demo.Controllers.ES;
  13. /// <summary>
  14. /// 测试索引控制器
  15. /// </summary>
  16. public class TweetController : AreaController
  17. {
  18.     private readonly ElasticSetting elasticSetting;
  19.     private readonly ElasticsearchClient esClient;
  21.     public TweetController(IOptionsSnapshot<AppSetting> options,IElasticSearchHelper esClientConnHelp)
  22.     {
  23.         if (options == null || options.Value == null)
  24.             throw new ArgumentNullException(nameof(options));
  26.         if(esClientConnHelp.ESClient==null)
  27.             throw new ArgumentNullException(nameof(esClientConnHelp));
  29.         elasticSetting = options.Value.ElasticSetting;
  30.         esClient = esClientConnHelp.ESClient;
  31.     }
  33.     /// <summary>
  34.     /// 创建索引
  35.     /// </summary>
  36.     /// <param name="tweet"></param>
  37.     /// <returns></returns>
  38.     [HttpPut]
  39.     public async Task<IActionResult> IndexAsync(Tweet entity)
  40.     {
  41.         if (entity == null || entity.Id <= 0) return NoContent();
  43.         var response = await esClient.IndexAsync(entity, request => request.Index(elasticSetting.IndexSetting.TweetIndex));
  45.         if (response.IsValid)
  46.         {
  47.             Console.WriteLine($"Index document with ID {response.Id} succeeded.");
  48.         }
  50.         return Ok(response);
  51.     }
  53.     /// <summary>
  54.     /// 获取文档
  55.     /// </summary>
  56.     /// <param name="id"></param>
  57.     /// <returns></returns>
  58.     [HttpGet]
  59.     public async Task<IActionResult> GetAsync(string id)
  60.     {
  61.         var response = await esClient.GetAsync<Tweet>(id, idx => idx.Index(elasticSetting.IndexSetting.TweetIndex));
  62.         var entity = response.Source;
  64.         return Ok(entity);
  65.     }
  67.     /// <summary>
  68.     /// 搜索文档(lambda方式)
  69.     /// </summary>
  70.     /// <param name="userName"></param>
  71.     /// <returns></returns>
  72.     [HttpGet]
  73.     public async Task<IActionResult> SearchAsync(string userName)
  74.     {
  75.         var response = await esClient.SearchAsync<Tweet>(s => s
  76.                             .Index(elasticSetting.IndexSetting.TweetIndex)
  77.                             .From(0)
  78.                             .Size(10)
  79.                             .Query(q => q
  80.                                 .Term(t => t.User, userName)
  81.                             )
  82.                         );
  84.         if (response.IsValid)
  85.         {
  86.             var tweet = response.Documents.FirstOrDefault();
  87.             return Ok(tweet);
  88.         }
  89.         else
  90.         {
  91.             return NotFound();
  92.         }
  93.     }
  95.     /// <summary>
  96.     /// 搜索文档(实体对象方式)
  97.     /// </summary>
  98.     /// <param name="userName"></param>
  99.     /// <returns></returns>
  100.     [HttpGet]
  101.     public async Task<IActionResult> SearchRequestAsync(string userName)
  102.     {
  103.         var request = new SearchRequest(elasticSetting.IndexSetting.TweetIndex)
  104.         {
  105.             From = 0,
  106.             Size = 10,
  107.             Query = new TermQuery("user") { Value = userName }
  108.         };
  109.         var response = await esClient.SearchAsync<Tweet>(request);
  111.         if (response.IsValid)
  112.         {
  113.             var entity = response.Documents.FirstOrDefault();
  114.             return Ok(entity);
  115.         }
  116.         else
  117.         {
  118.             return NotFound();
  119.         }
  120.     }
  122.     /// <summary>
  123.     /// 更新文档
  124.     /// </summary>
  125.     /// <param name="entity"></param>
  126.     /// <returns></returns>
  127.     [HttpPost]
  128.     public async Task<IActionResult> UpdateAsync(Tweet entity)
  129.     {
  130.         if (entity == null || entity.Id <= 0) return NoContent();
  132.         var response = await esClient.UpdateAsync<Tweet, object>(elasticSetting.IndexSetting.TweetIndex, entity.Id.ToString(), u => u
  133.          .Doc(entity));
  135.         if (response.IsValid)
  136.         {
  137.             Console.WriteLine("Update document succeeded.");
  138.         }
  139.         return Ok(response);
  140.     }
  142.     /// <summary>
  143.     /// 删除文档
  144.     /// </summary>
  145.     /// <param name="id"></param>
  146.     /// <returns></returns>
  147.     [HttpPost]
  148.     public async Task<IActionResult> DeleteAsync(string id)
  149.     {
  150.         if (string.IsNullOrWhiteSpace(id)) return NoContent();
  152.         var response = await esClient.DeleteAsync(elasticSetting.IndexSetting.TweetIndex, id);
  154.         if (response.IsValid)
  155.         {
  156.             Console.WriteLine("Delete document succeeded.");
  157.         }
  158.         return Ok(response);
  159.     }
  161. }