打开 VS.NET 2017 或更高版本
创建一个示例 VS.NET（.NET Framework 4.5 / .NET Core 2.x）控制台应用程序项目
通过 .NET 环境下的 Nuget 命令，在程序包管理器控制台中使用 Nuget 安装 ChoETL
- Install-Package ChoETL.Yaml
使用 ChoETL 命名空间

让我们从一个读取包含三个字段的简单 YAML 文件的示例开始。

图 3.1 示例 YAML 数据文件 (emp.yaml)

emps:
    - id: 1
      name: Tom

    - id: 2
      name: Mark

有多种方法可以开始解析 YAML 文件，只需最少的设置。

3.1. 快速加载 - 数据优先方法

这是 零配置、快速加载 YAML 文件的方式。不需要 POCO 对象。下面的示例代码显示了如何加载文件。

图 3.1.1 使用迭代器加载 YAML 文件

foreach (dynamic e in new ChoYamlReader("emp.yaml")
                .WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

图 3.1.2 使用循环加载 YAML 文件

var reader = new ChoYamlReader("emp.yaml").WithYamlPath("$.emps[*]");
dynamic rec;
 
while ((rec = reader.Read()) != null)
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

3.2. 代码优先方法

这是另一种 零配置 的方法，使用 POCO 类解析和加载 YAML 文件。首先，定义一个简单的数据类来匹配底层 YAML 文件的布局。

图 3.2.1 简单的 POCO 实体类

public partial class EmployeeRec
{
    public int Id { get; set; }
    public string Name { get; set; } 
}

在上面，该类定义了两个属性，与示例 Yaml 文件模板匹配。

图 3.2.2 加载 YAML 文件

foreach (var e in new ChoYamlReader<EmployeeRec>("emp.yaml").WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

3.3. 配置优先方法

在此模型中，我们使用所有必要的解析参数以及与底层 YAML 文件匹配的 yaml 字段来定义 YAML 配置。

图 3.3.1 定义 YAML 配置

ChoYamlRecordConfiguration config = new ChoYamlRecordConfiguration();
config.YamlRecordFieldConfigurations.Add(new ChoYamlRecordFieldConfiguration("Id"));
config.YamlRecordFieldConfigurations.Add(new ChoYamlRecordFieldConfiguration("Name"));

在上面，该类定义了两个属性，与示例 YAML 文件模板匹配。

图 3.3.2 不带 POCO 对象加载 YAML 文件

foreach (dynamic e in new ChoYamlReader("emp.yaml", config).WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

图 3.3.3 带 POCO 对象加载 YAML 文件

foreach (var e in new ChoYamlReader<EmployeeRec>
        ("emp.yaml", config).WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

3.4. 代码优先声明式配置

这是结合了定义 POCO 实体类和 YAML 配置参数（以声明方式装饰）的方法。Id 是必需字段，Name 是可选值字段，默认值为*“XXXX”*。如果 Name 不存在，则使用默认值。

清单 3.4.1 定义 POCO 对象

public class EmployeeRec
{
    [ChoYamlRecordField]
    [Required]
    public int Id
    {
        get;
        set;
    }
    [ChoYamlRecordField]
    [DefaultValue("XXXX")]
    public string Name
    {
        get;
        set;
    }
 
    public override string ToString()
    {
        return "{0}. {1}".FormatString(Id, Name);
    }
}

上面的代码说明了如何定义 POCO 对象来存储输入文件中每条记录行的值。第一项是为每个记录字段定义属性，并使用 ChoYamlRecordFieldAttribute 来限定 YAML 记录映射。YamlPath 是一个可选属性。如果未指定，框架会自动发现并从 yaml 属性加载值。Id 使用 RequiredAttribute 装饰，如果值缺失，将抛出异常。Name 使用 DefaultValueAttribute 指定默认值。这意味着如果文件中的 Name yaml 字段为空，它将被默认设置为“XXXX”值。

它非常简单，并且可以立即提取 YAML 数据。

清单 3.4.2 主方法

foreach (var e in new ChoYamlReader<EmployeeRec>("emp.yaml").WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

我们首先创建一个 ChoYamlReader 对象的新实例。就这样。解析器在后台完成了解析和将 YAML 数据流加载到对象中的繁重工作。

默认情况下，ChoYamlReader 在加载 YAML 文件时会发现并使用默认配置参数。可以根据您的需要覆盖这些参数。以下部分将详细介绍每个配置属性。

4. 读取所有记录

这就像设置与 YAML 文件结构匹配的 POCO 对象一样简单，您可以以可枚举模式读取整个文件。这是一种延迟执行模式，但请注意在对其进行任何聚合操作时。这将把整个文件记录加载到内存中。

图 4.1 读取 YAML 文件

foreach (var e in new ChoYamlReader<EmployeeRec>("emp.yaml").WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

或

图 4.2 读取 YAML 文件流

foreach (var e in new ChoYamlReader<EmployeeRec>(textReader).WithYamlPath("$.emps[*]"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

此模型使您的代码优雅、简洁、易于阅读和维护。它还利用 LINQ 扩展方法来执行分组、连接、投影、聚合等操作。

清单 4.3 使用 LINQ

var list = (from o in new ChoYamlReader<EmployeeRec>("emp.yaml").WithYamlPath("$.emps[*]")
           where o.Name != null && o.Name.StartsWith("R")
           select o).ToArray();
 
foreach (var e in list)
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

5. 手动读取记录

这就像设置与 YAML 文件结构匹配的 POCO 对象一样简单，您可以以可枚举模式读取整个文件。

图 5.1 读取 YAML 文件

var reader = new ChoYamlReader<EmployeeRec>("emp.yaml").WithYamlPath("$.emps[*]");
var rec = (object)null;
 
while ((rec = reader.Read()) != null)
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

6. 自定义 YAML 记录

使用 ChoYamlRecordObjectAttribute，您可以以声明方式自定义 POCO 实体对象。

图 6.1 为每条记录自定义 POCO 对象

[ChoYamlRecordObject]
public class EmployeeRec
{
    [ChoYamlRecordField] 
    public int Id { get; set; }
    [ChoYamlRecordField] 
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

以下是用于自定义文件上的 YAML 加载操作的可用属性。

YamlPath - 可选。用于选择要加载的元素的 YamlPath 表达式。如果未指定，则成员值将被自动发现并加载。
CultureName - 用于读取和写入 YAML 数据的区域性名称（例如，en-US、en-GB）。
Encoding - YAML 文件的编码。
ColumnCountStrict - 此标志指示在读取预期字段丢失时是否应抛出异常。
ErrorMode - 此标志指示在读取时是否应抛出异常，并且预期的字段加载失败。这可以每隔属性覆盖。可能的值是
- IgnoreAndContinue - 忽略错误，记录将被跳过并继续处理下一条。
- ReportAndContinue - 如果 POCO 实体是 IChoNotifyRecordRead 类型，则向其报告错误
- ThrowAndStop - 抛出错误并停止执行
IgnoreFieldValueMode - 一个标志，告知读取器在读取时是否应跳过空/null 的记录。这可以每隔属性覆盖。可能的值是
- Null - 如果记录值为 null，则跳过
- DBNull - N/A
- Empty - 如果记录值为空，则跳过
- WhiteSpace - 如果记录值仅包含空格，则跳过
ObjectValidationMode - 一个标志，告知读取器关于记录对象要执行的验证类型。可能的值是
- Off - 不执行对象验证（默认）
- MemberLevel - 在加载每个 YAML 属性的值时执行的验证。
- ObjectLevel - 在所有属性加载到 POCO 对象后执行验证

7. 自定义 YAML 字段

对于每个 yaml 字段，您可以使用 ChoYamlRecordFieldAttribute 在 POCO 实体属性中指定映射。仅当您想使用自定义 YamlPath 映射到此字段时，才使用此属性。

图 7.1 为 YAML 字段自定义 POCO 对象

public class EmployeeRec
{
    [ChoYamlRecordField]
    public int Id { get; set; }
    [ChoYamlRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

以下是您可以为每个属性添加自定义的可用成员

YamlPath - 可选。YamlPath 表达式使用路径表示法来寻址 YAML 文档的各个部分。如果未指定，ChoYamlReader 将自动发现并从匹配字段名称的 YAML 对象加载值。

7.1. 默认值

当 yaml 值为空或为空白时（通过 IgnoreFieldValueMode 控制），用于设置属性的值。

可以使用 System.ComponentModel.DefaultValueAttribute 为任何 POCO 实体属性指定默认值。

7.2. 后备值

当 YAML 值设置失败时，用于设置属性的值。Fallback 值仅在 ErrorMode 为 IgnoreAndContinue 或 ReportAndContinue 时设置。

可以使用 ChoETL.ChoFallbackValueAttribute 为任何 POCO 实体属性指定回退值。

7.3. 类型转换器

大多数原始类型都会自动转换并设置到属性中。如果 yaml 字段的值无法自动转换为属性的类型，您可以指定自定义/内置 .NET 转换器来转换该值。这些可以是 IValueConverter 或 TypeConverter 转换器。

有两种方法可以为每个字段指定转换器

声明式方法
配置方法

7.3.1. 声明式方法

此模型仅适用于 POCO 实体对象。如果您有 POCO 类，您可以为每个属性指定转换器以进行必要的转换。以下示例显示了如何操作。

图 7.3.1.1 指定类型转换器

public class EmployeeRec
{
    [ChoYamlRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    public int Id { get; set; }
    [ChoYamlRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

图 7.3.1.2 IntConverter 实现

public class IntConverter : IValueConverter
{
    public object Convert(object value, Type targetType, 
                          object parameter, CultureInfo culture)
    {
        return value;
    }
 
    public object ConvertBack(object value, Type targetType, 
                              object parameter, CultureInfo culture)
    {
        return value;
    }
}

在上面的示例中，我们定义了自定义 IntConverter 类。并展示了如何将其与 'Id' YAML 属性一起使用。

7.3.2. 配置式方法

此模型适用于动态和 POCO 实体对象。这使得可以在运行时将转换器附加到每个属性。这优先于 POCO 类上的声明式转换器。

清单 7.3.2.2 指定类型转换器

ChoYamlRecordConfiguration config = new ChoYamlRecordConfiguration();

ChoYamlRecordFieldConfiguration idConfig = new ChoYamlRecordFieldConfiguration("Id");
idConfig.AddConverter(new IntConverter());
config.YamlRecordFieldConfigurations.Add(idConfig);

config.YamlRecordFieldConfigurations.Add(new ChoYamlRecordFieldConfiguration("Name"));

在上面，我们使用 ChoYamlRecordFieldConfiguration 对象中的 AddConverter 辅助方法构造并附加 IntConverter 到 'Id' 字段。

同样，如果您想从中删除任何转换器，可以使用 ChoYamlRecordFieldConfiguration 对象上的 RemoveConverter。

7.4. 验证

ChoYamlReader 利用 System.ComponentModel.DataAnnotations 和 Validation Block 验证属性来为 POCO 实体的各个字段指定验证规则。有关可用 DataAnnotations 验证属性的列表，请参阅 MSDN 网站。

图 7.4.1 在 POCO 实体中使用验证属性

[ChoYamlRecordObject]
public partial class EmployeeRec
{
    [ChoYamlRecordField(FieldName = "id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoYamlRecordField(FieldName = "Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
}

在上面的示例中，为 Id 属性使用了 Range 验证属性。为 Name 属性使用了 Required 验证属性。当 Configuration.ObjectValidationMode 设置为 ChoObjectValidationMode.MemberLevel 或 ChoObjectValidationMode.ObjectLevel 时，ChoYamlReader 会在加载期间执行验证。

有时，您可能希望覆盖 POCO 类随附的声明式验证行为，您可以使用 Cinchoo ETL 通过配置方法来实现。下面的示例展示了如何覆盖它们。

static void ValidationOverridePOCOTest()
{
    ChoYamlRecordConfiguration config = new ChoYamlRecordConfiguration();
    var idConfig = new ChoYamlRecordFieldConfiguration("Id");
    idConfig.Validators = new ValidationAttribute[] { new RequiredAttribute() };
    config.YamlRecordFieldConfigurations.Add(idConfig);
    config.YamlRecordFieldConfigurations.Add
           (new ChoYamlRecordFieldConfiguration("Name"));
 
    using (var parser = new ChoYamlReader<EmployeeRec>("emp.yaml", config))
    {
        object rec;
        while ((rec = parser.Read()) != null)
        {
            Console.WriteLine(rec.ToStringEx());
        }
    }
}

在某些情况下，您可能希望获得控制权并在 POCO 实体类中执行手动**自验证**。这可以通过继承 POCO 对象并实现 IChoValidatable 接口来实现。

图 7.4.2 在 POCO 实体上手动验证

[ChoYamlRecordObject]
public partial class EmployeeRec : IChoValidatable
{
    [ChoYamlRecordField(FieldName = "id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoYamlRecordField(FieldName = "Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool TryValidate
    (object target, ICollection<ValidationResult> validationResults)
    {
        return true;
    }
 
    public bool TryValidateFor(object target, string memberName, 
                ICollection<ValidationResult> validationResults)
    {
        return true;
    }
 
    public void Validate(object target)
    {
    }
 
    public void ValidateFor(object target, string memberName)
    {
    }
}

上面的示例展示了如何在 POCO 对象中实现自定义自验证。

IChoValidatable 接口公开了以下方法

TryValidate - 验证整个对象，如果所有验证都通过则返回 true。否则返回 false。
Validate - 验证整个对象，如果验证未通过则抛出异常。
TryValidateFor - 验证对象的特定属性，如果所有验证都通过则返回 true。否则返回 false。
ValidateFor - 验证对象的特定属性，如果验证未通过则抛出异常。

8. 回调机制

ChoYamlReader 提供行业标准的 YAML 解析功能，可满足大多数解析需求。如果解析无法满足任何需求，您可以使用 ChoYamlReader 提供的回调机制来处理这种情况。为了参与回调机制，您可以使用以下任一模型：

使用 ChoYamlReader 通过 IChoReader 接口公开的事件处理程序
继承 POCO 实体对象，实现 IChoNotifyRecordRead / IChoNotifyFileRead / IChoNotifyRecordFieldRead 接口
继承 DataAnnotation 的 MetadataType 类型对象，并继承 IChoNotifyRecordRead / IChoNotifyFileRead / IChoNotifyRecordFieldRead 接口
继承 IChoNotifyRecordFieldConfigurable / IChoNotifyRecordFieldConfigurable 配置接口

注意：从此接口方法引发的任何异常都将被忽略。

IChoReader 公开了以下事件

BeginLoad - 在 YAML 文件加载开始时调用
EndLoad - 在 YAML 文件加载结束时调用
BeforeRecordLoad - 在 YAML 记录加载之前触发
AfterRecordLoad - 在 YAML 记录加载之后触发
RecordLoadError - 在 YAML 记录加载出错时触发
BeforeRecordFieldLoad - 在 YAML 字段值加载之前触发
AfterRecordFieldLoad - 在 YAML 字段值加载之后触发
RecordFieldLoadError - 在 YAML 字段值加载出错时触发
SkipUntil - 在 YAML 解析开始之前触发，以添加自定义逻辑来跳过记录行。
DoWhile - 在 YAML 解析期间触发，您可以在其中添加自定义逻辑来停止解析。

IChoNotifyRecordRead 公开以下方法

BeforeRecordLoad - 在 YAML 记录加载之前触发
AfterRecordLoad - 在 YAML 记录加载之后触发
RecordLoadError - 在 YAML 记录加载出错时触发

IChoNotifyFileRead 公开以下方法

BeginLoad - 在 YAML 文件加载开始时调用
EndLoad - 在 YAML 文件加载结束时调用
SkipUntil - 在 YAML 解析开始之前触发，以添加自定义逻辑来跳过记录行
DoWhile - 在 YAML 解析期间触发，您可以在其中添加自定义逻辑来停止解析

IChoNotifyRecordFieldRead 公开以下方法

BeforeRecordFieldLoad - 在 yaml 字段值加载之前触发
AfterRecordFieldLoad - 在 yaml 字段值加载之后触发
RecordFieldLoadError - 在 yaml 字段值加载出错时触发

IChoNotifyRecordConfigurable 公开了以下方法

RecondConfigure - 在 YAML 记录配置时触发

IChoNotifyRecordFieldConfigurable 公开了以下方法

RecondFieldConfigure - 在每个 yaml 记录字段配置时触发

8.1. 使用 ChoYamlReader 事件

这是订阅回调事件并处理 YAML 文件解析中的特殊情况的更直接、更简单的方法。缺点是代码不像通过实现 IChoNotifyRecordRead 和 POCO 记录对象那样可重用。

下面的示例显示了如何使用 BeforeRecordLoad 回调方法来跳过以“%”字符开头的行。

图 8.1.1 使用 ChoYamlReader 回调事件

static void IgnoreLineTest()
{
    using (var parser = new ChoYamlReader("emp.yaml").WithYamlPath("$.emps[*]"))
    {
        parser.BeforeRecordLoad += (o, e) =>
        {
            if (e.Source != null)
            {
                e.Skip = !((IDictionary<string, object>)e.Source).ContainsKey("Name");
            }
        };
        foreach (var e in parser)
            Console.WriteLine(e.Dump());
    }
}

同样，您也可以使用 ChoYamlReader 的其他回调方法。

8.2. 实现 IChoNotifyRecordRead 接口

下面的示例显示了如何实现 IChoNotifyRecordRead 接口来直接处理 POCO 类。

图 8.2.1 直接 POCO 回调机制实现

[ChoYamlRecordObject]
public partial class EmployeeRec : IChoNotifyRecordRead
{
    [ChoYamlRecordField(FieldName = "Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
    
    [ChoYamlRecordField(FieldName = "Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordLoad(object target, int index, object source)
    {
        throw new NotImplementedException();
    }
 
    public bool BeforeRecordLoad(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }
 
    public bool RecordLoadError(object target, int index, object source, Exception ex)
    {
        throw new NotImplementedException();
    }
}

下面的示例展示了如何通过在 POCO 类上使用 MetadataTypeAttribute 来附加 Metadata 类。

图 8.2 MetaDataType 基于回调机制实现

[ChoYamlRecordObject]
public class EmployeeRecMeta : IChoNotifyRecordRead
{
    [ChoYamlRecordField(FieldName = "Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }

    [ChoYamlRecordField(FieldName = "Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordLoad(object target, int index, object source)
    {
        throw new NotImplementedException();
    }
 
    public bool BeforeRecordLoad(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }
 
    public bool RecordLoadError(object target, int index, object source, Exception ex)
    {
        throw new NotImplementedException();
    }
} 

[MetadataType(typeof(EmployeeRecMeta))]
public partial class EmployeeRec
{
    public int Id { get; set; }
    public string Name { get; set; }
}

下面的示例显示了如何通过在 POCO 类上使用 ChoMetadataRefTypeAttribute 来附加 Metadata 类以用于密封类或第三方 POCO 类。

图 8.2.3 ChoMetaDataRefType 基于回调机制实现

[ChoMetadataRefType(typeof(EmployeeRec))]
[ChoYamlRecordObject]
public class EmployeeRecMeta : IChoNotifyRecordRead
{
    [ChoYamlRecordField(FieldName = "id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }

    [ChoYamlRecordField(FieldName = "Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordLoad(object target, int index, object source)
    {
        throw new NotImplementedException();
    }
 
    public bool BeforeRecordLoad(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }
 
    public bool RecordLoadError(object target, int index, object source, Exception ex)
    {
        throw new NotImplementedException();
    }
} 

public partial class EmployeeRec
{
    public int Id { get; set; }    
    public string Name { get; set; }
}

8.3. BeginLoad

此回调在 YAML 文件加载的开始时调用一次。source 是 YAML 文件流对象。在这里，您可以检查流，返回 true 继续加载 YAML。返回 false 停止解析。

图 8.1.1 BeginLoad 回调示例

public bool BeginLoad(object source)
{
    StreamReader sr = source as StreamReader;
    return true;
}

8.4. EndLoad

此回调在 YAML 文件加载的结束时调用一次。source 是 YAML 文件流对象。在这里，您可以检查流，对 stream 执行任何后续步骤。

图 8.2.1 EndLoad 回调示例

public void EndLoad(object source)
{
    StreamReader sr = source as StreamReader;
}

8.5. BeforeRecordLoad

此回调在 YAML 文件中的每个 YAML 节点加载之前调用。target 是 POCO 记录对象的实例。index 是文件中的 JObject 节点索引。source 是 YAML 记录对象。在这里，您可以检查对象，并在需要时用新值覆盖它。

提示：如果您想跳过 JObject 的加载，请将 source 设置为 null。