CsvHelper 使用手册：从入门到精通

1. 简介

CsvHelper 是一个强大的 .NET 库，专门用于处理 CSV（逗号分隔值）文件。它提供了简单易用的 API，支持读写 CSV 文件，并具有高度的灵活性和可扩展性。无论是简单的数据导入导出，还是复杂的数据转换，CsvHelper 都能胜任。

1.1 为什么选择 CsvHelper？

• 高性能：CsvHelper 采用流式处理，内存占用低，适合处理大型 CSV 文件。
• 灵活性：支持自定义映射、类型转换、忽略字段等高级功能。
• 易用性：API 设计简洁，学习曲线平缓。

2. 安装与配置

2.1 安装 CsvHelper

可以通过 NuGet 包管理器安装 CsvHelper：

Install-Package CsvHelper

2.2 基本配置

使用 CsvHelper 前，需要创建一个 CsvReader 或 CsvWriter 实例。以下是一个简单的示例：

using (var reader = new StreamReader("data.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    var records = csv.GetRecords<MyClass>().ToList();
}

3. 读取 CSV 文件

3.1 基本读取

CsvHelper 提供了多种读取 CSV 文件的方式。以下是一个读取 CSV 文件并映射到自定义类的示例：

public class MyClass
{
    public int Id { get; set; }
    public string Name { get; set; }
}
using (var reader = new StreamReader("data.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    var records = csv.GetRecords<MyClass>().ToList();
}

3.2 自定义映射

如果 CSV 文件的列名与类的属性名不一致，可以通过自定义映射来解决：

public sealed class MyClassMap : ClassMap<MyClass>
{
    public MyClassMap()
    {
        Map(m => m.Id).Name("ID");
        Map(m => m.Name).Name("FULL_NAME");
    }
}
// 使用自定义映射
csv.Context.RegisterClassMap<MyClassMap>();

4. 写入 CSV 文件

4.1 基本写入

以下是一个将数据写入 CSV 文件的示例：

var records = new List<MyClass>
{
    new MyClass { Id = 1, Name = "Alice" },
    new MyClass { Id = 2, Name = "Bob" }
};
using (var writer = new StreamWriter("output.csv"))
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
    csv.WriteRecords(records);
}

4.2 自定义写入

可以通过配置 CsvWriter 来控制写入的格式，例如设置分隔符或忽略某些字段：

csv.Configuration.Delimiter = ";";
csv.Configuration.ShouldQuote = (field, context) => true;

5. 高级功能

5.1 类型转换

CsvHelper 支持自定义类型转换器。例如，将字符串转换为自定义枚举：

public class MyClass
{
    public Status Status { get; set; }
}
public enum Status { Active, Inactive }
// 注册类型转换器
csv.Context.TypeConverterCache.AddConverter<Status>(new EnumConverter<Status>());

5.2 异常处理

CsvHelper 提供了多种异常处理机制，例如忽略错误行或记录错误信息：

csv.Configuration.BadDataFound = context => 
{
    Console.WriteLine($"Bad data found at row {context.RawRow}: {context.RawRecord}");
};

6. 性能优化

6.1 流式处理

CsvHelper 默认使用流式处理，适合处理大型文件。避免一次性加载所有数据到内存：

using (var reader = new StreamReader("largefile.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    while (csv.Read())
    {
        var record = csv.GetRecord<MyClass>();
        // 处理单条记录
    }
}

6.2 缓存配置

对于频繁使用的配置，可以缓存 CsvConfiguration 实例以提高性能：

var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    Delimiter = ",",
    HasHeaderRecord = true
};
using (var csv = new CsvReader(reader, config))
{
    // 使用缓存的配置
}

7. 常见问题与解决方案

7.1 编码问题

如果 CSV 文件包含非 ASCII 字符，确保指定正确的编码：

using (var reader = new StreamReader("data.csv", Encoding.UTF8))

7.2 空值处理

可以通过配置控制空值的处理方式：

csv.Configuration.ShouldSkipRecord = record => record.All(string.IsNullOrEmpty);

8. 总结

CsvHelper 是一个功能强大且灵活的 CSV 处理库，适用于各种场景。通过本文的介绍，你应该已经掌握了 CsvHelper 的核心功能，包括读写 CSV 文件、自定义映射、异常处理等。希望这篇手册能帮助你更高效地处理 CSV 数据。

8.1 进一步学习

• 官方文档：https://joshclose.github.io/CsvHelper/
• GitHub 仓库：https://github.com/JoshClose/CsvHelper