CsvHelper 简介

CsvHelper 是一个开源的 .NET 库，专门用于高效处理 CSV（Comma-Separated Values）文件。它提供了简单易用的 API，支持从 CSV 文件读取数据、将数据写入 CSV 文件，以及处理各种复杂的 CSV 格式。无论是简单的数据导出，还是复杂的数据转换，CsvHelper 都能提供强大的支持。

安装与配置

安装 CsvHelper

CsvHelper 可以通过 NuGet 包管理器轻松安装。在 Visual Studio 中，可以通过以下步骤安装：

1. 打开“解决方案资源管理器”。
2. 右键点击项目名称，选择“管理 NuGet 包”。
3. 在“浏览”选项卡中搜索“CsvHelper”。
4. 选择最新版本，点击“安装”。

或者，可以通过 .NET CLI 命令行工具安装：

dotnet add package CsvHelper

配置项目

安装完成后，需要在代码文件中引入 CsvHelper 命名空间：

using CsvHelper;
using CsvHelper.Configuration;

基本使用

读取 CSV 文件

定义数据模型

首先，需要定义一个与 CSV 文件结构对应的类。例如，假设有一个包含姓名、年龄和邮箱的 CSV 文件，可以定义如下类：

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

读取 CSV 文件

使用 CsvHelper 读取 CSV 文件非常简单。以下是一个完整的示例：

using System.Globalization;
using System.IO;
public class CsvReaderExample
{
    public static void ReadCsvFile(string filePath)
    {
        using (var reader = new StreamReader(filePath))
        using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
        {
            var records = csv.GetRecords<Person>().ToList();
            foreach (var record in records)
            {
                Console.WriteLine($"Name: {record.Name}, Age: {record.Age}, Email: {record.Email}");
            }
        }
    }
}

配置读取选项

CsvHelper 提供了丰富的配置选项，可以通过 CsvConfiguration 类进行设置。例如，可以设置分隔符、忽略空行、处理引号等：

var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    Delimiter = ";", // 设置分隔符为分号
    IgnoreBlankLines = true, // 忽略空行
    HasHeaderRecord = true // CSV 文件包含标题行
};
using (var reader = new StreamReader(filePath))
using (var csv = new CsvReader(reader, config))
{
    // 读取逻辑
}

写入 CSV 文件

写入数据到 CSV 文件

使用 CsvHelper 写入 CSV 文件同样简单。以下是一个完整的示例：

using System.Collections.Generic;
using System.Globalization;
using System.IO;
public class CsvWriterExample
{
    public static void WriteCsvFile(string filePath, List<Person> people)
    {
        using (var writer = new StreamWriter(filePath))
        using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
        {
            csv.WriteRecords(people);
        }
    }
}

配置写入选项

与读取类似，写入时也可以配置各种选项。例如，可以设置是否包含标题行、自定义分隔符等：

var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    Delimiter = ";", // 设置分隔符为分号
    ShouldQuote = args => true // 强制引号包围所有字段
};
using (var writer = new StreamWriter(filePath))
using (var csv = new CsvWriter(writer, config))
{
    csv.WriteRecords(people);
}

高级特性

自定义映射

CsvHelper 允许通过类映射（Class Map）自定义字段与属性之间的映射关系。这对于处理复杂的 CSV 结构非常有用。

定义类映射

public sealed class PersonMap : ClassMap<Person>
{
    public PersonMap()
    {
        Map(m => m.Name).Name("Full Name"); // 将 CSV 中的 "Full Name" 列映射到 Name 属性
        Map(m => m.Age).Index(1); // 通过索引映射
        Map(m => m.Email).Ignore(); // 忽略 Email 字段
    }
}

使用类映射

var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    HasHeaderRecord = true
};
using (var reader = new StreamReader(filePath))
using (var csv = new CsvReader(reader, config))
{
    csv.Context.RegisterClassMap<PersonMap>(); // 注册类映射
    var records = csv.GetRecords<Person>().ToList();
}

处理异常和错误

CsvHelper 提供了强大的错误处理机制。可以通过 CsvReader 和 CsvWriter 的 Context 属性访问错误信息。

捕获读取错误

try
{
    using (var reader = new StreamReader(filePath))
    using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
    {
        var records = csv.GetRecords<Person>().ToList();
    }
}
catch (CsvHelperException ex)
{
    Console.WriteLine($"Error reading CSV: {ex.Message}");
}

自定义错误处理

可以通过实现 IParserError 接口来自定义错误处理逻辑。

性能优化

批量读取与写入

对于大型 CSV 文件，建议使用批量读取和写入以提高性能。

批量读取

using (var reader = new StreamReader(filePath))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    while (csv.Read())
    {
        var person = new Person
        {
            Name = csv.GetField<string>("Name"),
            Age = csv.GetField<int>("Age"),
            Email = csv.GetField<string>("Email")
        };
        // 处理每条记录
    }
}

批量写入

using (var writer = new StreamWriter(filePath))
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
    csv.WriteHeader<Person>(); // 写入标题行
    csv.NextRecord(); // 移动到下一行
    foreach (var person in people)
    {
        csv.WriteField(person.Name);
        csv.WriteField(person.Age);
        csv.WriteField(person.Email);
        csv.NextRecord(); // 移动到下一行
    }
}

异步操作

CsvHelper 支持异步操作，可以通过 StreamReader 和 StreamWriter 的异步方法实现。

异步读取

public static async Task ReadCsvFileAsync(string filePath)
{
    using (var reader = new StreamReader(filePath))
    using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
    {
        await foreach (var record in csv.GetRecordsAsync<Person>())
        {
            Console.WriteLine($"Name: {record.Name}, Age: {record.Age}, Email: {record.Email}");
        }
    }
}

异步写入

public static async Task WriteCsvFileAsync(string filePath, List<Person> people)
{
    using (var writer = new StreamWriter(filePath))
    using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
    {
        await csv.WriteRecordsAsync(people);
    }
}

总结

CsvHelper 是一个功能强大且易于使用的 .NET 库，用于处理 CSV 文件。本文介绍了 CsvHelper 的基本使用、高级特性以及性能优化方法。通过合理使用 CsvHelper，可以大大简化 CSV 文件的读写操作，提高开发效率。无论是简单的数据导出，还是复杂的数据转换，CsvHelper 都能提供强大的支持。希望本文能为开发者提供有价值的参考。