[C#.NET 拾遺補漏]09:數據標註與數據校驗

數據標註(Data Annotation)是類或類成員添加上下文信息的一種方式,在 C# 通常用特性(Attribute)類來描述。它的用途主要可以分為下面這三類:

  • 驗證 Validation:向數據添加驗證規則
  • 顯示 Display:指定數據如何呈現給用戶
  • 模型 Modelling:添加關於用法和與其它類的關係信息

下面是一個用來驗證和展現用戶信息的一個 Model:

class Kid
{
  [Range(0, 18)] // 年齡不能超過18歲,不能為負數
  public int Age { get; set; }

  [StringLength(MaximumLength = 50, MinimumLength = 3)] // 名稱的長度不能超過 50,不能小於 3
  public string Name { get; set; }

  [DataType(DataType.Date)] // 生日將作為日期展示 (不帶時間)
  public DateTime Birthday { get; set; }
}

數據標註的顯示用途主要在早期的 ASP.NET 和 ASP.NET MVC 等框架中使用。例如,在 ASP.NET MVC 中,Razor 引擎會根據 Model 屬性的 DataType 特性動態生成不同類型的表單元素。不過,現在這類用途除了 WPF(比如 EditableAttribute)已經過時很少用了。

數據標註用來驗證數據的合法性是最常見的用法,在 ASP.NET Core/Mvc 中,數據作為表單 Model 提交時,框架會對 Model 數據自動進行校驗,也可以手動調用 ModelState.IsValid() 來判斷數據是否合法。

自定義校驗特性

自定義一個校驗特性很簡單,創建一個繼承 ValidationAttribute 的類,然後重寫它的 IsValid 方法。示例:

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = false)]
public class EvenNumberAttribute : ValidationAttribute
{
    public override bool IsValid(object input)
    {
        if (input == null)
            return false;

        if (!int.TryParse(input.ToString(), out int val))
            return false;

        return val % 2 == 0;
    }
}

然後這個特性可以這麼用:

public class Model
{
    [EvenNumberAttribute(ErrorMessage = "數字必須是偶數")]
    public int MyNumber { get; set; }
}

除了這自定義校驗的方式,C# 還提供了一個 CustomValidation 特性,也是用來自定義數據校驗的,它是通過反射的方式來實現的。示例:

public class Model
{
    [CustomValidation(typeof(MyCustomValidation), "IsNotEvenNumber")]
    public int MyNumber { get; set; }
}

public static class MyCustomValidation
{
    public static ValidationResult IsNotEvenNumber(object input)
    {
        var result = new ValidationResult("數字必須是偶數");
        if (input == null || !int.TryParse(input.ToString(), out int val))
            return result;
        return val % 2 == 0 ? ValidationResult.Success : result;
    }
}

C# 內置了很多常用數據校驗特性類,比如最常用的 RequiredAttributeStringLengthAttributeRangeAttribute 等。

手動執行數據校驗

大多數時候,數據校驗都是由框架(如 ASP.NET Core)幫我們做了,但有時候我們想手動執行校驗數據怎麼做呢?簡單說,使用 Validator 類即可,但也不是想像的那麼直接。數據校驗需要提供檢驗的信息,比如校驗規則、需要校驗的屬性及未通過顯示的錯誤信息等,而這些需要由另一個類來從待校驗的實例中提取作為上下文,它是 ValidationContext,所以需要先創建 ValidationContext 對象:

ValidationContext vc = new ValidationContext(objectToValidate);

創建好這個上下文對象就可以對數據進行多種方式的校驗了,比如校驗對象的所有屬性:

ValidationContext vc = new ValidationContext(objectToValidate);
ICollection<ValidationResult> results = new List<ValidationResult>();
bool isValid = Validator.TryValidateObject(objectToValidate, vc, results, true);

也可以只校驗對象的指定屬性:

ValidationContext vc = new ValidationContext(objectToValidate);
ICollection<ValidationResult> results = new List<ValidationResult>();
bool isValid = Validator.TryValidatePropery(objectToValidate.PropertyToValidate, vc, results, true);

返回值 isValid 表示是否所有數據都驗證通過,驗證失敗的信息會放到 results 結果集。

看到這,我覺得手動執行校驗還是有點麻煩,創建 ValidationContext 對象這一步如果也封裝在 Validator 類的方法內,豈不是簡潔一些?