打开 VS.NET 2013 或更高版本
创建一个示例 VS.NET（.NET Framework 4.5 / .NET core 2.x）控制台应用程序项目。
根据 .NET 环境，通过包管理器控制台使用 Nuget 命令安装 **ChoETL**。
- Install-Package ChoETL.Parquet
使用 ChoETL 命名空间

让我们从查看一个包含 2 个字段的简单 Parquet 文件读取示例开始。

图 3.1 示例 Parquet 数据文件 (emp.parquet)

有许多方法可以以最少的设置开始 Parquet 文件解析。

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

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

列表 3.1.1 使用迭代器加载 Parquet 文件

foreach (dynamic rec in new ChoParquetReader("emp.parquet"))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

示例 Fiddle：https://dotnetfiddle.net/4dJk4G

列表 3.1.2 使用循环加载 Parquet 文件

var reader = new ChoParquetReader("emp.parquet");
dynamic rec;
 
while ((rec = reader.Read()) != null)
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

示例 Fiddle：https://dotnetfiddle.net/XAtppL

3.2. 代码优先方法

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

清单 3.2.1 简单的 POCO 实体类

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

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

列表 3.2.2 加载 Parquet 文件

foreach (var rec in new ChoParquetReader<EmployeeRec>("emp.parquet"))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

示例 Fiddle：https://dotnetfiddle.net/00baoy

3.3. 配置优先方法

在此模型中，我们定义了 Parquet 配置，包含所有必需的解析参数以及与底层 Parquet 文件匹配的 Parquet 字段。

列表 3.3.1 定义 Parquet 配置

ChoParquetRecordConfiguration config = new ChoParquetRecordConfiguration();
config.ParquetRecordFieldConfigurations.Add(new ChoParquetRecordFieldConfiguration("Id"));
config.ParquetRecordFieldConfigurations.Add
       (new ChoParquetRecordFieldConfiguration("Name"));

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

列表 3.3.2 不带 POCO 对象加载 Parquet 文件

foreach (dynamic rec in new ChoParquetReader("emp.parquet", config))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

示例 Fiddle：https://dotnetfiddle.net/V5ts04

列表 3.3.3 带 POCO 对象加载 Parquet 文件

foreach (var rec in new ChoParquetReader<EmployeeRec>("emp.parquet", config))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

示例 Fiddle：https://dotnetfiddle.net/mwd0EK

3.4. 代码优先声明式配置

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

清单 3.4.1 定义 POCO 对象

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

上面的代码说明了如何定义 POCO 对象来承载输入文件中每条记录行（record line）的值。首先，为每个记录字段定义属性，并使用 ChoParquetRecordFieldAttribute 进行限定，以便与 Parquet 记录映射。ParquetPath是一个可选属性。如果未指定，框架会自动发现并从 Parquet 属性加载值。Id 被装饰了 RequiredAttribute，如果值缺失，它将抛出异常。Name 使用 DefaultValueAttribute 赋予了默认值。这意味着，如果 Name Parquet 字段在文件中包含空值，它将被默认设置为“XXXX”值。

它非常简单，可以立即提取 Parquet 数据。

清单 3.4.2 主方法

foreach (var rec in new ChoParquetReader<EmployeeRec>("emp.parquet"))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

我们首先创建一个 ChoParquetReader 对象的实例。就是这样。所有解析和将 Parquet 数据流加载到对象中的繁重工作都由底层的解析器完成。

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

4. 读取所有记录

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

列表 4.1 读取 Parquet 文件

foreach (var rec in new ChoParquetReader<EmployeeRec>("emp.parquet"))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

或

列表 4.2 读取 Parquet 文件流

foreach (var rec in new ChoParquetReader<EmployeeRec>(textReader))
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

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

清单 4.3 使用 LINQ

var list = (from o in new ChoParquetReader<EmployeeRec>("emp.parquet")
           where o.Name != null && o.Name.StartsWith("R")
           select o).ToArray();
 
foreach (var rec in list)
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

5. 手动读取记录

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

列表 5.1 读取 Parquet 文件

var reader = new ChoParquetReader<EmployeeRec>("emp.parquet");
var rec = (object)null;
 
while ((rec = reader.Read()) != null)
{
    Console.WriteLine($"Id: {rec.Id}, Name: {rec.Name}");
}

6. 自定义 Parquet 记录

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

清单 6.1 为每个记录自定义 POCO 对象

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

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

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

7. 自定义 Parquet 字段

对于每个 Parquet 字段，您可以使用 ChoParquetRecordFieldAttribute 在 POCO 实体属性中指定映射。只有当您想使用自定义 ParquetPath 来映射到该字段时，才使用此属性。

列表 7.1 为 Parquet 字段自定义 POCO 对象

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

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

FieldName - 按名称映射时，您指定要用于该属性的 Parquet 字段的名称。

7.1. 默认值

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

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

7.2. 后备值

