本文程式碼基於 CsvHelper 15.0.5
簡介
CsvHelper 是一個用於讀寫 CSV 檔案的.NET庫。極其快速,靈活且易於使用。
CsvHelper 建立在.NET Standard 2.0 之上,幾乎可以在任何地方執行。
Github 地址:https://github.com/joshclose/csvhelper
模組
模組 | 功能 |
---|---|
CsvHelper | 讀寫 CSV 資料的核心類。 |
CsvHelper.Configuration | 配置 CsvHelper 讀寫行為的類。 |
CsvHelper.Configuration.Attributes | 配置 CsvHelper 的特性。 |
CsvHelper.Expressions | 生成 LINQ 表示式的類。 |
CsvHelper.TypeConversion | 將 CSV 欄位與 .NET 型別相互轉換的類。 |
讀取
測試類
public class Foo
{
public int ID { get; set; }
public string Name { get; set; }
}
csv 檔案資料
ID,Name
1,Tom
2,Jerry
讀取所有記錄
using (var reader = new StreamReader("foo.csv"))
{
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
var records = csv.GetRecords<Foo>();
}
}
讀取 csv 檔案時,空行將被忽略,若空行中包含空格,將報錯。
如果是 Excel 編輯的 CSV 檔案,空行將會變成僅包含分隔符,
的行,也會報錯。
逐條讀取
using (var reader = new StreamReader("foo.csv"))
{
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
while (csv.Read())
{
var record = csv.GetRecord<Foo>();
}
}
}
GetRecords<T>
方法通過yield
返回一個IEnumerable<T>
,並不會將內容一次全部讀進記憶體,除非呼叫了ToList
或ToArray
方法。所以這種逐條讀取的寫法沒有太多必要。
讀取單個欄位
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
csv.Read();
csv.ReadHeader();
while (csv.Read())
{
var id = csv.GetField<int>(0);
var name = csv.GetField<string>("Name");
}
}
逐行讀取時,可以不管標題行,但是,這裡不行。
csv.Read();
這句是讀取標題,如果沒有的話,while
迴圈第一次取到的是標題,肯定會報錯。
csv.ReadHeader();
這句是給標題賦值,如果沒有的話,csv.GetField<string>("Name")
會報找不到標題。
使用 TryGetField
可以防止意外的報錯。
csv.TryGetField(0, out int id);
寫入
寫入所有記錄
var records = new List<Foo>
{
new Foo { ID = 1, Name = "Tom" },
new Foo { ID = 2, Name = "Jerry" },
};
using (var writer = new StreamWriter("foo.csv"))
{
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
csv.WriteRecords(records);
}
}
逐條寫入
using (var writer = new StreamWriter("foo.csv"))
{
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
foreach (var record in records)
{
csv.WriteRecord(record);
}
}
}
逐欄位寫入
using (var writer = new StreamWriter("foo.csv"))
{
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
csv.WriteHeader<Foo>();
csv.NextRecord();
foreach (var record in records)
{
csv.WriteField(record.ID);
csv.WriteField(record.Name);
csv.NextRecord();
}
}
}
特性
Index
Index
特性用於標記欄位順序。
在讀取檔案時,如果沒有標題,就只能通過順序來確定欄位。
public class Foo
{
[Index(0)]
public int ID { get; set; }
[Index(1)]
public string Name { get; set; }
}
using (var reader = new StreamReader("foo.csv"))
{
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
csv.Configuration.HasHeaderRecord = false;
var records = csv.GetRecords<Foo>().ToList();
}
}
csv.Configuration.HasHeaderRecord = false
配置告知CsvReader
沒有標題。必須要加這一行,否則會預設第一行為標題而跳過,導致最後的結果中少了一行。如果資料量比較多,會很難發現這個 bug。
在寫入檔案的時候,會按 Index
順序寫入。如果不想寫入標題,也需要新增 csv.Configuration.HasHeaderRecord = false;
Name
如果欄位名稱和列名不一致,可以使用 Name
屬性。
public class Foo
{
[Name("id")]
public int ID { get; set; }
[Name("name")]
public string Name { get; set; }
}
NameIndex
NameIndex
用於處理 CSV 檔案中的同名列。
public class Foo
{
...
[Name("Name")]
[NameIndex(0)]
public string FirstName { get; set; }
[Name("Name")]
[NameIndex(1)]
public string LastName { get; set; }
}
Ignore
忽略欄位
Optional
讀取時如果找不到匹配的欄位,則忽略。
public class Foo
{
...
[Optional]
public string Remarks { get; set; }
}
Default
當讀取的欄位為空時 Default
特性可為其指定預設值。
Default
特性僅在讀取時有效,寫入時是不會將空值替換為預設值寫入的。
NullValues
public class Foo
{
...
[NullValues("None", "none", "Null", "null")]
public string None { get; set; }
}
讀取檔案時,若 CSV 檔案中某欄位的值為空,那麼讀取後的值是 ""
,而非 null
,標記 NullValues
特性後,若 CSV 檔案中的某欄位值為 NullValues
指定的值,則讀取後為 null
。
若同時標記了 Default
特性,則此特性不起作用。
坑爹的是,在寫入檔案時,此特性並不起作用。因此會引起讀寫不一致的問題。
Constant
Constant
特性為欄位指定一個常量值,讀寫時都使用此值,無論指定了什麼其他對映或配置。
Format
Format
指定型別轉換時使用的字串格式。
例如數字和時間型別,我們經常會指定其格式。
public class Foo
{
...
[Format("0.00")]
public decimal Amount { get; set; }
[Format("yyyy-MM-dd HH:mm:ss")]
public DateTime JoinTime { get; set; }
}
BooleanTrueValues 和 BooleanFalseValues
這兩個特性用於將 bool 轉換成指定的形式顯示。
public class Foo
{
...
[BooleanTrueValues("yes")]
[BooleanFalseValues("no")]
public bool Vip { get; set; }
}
NumberStyles
public class Foo
{
...
[Format("X2")]
[NumberStyles(NumberStyles.HexNumber)]
public int Data { get; set; }
}
比較有用是 NumberStyles.HexNumber
和 NumberStyles.AllowHexSpecifier
,這兩個列舉的作用差不多。此特性僅在讀取時有效,寫入時並不會轉成 16 進位制寫入。這會導致讀寫不一致,可以用 Format
特性指定寫入格式。
對映
如果無法給要對映的類新增特性,在這種情況下,可以使用 ClassMap
方式進行對映。
使用對映和使用特性效果是一樣的,坑爹的地方也一樣坑爹。以下示例用屬性實現了上面特性的功能。
public class Foo2
{
public int ID { get; set; }
public string Name { get; set; }
public decimal Amount { get; set; }
public DateTime JoinTime { get; set; }
public string Msg { get; set; }
public string Msg2 { get; set; }
public bool Vip { get; set; }
public string Remarks { get; set; }
public string None { get; set; }
public int Data { get; set; }
}
public class Foo2Map : ClassMap<Foo2>
{
public Foo2Map()
{
Map(m => m.ID).Index(0).Name("id");
Map(m => m.Name).Index(1).Name("name");
Map(m => m.Amount).TypeConverterOption.Format("0.00");
Map(m => m.JoinTime).TypeConverterOption.Format("yyyy-MM-dd HH:mm:ss");
Map(m => m.Msg).Default("Hello");
Map(m => m.Msg2).Ignore();
Map(m => m.Vip)
.TypeConverterOption.BooleanValues(true, true, new string[] { "yes" })
.TypeConverterOption.BooleanValues(false, true, new string[] { "no" });
Map(m => m.Remarks).Optional();
Map(m => m.None).TypeConverterOption.NullValues("None", "none", "Null", "null");
Map(m => m.Data)
.TypeConverterOption.NumberStyles(NumberStyles.HexNumber)
.TypeConverterOption.Format("X2");
}
}
在使用對映前,需要先註冊
csv.Configuration.RegisterClassMap<Foo2Map>();
ConvertUsing
ConvertUsing
允許使用一個委託方法實現型別轉換。
// 常數
Map(m => m.Constant).ConvertUsing(row => 3);
// 把兩列聚合在一起
Map(m => m.Name).ConvertUsing(row => $"{row.GetField<string>("FirstName")} {row.GetField<string>("LastName")}");
Map(m => m.Names).ConvertUsing(row => new List<string> { row.GetField<string>("Name") } );
配置
Delimiter
分隔符
csv.Configuration.Delimiter = ",";
HasHeaderRecord
此配置前文已經提到過,是否將第一行作為標題
csv.Configuration.HasHeaderRecord = false;
IgnoreBlankLines
是否忽略空行,預設 true
csv.Configuration.IgnoreBlankLines = false;
無法忽略一個僅包含空格或 ,
的行。
AllowComments
是否允許註釋,註釋以 #
開頭。
csv.Configuration.AllowComments = true;
Comment
獲取或設定用於表示註釋掉的行的字元。預設是 #
。
csv.Configuration.Comment = '/';
BadDataFound
設定一個函式,該函式會在資料不正確時觸發,可用於記錄日誌。
IgnoreQuotes
獲取或設定一個值,該值指示在解析時是否應忽略引號並將其與其他任何字元一樣對待。
預設是 false
,如果字串中有引號,必須是 3 個 "
連在一起,讀取到的字串中才會有一個 "
,如果是 1 個則忽略,2 個則報錯。
如果為 true
,則會將 "
當做字串原樣返回。
csv.Configuration.IgnoreQuotes = true;
CsvWriter
中是沒有這個屬性的,一旦字串中包含 "
,寫出來就是 3 個 "
連在一起。
TrimOptions
去除欄位首尾空格
csv.Configuration.TrimOptions = TrimOptions.Trim;
PrepareHeaderForMatch
PrepareHeaderForMatch
定義了屬性名稱與標題進行匹配的函式。標題和屬性名稱均通過該函式執行。此功能可用於刪除標題中的空格,或者當標題和屬性名稱大小寫不一致時統一大小寫後比較。
csv.Configuration.PrepareHeaderForMatch = (string header, int index) => header.ToLower();