• 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

• 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

• 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

Fluent mapping 允许你可以最大程度地控制 POCOs 到 ES 字段的映射。你可以认为这种方式类似于 Automapper 中通过 CreateMap<T1, T2>().ForMember 来显式指定属性之间的映射。Fluent mapping 同样需要你显式指定每一个 POCO 属性跟 ES 字段的映射关系。

下面使用 Company 和 Employee 这 2 个 类来进行演示，两者之间的关系如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class Company
{
    public string Name { get; set; }
    public List<Employee> Employees { get; set; }
}

public class Employee
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Salary { get; set; }
    public DateTime Birthday { get; set; }
    public bool IsManager { get; set; }
    public List<Employee> Employees { get; set; }
    public TimeSpan Hours { get; set; }
}

• 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

• 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

• 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

使用自动映射的时候，NEST 会将 POCO 模型属性的数据类型自动推断出对应的 ES 数据类型。同样，NEST 也提供了一系列特性，方便你进行一些定制。

唯一需要注意的是，虽然使用特性进行了映射，但依然需要调用 .AutoMap() 方法，以便在特性上自定义的值生效。

示例：

在 Employee 和 Skill 类上使用特性

• 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

• 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

• 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

类似于 dynamic mapping，在创建索引或通过 Put Mapping API 创建映射时，NEST 提供了一种称为自动映射的功能，该功能可以从正在映射的 CLR POCO 属性类型自动推断出正确的 Elasticsearch 字段数据类型。

一个简单示例：

• 新建 Document 抽象基类。

• 新建 Company 类

• 新建 Employee 类

• 三者关系如下

• 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

• 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

• 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

虽然 ES 可以自动推断部分类型（如 string, bool, number）并进行映射，但无法满足在所有业务场景，显式指定模型映射至关重要。

本章节主要说明如何通过 NEST 将 .NET 中 POCOs 模型的属性跟 ES 中存储的 JSON 文档和字段进行映射。

NEST 提供了如下几种转换方式：

• Auto mapping：自动转换，根据 POCO 属性类型进行推断，见此博文：NEST 教程系列 4-1 映射：Auto mapping | 自动映射

• Attribute mapping：通过特性进行映射，见此博文：NEST 教程系列 4-2 映射：Attribute mapping | 通过特性进行映射

• Fluent mapping：流畅映射，见此博文：NEST 教程系列 4-3 映射：Fluent mapping | 流畅映射

• through the Visitor Pattern：通过 Visitor 模式进行映射，见此博文：NEST 教程系列 4-4 映射：through the Visitor Pattern | 通过访客模式进行映射

• Parent/Child relationships：子父级关系映射，，见此博文：NEST 教程系列 4-5 映射：Parent/Child relationships | 子父级关系映射

以上几种映射方式可以组合起来以形成整体映射方法。

此外，还有一些控制方法：

• Ignoring properties：忽略属性，见此博文：NEST 教程系列 4-6 映射：Ignoring properties | 映射时忽略 POCO 上的某些属性

• Multi fields：多字段，见此博文：NEST 教程系列 4-7 映射：Multi fields | 多字段映射

• 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

• 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

• 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

NEST 的默认 JSON 序列化知道如何正确的序列化所有请求和响应类型，以及如何正确处理的你的 .NET 模型类。然而有的时候，你可能需要修改默认行为或者自定义你自己的序列化器，本章节将说明如何自定义以及扩展 NEST 类型。

有时为了解决某些问题，或者因为你使用了扩展了 Elasticsearch 功能的第三方插件，需要你提供某一种类型的自定义实现，而 NEST 并没有提供现成的支持。这个时候就可以通过如下方式来扩展 NEST 的类型使得在某些场景支持：

创建你自己的属性映射

通过实现自定义的 IProperty 实现，将 POCO 属性跟 NEST 字段进行映射。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

public class MyPluginProperty : IProperty
{
    IDictionary<string, object> IProperty.LocalMetadata { get; set; }
    public string Type { get; set; } = "my_plugin_property";
    public PropertyName Name { get; set; }

    public MyPluginProperty(string name, string language)
    {
        this.Name = name;
        this.Language = language;
        this.Numeric = true;
    }

    [PropertyName("language")]
    public string Language { get; set; }

    [PropertyName("numeric")]
    public bool Numeric { get; set; }
}

• PropertyNameAttribute 特性用于标记应序列化的属性。如果没有此属性，NEST将不会选择该属性进行序列化。

在创建索引的时候使用自定义的 IProperty 实现

• 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

• 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

• 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

NEST 的默认 JSON 序列化知道如何正确的序列化所有请求和响应类型，以及如何正确处理的你的 .NET 模型类。然而有的时候，你可能需要修改默认行为或者自定义你自己的序列化器，本章节将说明如何自定义以及扩展 NEST 类型。

目前 NEST 客户端已经完全移除了 SimpleJson 和 Newtonsoft.Json，转而使用内置的 Utf8Json—一种直接与 UTF-8 二进制文件直接协同工作的快速序列化器。

随着转而使用 UtfJson，NEST 团队在 7.x 阶段删除了部分原先在之前 NEST 客户端中存在的 JSON 特性，变动如下：

• 由于性能原因，由 Utf8Json 生成的 JSON 不会缩进。如请求中的 JSON 不会缩进，哪怕指定了 SerializationFormatting.Indented。但 NEST 团队正在考虑公开缩进 JSON 的选项以便于开发和调试。

• NEST 类型不能通过继承扩展。在 6.x 版本，可以通过派生该类型并注释这些新属性来为该类型包括其他属性。在当前使用 Utf8Json 进行序列化的时候，此方法将不起作用。

• 序列化器使用 Reflection.Emit，而 Utf8Json 使用 Reflection.Emit 来生成高效的格式化器。但并非所有平台都支持 Reflection.Emit，例如 UWP，Xamarin.iOS 和 Xamarin.Android。

• Elasticsearch.Net.DynamicResponse 将 JSON 数组反序列化为 List