当 Parquet 值未能设置时，用于并设置到属性的值。Fallback 值仅在 ErrorMode 为 IgnoreAndContinue 或 ReportAndContinue 时设置。

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

7.3. 类型转换器

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

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

声明式方法
配置方法

7.3.1. 声明式方法

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

列表 7.3.1.1 指定类型转换器

public class EmployeeRec
{
    [ChoParquetRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    public int Id { get; set; }
    [ChoParquetRecordField]
    [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”Parquet 属性。

7.3.2. 配置式方法

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

清单 7.3.2.2 指定类型转换器

ChoParquetRecordConfiguration config = new ChoParquetRecordConfiguration();

ChoParquetRecordFieldConfiguration idConfig = 
                new ChoParquetRecordFieldConfiguration("Id");
idConfig.AddConverter(new IntConverter());
config.ParquetRecordFieldConfigurations.Add(idConfig);

config.ParquetRecordFieldConfigurations.Add
              (new ChoParquetRecordFieldConfiguration("Name"));

在上面，我们使用 ChoParquetRecordFieldConfiguration 对象中的 AddConverter 帮助方法构造并附加 IntConverter 到“Id”字段。

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

7.4. 验证

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

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

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

在上面的示例中，我们为 Id 属性使用了 Range 验证属性。为 Name 属性使用了 Required 验证属性。当 Configuration.ObjectValidationMode 设置为 ChoObjectValidationMode.MemberLevel 或 ChoObjectValidationMode.ObjectLevel 时，ChoParquetReader 会在加载时对其进行验证。

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

static void ValidationOverridePOCOTest()
{
    ChoParquetRecordConfiguration config = new ChoParquetRecordConfiguration();
    var idConfig = new ChoParquetRecordFieldConfiguration("Id");
    idConfig.Validators = new ValidationAttribute[] { new RequiredAttribute() };
    config.ParquetRecordFieldConfigurations.Add(idConfig);
    config.ParquetRecordFieldConfigurations.Add
           (new ChoParquetRecordFieldConfiguration("Name"));
 
    using (var parser = new ChoParquetReader<EmployeeRec>("emp.parquet", config))
    {
        object rec;
        while ((rec = parser.Read()) != null)
        {
            Console.WriteLine(rec.ToStringEx());
        }
    }
}

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

列表 7.4.2 对 POCO 实体进行手动验证

[ChoParquetRecordObject]
public partial class EmployeeRec : IChoValidatable
{
    [ChoParquetRecordField(FieldName = "id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoParquetRecordField(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 - 验证对象的特定属性，如果验证未通过则抛出异常。

10. 回调机制

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

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

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

IChoReader 公开了以下事件

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

IChoNotifyRecordRead 公开了以下方法

BeforeRecordLoad - 在加载 Parquet 记录之前引发。
AfterRecordLoad - 在加载 Parquet 记录之后引发。
RecordLoadError - 在加载 Parquet 记录时出错时引发。

IChoNotifyFileRead 公开了以下方法

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

IChoNotifyRecordFieldRead 公开以下方法

BeforeRecordFieldLoad - 在加载 Parquet 字段值之前引发。
AfterRecordFieldLoad - 在加载 Parquet 字段值之后引发。
RecordFieldLoadError - 在加载 Parquet 字段值时出错时引发。

IChoNotifyRecordConfigurable 公开了以下方法：

RecondConfigure - 在 Parquet 记录配置时引发。

IChoNotifyRecordFieldConfigurable 公开了以下方法：

RecondFieldConfigure - 在每个 Parquet 记录字段配置时引发。

10.1. 使用 ChoParquetReader 事件

这是订阅回调事件并处理解析 Parquet 文件中异常情况的更直接、最简单的方法。缺点是代码不能像通过实现 IChoNotifyRecordRead 与 POCO 记录对象那样进行重用。

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

列表 10.1.1 使用 ChoParquetReader 回调事件

static void IgnoreLineTest()
{
    using (var parser = new ChoParquetReader("emp.parquet"))
    {

        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());
    }
}

同样，您也可以在 ChoParquetReader 中使用其他回调方法。

10.2. 实现 IChoNotifyRecordRead 接口

下面的示例展示了如何为直接 POCO 类实现 IChoNotifyRecordRead 接口。

清单 10.2.1 直接 POCO 回调机制实现

[ChoParquetRecordObject]
public partial class EmployeeRec : IChoNotifyRecordRead
{
    [ChoParquetRecordField(FieldName = "Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
    
    [ChoParquetRecordField(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 类。

清单 10.2 基于 MetaDataType 的回调机制实现

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

    [ChoParquetRecordField(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 来为密封类或第三方 POCO 类附加 Metadata 类。

列表 10.2.3 基于 ChoMetaDataRefType 的回调机制实现

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

    [ChoParquetRecordField(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; }
}

10.3. BeginLoad

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

列表 10.1.1 BeginLoad 回调示例

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

10.4. EndLoad

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

列表 10.2.1 EndLoad 回调示例

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

10.5. BeforeRecordLoad

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

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