.NET 使用 CsvHelper 快速读取与写入 CSV 文件完整指南

在 .NET 应用程序中处理 CSV 文件是一项常见需求，无论是导入数据还是导出报告，CSV 格式凭借其简单、通用的特性备受欢迎。CsvHelper 是社区中广泛使用的一款高性能、功能丰富的开源库，专为处理 CSV 文件设计，支持类映射、动态读取、复杂格式以及低内存使用等特性。

CsvHelper 安装方式

要使用 CsvHelper，首先将其引入 .NET 项目。通过 NuGet 包管理器输入:

Install-Package CsvHelper

或在 .NET CLI 中执行:

dotnet add package CsvHelper

插件基于 .NET Standard 2.0，跨平台兼容，适用于桌面应用、Web 项目、后台服务等场景。

读取 CSV 文件的多种方式

1. 基础类映射读取

若 CSV 表头与类属性名称一致，可按如下方式读取：

using (var reader = new StreamReader("data.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    var records = csv.GetRecords<MyClass>();
    foreach (var item in records)
    {
        // 处理 item
    }
}

这一方式简单直观，序列化效果好，且 GetRecords<T>() 支持延迟枚举，内存消耗极低。

2. 自定义映射表头与属性

当 CSV 表头名称与类属性不一致时，使用 ClassMap 进行灵活映射：

public class MyClassMap : ClassMap<MyClass>
{
    public MyClassMap()
    {
        Map(m => m.Id).Name("id_column");
        Map(m => m.Name).Name("full_name");
    }
}

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

映射方式丰富，还可以按列索引映射，适用于没有表头或需要精确控制字段顺序的文件。

3. 手动逐行读取方式

想更灵活地控制读取过程、跳过表头或处理异常时，可这样写：

using (var reader = new StreamReader("data.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    csv.Read();
    csv.ReadHeader();
    while (csv.Read())
    {
        var record = csv.GetRecord<MyClass>();
        // 进一步处理
    }
}

这种方法允许你在读取过程中手动控制流程，比如校验、日志、处理异常行等。

4. 动态读取或匿名类型

如果 CSV 列结构不固定，想更灵活读取：

var records = csv.GetRecords<dynamic>();

或用匿名类型读取特定字段，满足快速探索或临时处理需求。

使用 CsvHelper 写入 CSV 文件技巧

1. 基础写入类对象列表

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

这会自动写入表头并输出所有记录，简单高效。

2. 控制输出顺序与字段名映射

通过配置 ClassMap 也可以控制写入顺序与列名：

public class MyClassMap : ClassMap<MyClass>
{
    public MyClassMap()
    {
        Map(m => m.Name).Index(0).Name("Full Name");
        Map(m => m.Id).Index(1).Name("Identifier");
    }
}

using (...)
{
    csv.Context.RegisterClassMap<MyClassMap>();
    csv.WriteHeader<MyClass>();
    csv.NextRecord();
    foreach (var rec in records)
    {
        csv.WriteRecord(rec);
        csv.NextRecord();
    }
}

手动写入让你可以添加自定义列或控制换行逻辑。

为什么选择 CsvHelper？

性能优异：按需读取，延迟加载，一次只处理一行，适合大文件。
功能全面：支持类映射、动态类型、匿名类型、索引与名称映射。
兼容性强：.NET Standard 2.0 兼容性强，跨平台稳定使用。
社区活跃：下载量巨大，使用教程与社区支持丰富实用。

不少开发者在 .NET 社区（如 r/dotnet）推荐 CsvHelper 是处理 CSV 的首选工具，它简洁且功能强大，非常适合常见的 CSV 操作需求。

小结

从安装 CsvHelper 到常见的读取和写入方法。
掌握类映射、自定义映射、手动逐行读取以及动态读取等技巧。
学会控制写入格式与字段顺序方式。
理解 CsvHelper 在性能和灵活性上的优势。

无论你是初次接触 CSV 处理，还是需要构建更复杂的数据导入导出流程，CsvHelper 都是一个方便易用又强大的工具，值得在 .NET 项目中优先考虑。