Magicodes.IE之匯入學生資料教程
阿新 • • 發佈：2019-11-29
基礎教程之匯入學生資料
說明
本教程主要說明如果使用Magicodes.IE.Excel完成學生資料的Excel匯入。
要點
- 本教程使用Magicodes.IE.Excel來完成Excel資料匯入
- 需要通過建立Dto來完成匯入
- Magicodes.IE.Excel可以根據Dto以及特性設定來自動生成匯入的Excel模板，資料驗證（包括重複驗證），模板驗證，讀取設定，值約束和對映，輸出Excel驗證標註
主要步驟
1.安裝包Magicodes.IE.Excel
在本篇教程中，我們僅演示使用Excel來完成學生資料的匯入。我們需要在已準備好的工程中安裝以下包，參考命令如下所示：
Install-Package Magicodes.IE.Excel
2.建立匯入Dto
主要程式碼如下所示：
-
學生資料Dto
/// <summary> /// 匯入學生資料Dto /// IsLabelingError：是否標註資料錯誤 /// </summary> [ExcelImporter(IsLabelingError = true)] public class ImportStudentDto { /// <summary> /// 序號 /// </summary> [ImporterHeader(Name = "序號")] public long SerialNumber { get; set; } /// <summary> /// 學籍號 /// </summary> [ImporterHeader(Name = "學籍號")] [MaxLength(30, ErrorMessage = "學籍號字數超出最大限制,請修改!")] public string StudentCode { get; set; } /// <summary> /// 姓名 /// </summary> [ImporterHeader(Name = "姓名")] [Required(ErrorMessage = "學生姓名不能為空")] [MaxLength(50, ErrorMessage = "名稱字數超出最大限制,請修改!")] public string Name { get; set; } /// <summary> /// 身份證號碼 /// </summary> [ImporterHeader(Name = "身份證號", IsAllowRepeat = false)] [Required(ErrorMessage = "身份證號不能為空")] [MaxLength(18, ErrorMessage = "身份證字數超出最大限制,請修改!")] public string IdCard { get; set; } /// <summary> /// 性別 /// </summary> [ImporterHeader(Name = "性別")] [Required(ErrorMessage = "性別不能為空")] [ValueMapping("男", 0)] [ValueMapping("女", 1)] public Genders Gender { get; set; } /// <summary> /// 家庭地址 /// </summary> [ImporterHeader(Name = "家庭住址")] [Required(ErrorMessage = "家庭地址不能為空")] [MaxLength(200, ErrorMessage = "家庭地址字數超出最大限制,請修改!")] public string Address { get; set; } /// <summary> /// 家長姓名 /// </summary> [ImporterHeader(Name = "家長姓名")] [Required(ErrorMessage = "家長姓名不能為空")] [MaxLength(50, ErrorMessage = "家長姓名數超出最大限制,請修改!")] public string Guardian { get; set; } /// <summary> /// 家長聯絡電話 /// </summary> [ImporterHeader(Name = "家長聯絡電話")] [MaxLength(20, ErrorMessage = "家長聯絡電話字數超出最大限制,請修改!")] public string GuardianPhone { get; set; } /// <summary> /// 學號 /// </summary> [ImporterHeader(Name = "學號")] [MaxLength(30, ErrorMessage = "學號字數超出最大限制,請修改!")] public string StudentNub { get; set; } /// <summary> /// 宿舍號 /// </summary> [ImporterHeader(Name = "宿舍號")] [MaxLength(20, ErrorMessage = "宿舍號字數超出最大限制,請修改!")] public string DormitoryNo { get; set; } /// <summary> /// QQ /// </summary> [ImporterHeader(Name = "QQ號")] [MaxLength(30, ErrorMessage = "QQ號字數超出最大限制,請修改!")] public string QQ { get; set; } /// <summary> /// 民族 /// </summary> [ImporterHeader(Name = "民族")] [MaxLength(2, ErrorMessage = "民族字數超出最大限制,請修改!")] public string Nation { get; set; } /// <summary> /// 戶口性質 /// </summary> [ImporterHeader(Name = "戶口性質")] [MaxLength(10, ErrorMessage = "戶口性質字數超出最大限制,請修改!")] public string HouseholdType { get; set; } /// <summary> /// 聯絡電話 /// </summary> [ImporterHeader(Name = "學生聯絡電話")] [MaxLength(20, ErrorMessage = "手機號碼字數超出最大限制,請修改!")] public string Phone { get; set; } /// <summary> /// 狀態 /// 測試可為空的列舉型別 /// </summary> [ImporterHeader(Name = "狀態")] public StudentStatus? Status { get; set; } /// <summary> /// 備註 /// </summary> [ImporterHeader(Name = "備註")] [MaxLength(200, ErrorMessage = "備註字數超出最大限制,請修改!")] public string Remark { get; set; } /// <summary> /// 是否住校(宿舍) /// </summary> [ImporterHeader(IsIgnore = true)] public bool? IsBoarding { get; set; } /// <summary> /// 所屬班級id /// </summary> [ImporterHeader(IsIgnore = true)] public Guid ClassId { get; set; } /// <summary> /// 學校Id /// </summary> [ImporterHeader(IsIgnore = true)] public Guid? SchoolId { get; set; } /// <summary> /// 校區Id /// </summary> [ImporterHeader(IsIgnore = true)] public Guid? CampusId { get; set; } /// <summary> /// 專業Id /// </summary> [ImporterHeader(IsIgnore = true)] public Guid? MajorsId { get; set; } /// <summary> /// 年級Id /// </summary> [ImporterHeader(IsIgnore = true)] public Guid? GradeId { get; set; } }如上述程式碼所示，我們定義了以上學生資料Dto，主要注意事項如下：
- ExcelImporter特性可以設定一些匯入的全域性設定，比如是否標註錯誤、匯入Sheet名稱（如不設定則自動獲取第一個）、截止讀取的列數、表頭位置。
- 支援常用的資料驗證設定，比如必填、最大長度。
- 支援資料重複校驗，比如身份證號碼。見ImporterHeader特性的IsAllowRepeat設定。
- 支援列頭設定，將ImporterHeader的Name屬性。除此之外，ImporterHeader還支援自動過濾空格（預設啟用）、處理掉所有的空格、列索引等。
- 對資料列啟用了忽略設定，見SchoolId的"[ImporterHeader(IsIgnore = true)]"。
- 使用了值對映，見“Gender”屬性。啟用值對映之後，將不會從列舉定義中獲取值對映。
- 支援列舉，支援從列舉的Display、Description特性中獲取值對映。列舉定義見下文。
-
性別列舉
定義如下所示：
/// <summary> /// 性別 /// </summary> public enum Genders { /// <summary> /// 男 /// </summary> Man = 0, /// <summary> /// 女 /// </summary> Female = 1 }注意上文中的第7點。
- 學生狀態列舉
/// <summary>
/// 學生狀態 正常、流失、休學、勤工儉學、頂崗實習、畢業、參軍
/// </summary>
public enum StudentStatus
{
/// <summary>
/// 正常
/// </summary>
[Display(Name = "正常")] Normal = 0,
/// <summary>
/// 流失
/// </summary>
[Description("流水")] PupilsAway = 1,
/// <summary>
/// 休學
/// </summary>
[Display(Name = "休學")] Suspension = 2,
/// <summary>
/// 勤工儉學
/// </summary>
[Display(Name = "勤工儉學")] WorkStudy = 3,
/// <summary>
/// 頂崗實習
/// </summary>
[Display(Name = "頂崗實習")] PostPractice = 4,
/// <summary>
/// 畢業
/// </summary>
[Display(Name = "畢業")] Graduation = 5,
/// <summary>
/// 參軍
/// </summary>
[Display(Name = "參軍")] JoinTheArmy = 6
}
注意上文中的第7點。
3.生成匯入模板並填充資料
匯入之前是不是得準備一份模板？對於我們，手寫模板？這是不存在的。Magicodes.IE.Excel封裝了根據DTO自動生成Excel匯入模板的方法，我們可以直接呼叫。這裡我們來看下匯入的相關方法：
/// <summary>
/// 匯入
/// </summary>
public interface IImporter
{
/// <summary>
/// 生成Excel匯入模板
/// </summary>
/// <typeparam name="T"></typeparam>
/// <returns></returns>
Task<TemplateFileInfo> GenerateTemplate<T>(string fileName) where T : class, new();
/// <summary>
/// 生成Excel匯入模板
/// </summary>
/// <typeparam name="T"></typeparam>
/// <returns>二進位制位元組</returns>
Task<byte[]> GenerateTemplateBytes<T>() where T : class, new();
/// <summary>
/// 匯入模型驗證資料
/// </summary>
/// <typeparam name="T"></typeparam>
/// <param name="filePath"></param>
/// <returns></returns>
Task<ImportResult<T>> Import<T>(string filePath) where T : class, new();
}
通過以上方法中的GenerateTemplate，我們可以得到需要的匯入模板。具體使用可以參考以下單元測試：
public IImporter Importer = new ExcelImporter();
[Fact(DisplayName = "生成學生資料匯入模板（測試列舉生成模板）")]
public async Task GenerateStudentImportTemplate_Test()
{
var filePath = Path.Combine(Directory.GetCurrentDirectory(),
nameof(GenerateStudentImportTemplate_Test) + ".xlsx");
if (File.Exists(filePath)) File.Delete(filePath);
var result = await Importer.GenerateTemplate<ImportStudentDto>(filePath);
result.ShouldNotBeNull();
File.Exists(filePath).ShouldBeTrue();
//TODO:讀取Excel檢查表頭和格式
}
以上DTO獲取模板並填充資料後如下圖所示：
注意：列舉會自動生成下拉選擇，必填項列頭會標紅。
4.獲取學生匯入驗證錯誤和資料
根據模板填充資料後，我們就可以進行資料匯入了。通常情況下，我們有以下步驟：
-
驗證匯入資料
通過Magicodes.IE.Excel匯入資料會自動進行驗證，並且輸出驗證結果，以便於前臺顯示。具體我們可以通過其匯入的結果類來了解：
/// <summary> /// 匯入結果 /// </summary> public class ImportResult<T> where T : class { /// <summary> /// </summary> public ImportResult() { RowErrors = new List<DataRowErrorInfo>(); } /// <summary> /// 匯入資料 /// </summary> public virtual ICollection<T> Data { get; set; } /// <summary> /// 驗證錯誤 /// </summary> public virtual IList<DataRowErrorInfo> RowErrors { get; set; } /// <summary> /// 模板錯誤 /// </summary> public virtual IList<TemplateErrorInfo> TemplateErrors { get; set; } /// <summary> /// 匯入異常資訊 /// </summary> public virtual Exception Exception { get; set; } /// <summary> /// 是否存在匯入錯誤 /// </summary> public virtual bool HasError => Exception != null || (TemplateErrors?.Count(p => p.ErrorLevel == ErrorLevels.Error) ?? 0) > 0 || (RowErrors?.Count ?? 0) > 0; }其中，
-
Data為資料結果
-
RowErrors為驗證錯誤，比如必填、重複驗證、文字長度等等。會給出行號、欄位以及欄位錯誤集合
-
TemplateErrors為模板錯誤，比如必填列缺失等錯誤資訊。支援錯誤等級（警告、錯誤）
-
Exception為匯入異常資訊
-
HasError為是否存在錯誤（不包含警告）
通過ImportResult，我們就可以很方便的拿到匯入驗證錯誤而無須額外編寫程式碼。通常在匯入時我們需要判斷HasError屬性並給前臺返回具體的錯誤結果。
資料匯入參考程式碼如下所示：
[Fact(DisplayName = "學生基礎資料匯入")] public async Task StudentInfoImporter_Test() { var filePath = Path.Combine(Directory.GetCurrentDirectory(), "TestFiles", "Import", "學生基礎資料匯入.xlsx"); var import = await Importer.Import<ImportStudentDto>(filePath); import.ShouldNotBeNull(); if (import.Exception != null) _testOutputHelper.WriteLine(import.Exception.ToString()); if (import.RowErrors.Count > 0) _testOutputHelper.WriteLine(JsonConvert.SerializeObject(import.RowErrors)); import.HasError.ShouldBeFalse(); import.Data.ShouldNotBeNull(); import.Data.Count.ShouldBe(16); } -
- 獲取驗證標註
客戶說雖然你提示了，但是我還是不知道哪裡錯了！！怎麼辦？！！
我們貼心的為你準備了匯入資料的Excel檔案的標註：
如何開啟這個【史詩劇情】呢？僅需：
[ExcelImporter(IsLabelingError = true)]
開啟後，我們將自動儲存“{目標檔名稱}_.xlsx”的標註檔案到目標位置。
- 獲取匯入資料
沒有錯誤了？也就是HasError為false，那麼我們就可以直接拿到Data為所欲為了！
最後
整個學生資料的匯入教程就此結束了。相關庫會一直更新，在功能體驗上有可能會和本文教程有細微的出入，請以相關具體程式碼、版本日誌、單元測試示例為