validation-patterns
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseValidation Patterns in ASP.NET Core
ASP.NET Core中的验证模式
Rationale
设计初衷
Validation is critical for both security and user experience. Poor validation leads to invalid data, security vulnerabilities, and confusing error messages. These patterns provide a comprehensive approach to validation at multiple layers.
验证对于安全性和用户体验都至关重要。糟糕的验证会导致无效数据、安全漏洞以及令人困惑的错误提示。这些模式提供了多层级的全面验证方案。
Validation Strategy
验证策略
| Layer | Purpose | Technology |
|---|---|---|
| Client-Side | Immediate feedback, reduce server load | jQuery Validation, HTML5 |
| Model Binding | Data type/format validation | Model Binders |
| Application | Business rule validation | FluentValidation, DataAnnotations |
| Configuration | Startup validation | IValidateOptions<T> |
| Database | Constraint enforcement | EF Core Configurations |
| 层级 | 用途 | 技术实现 |
|---|---|---|
| 客户端 | 即时反馈,降低服务端负载 | jQuery Validation, HTML5 |
| 模型绑定 | 数据类型/格式验证 | 模型绑定器 |
| 应用层 | 业务规则验证 | FluentValidation, DataAnnotations |
| 配置层 | 启动时验证 | IValidateOptions<T> |
| 数据库层 | 约束强制校验 | EF Core 配置 |
Validation Approach Decision Tree
验证方案决策树
Choose the validation approach based on complexity:
- DataAnnotations (default) -- declarative ,
[Required],[Range],[StringLength]attributes. Best for simple property-level constraints.[RegularExpression] - -- implement
IValidatableObjectfor cross-property rules. Best for date range comparisons, conditional required fields.Validate() - Custom -- subclass
ValidationAttributefor reusable property-level rules.ValidationAttribute - -- validate configuration/options classes at startup with access to DI services.
IValidateOptions<T> - FluentValidation -- third-party library for complex, testable validation with fluent API. Best for async validators, database-dependent rules.
根据复杂度选择合适的验证方案:
- DataAnnotations(默认方案)-- 声明式的、
[Required]、[Range]、[StringLength]特性,最适合简单的属性级约束。[RegularExpression] - -- 实现
IValidatableObject方法处理跨属性规则,最适合日期范围比较、条件必填字段等场景。Validate() - 自定义-- 继承
ValidationAttribute实现可复用的属性级规则。ValidationAttribute - -- 启动时验证配置/选项类,可访问DI服务。
IValidateOptions<T> - FluentValidation -- 第三方库,通过流畅API实现复杂、可测试的验证,最适合异步验证器、依赖数据库的规则场景。
Pattern 1: DataAnnotations
模式1:DataAnnotations
The namespace provides declarative validation through attributes.
System.ComponentModel.DataAnnotationscsharp
using System.ComponentModel.DataAnnotations;
public sealed class CreateProductRequest
{
[Required(ErrorMessage = "Product name is required")]
[StringLength(200, MinimumLength = 1)]
public required string Name { get; set; }
[Range(0.01, 1_000_000, ErrorMessage = "Price must be between {1} and {2}")]
public decimal Price { get; set; }
[RegularExpression(@"^[A-Z]{2,4}-\d{4,8}$",
ErrorMessage = "SKU format: AA-0000 to AAAA-00000000")]
public string? Sku { get; set; }
[EmailAddress]
public string? ContactEmail { get; set; }
[Url]
public string? WebsiteUrl { get; set; }
[Range(0, int.MaxValue, ErrorMessage = "Quantity cannot be negative")]
public int Quantity { get; set; }
}System.ComponentModel.DataAnnotationscsharp
using System.ComponentModel.DataAnnotations;
public sealed class CreateProductRequest
{
[Required(ErrorMessage = "Product name is required")]
[StringLength(200, MinimumLength = 1)]
public required string Name { get; set; }
[Range(0.01, 1_000_000, ErrorMessage = "Price must be between {1} and {2}")]
public decimal Price { get; set; }
[RegularExpression(@"^[A-Z]{2,4}-\d{4,8}$",
ErrorMessage = "SKU format: AA-0000 to AAAA-00000000")]
public string? Sku { get; set; }
[EmailAddress]
public string? ContactEmail { get; set; }
[Url]
public string? WebsiteUrl { get; set; }
[Range(0, int.MaxValue, ErrorMessage = "Quantity cannot be negative")]
public int Quantity { get; set; }
}Attribute Reference
特性参考
| Attribute | Purpose | Example |
|---|---|---|
| Non-null, non-empty | |
| Min/max length | |
| Numeric/date range | |
| Pattern match | |
| Email format | |
| Phone format | |
| URL format | |
| Luhn check | |
| Property equality | |
| Collection/string length | |
| Value allowlist | |
| Value denylist | |
| Min and max in one | |
| Base64 format | |
| 特性 | 用途 | 示例 |
|---|---|---|
| 非空、非空值 | |
| 最小/最大长度 | |
| 数值/日期范围 | |
| 正则匹配 | |
| 邮箱格式校验 | |
| 手机号格式校验 | |
| URL格式校验 | |
| Luhn算法校验银行卡号 | |
| 属性值相等校验 | |
| 集合/字符串长度校验 | |
| 允许值白名单 | |
| 禁止值黑名单 | |
| 单特性同时配置最小最大长度 | |
| Base64格式校验 | |
Pattern 2: Custom ValidationAttribute
模式2:自定义ValidationAttribute
Create reusable validation attributes for domain-specific rules.
为领域特定规则创建可复用的验证特性。
Property-Level
属性级
csharp
[AttributeUsage(AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class FutureDateAttribute : ValidationAttribute
{
protected override ValidationResult? IsValid(
object? value, ValidationContext validationContext)
{
if (value is DateOnly date && date <= DateOnly.FromDateTime(DateTime.UtcNow))
{
return new ValidationResult(
ErrorMessage ?? "Date must be in the future",
[validationContext.MemberName!]);
}
return ValidationResult.Success;
}
}
public sealed class CreateEventRequest
{
[Required]
[StringLength(200)]
public required string Title { get; set; }
[FutureDate(ErrorMessage = "Event date must be in the future")]
public DateOnly EventDate { get; set; }
}csharp
[AttributeUsage(AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class FutureDateAttribute : ValidationAttribute
{
protected override ValidationResult? IsValid(
object? value, ValidationContext validationContext)
{
if (value is DateOnly date && date <= DateOnly.FromDateTime(DateTime.UtcNow))
{
return new ValidationResult(
ErrorMessage ?? "Date must be in the future",
[validationContext.MemberName!]);
}
return ValidationResult.Success;
}
}
public sealed class CreateEventRequest
{
[Required]
[StringLength(200)]
public required string Title { get; set; }
[FutureDate(ErrorMessage = "Event date must be in the future")]
public DateOnly EventDate { get; set; }
}Class-Level
类级
csharp
[AttributeUsage(AttributeTargets.Class)]
public sealed class DateRangeAttribute : ValidationAttribute
{
public string StartProperty { get; set; } = "StartDate";
public string EndProperty { get; set; } = "EndDate";
protected override ValidationResult? IsValid(
object? value, ValidationContext validationContext)
{
if (value is null) return ValidationResult.Success;
var type = value.GetType();
var startValue = type.GetProperty(StartProperty)?.GetValue(value);
var endValue = type.GetProperty(EndProperty)?.GetValue(value);
if (startValue is DateOnly start && endValue is DateOnly end && end < start)
{
return new ValidationResult(
ErrorMessage ?? $"{EndProperty} must be after {StartProperty}",
[EndProperty]);
}
return ValidationResult.Success;
}
}csharp
[AttributeUsage(AttributeTargets.Class)]
public sealed class DateRangeAttribute : ValidationAttribute
{
public string StartProperty { get; set; } = "StartDate";
public string EndProperty { get; set; } = "EndDate";
protected override ValidationResult? IsValid(
object? value, ValidationContext validationContext)
{
if (value is null) return ValidationResult.Success;
var type = value.GetType();
var startValue = type.GetProperty(StartProperty)?.GetValue(value);
var endValue = type.GetProperty(EndProperty)?.GetValue(value);
if (startValue is DateOnly start && endValue is DateOnly end && end < start)
{
return new ValidationResult(
ErrorMessage ?? $"{EndProperty} must be after {StartProperty}",
[EndProperty]);
}
return ValidationResult.Success;
}
}Pattern 3: IValidatableObject
模式3:IValidatableObject
Implement for cross-property validation within the model:
IValidatableObjectcsharp
public sealed class CreateOrderRequest : IValidatableObject
{
[Required]
[StringLength(50)]
public required string CustomerId { get; set; }
[Required]
public DateOnly OrderDate { get; set; }
public DateOnly? ShipByDate { get; set; }
[Required]
[MinLength(1, ErrorMessage = "At least one line item is required")]
public required List<OrderLineItem> Lines { get; set; }
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
if (ShipByDate.HasValue && ShipByDate.Value <= OrderDate)
{
yield return new ValidationResult(
"Ship-by date must be after order date",
[nameof(ShipByDate)]);
}
if (Lines.Sum(l => l.Quantity * l.UnitPrice) > 1_000_000)
{
yield return new ValidationResult(
"Total order value cannot exceed 1,000,000",
[nameof(Lines)]);
}
if (Lines.Any(l => l.RequiresShipping) && ShipByDate is null)
{
yield return new ValidationResult(
"Ship-by date is required when order contains shippable items",
[nameof(ShipByDate)]);
}
}
}When to use vs custom attribute: Use when validation logic is specific to one model. Use custom when the same rule applies across multiple models.
IValidatableObjectIValidatableObjectValidationAttribute实现接口完成模型内部的跨属性验证:
IValidatableObjectcsharp
public sealed class CreateOrderRequest : IValidatableObject
{
[Required]
[StringLength(50)]
public required string CustomerId { get; set; }
[Required]
public DateOnly OrderDate { get; set; }
public DateOnly? ShipByDate { get; set; }
[Required]
[MinLength(1, ErrorMessage = "At least one line item is required")]
public required List<OrderLineItem> Lines { get; set; }
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
if (ShipByDate.HasValue && ShipByDate.Value <= OrderDate)
{
yield return new ValidationResult(
"Ship-by date must be after order date",
[nameof(ShipByDate)]);
}
if (Lines.Sum(l => l.Quantity * l.UnitPrice) > 1_000_000)
{
yield return new ValidationResult(
"Total order value cannot exceed 1,000,000",
[nameof(Lines)]);
}
if (Lines.Any(l => l.RequiresShipping) && ShipByDate is null)
{
yield return new ValidationResult(
"Ship-by date is required when order contains shippable items",
[nameof(ShipByDate)]);
}
}
}IValidatableObjectIValidatableObjectValidationAttributePattern 4: IValidateOptions<T>
模式4:IValidateOptions<T>
Validate configuration/options classes at startup with access to DI services:
csharp
public sealed class DatabaseOptions
{
public const string SectionName = "Database";
public string ConnectionString { get; set; } = "";
public int MaxRetryCount { get; set; } = 3;
public int CommandTimeoutSeconds { get; set; } = 30;
public int MaxPoolSize { get; set; } = 100;
public int MinPoolSize { get; set; } = 0;
}
public sealed class DatabaseOptionsValidator : IValidateOptions<DatabaseOptions>
{
public ValidateOptionsResult Validate(string? name, DatabaseOptions options)
{
var failures = new List<string>();
if (string.IsNullOrWhiteSpace(options.ConnectionString))
{
failures.Add("Database connection string is required.");
}
if (options.MaxRetryCount is < 0 or > 10)
{
failures.Add("MaxRetryCount must be between 0 and 10.");
}
if (options.MinPoolSize > options.MaxPoolSize)
{
failures.Add($"MinPoolSize ({options.MinPoolSize}) cannot exceed MaxPoolSize ({options.MaxPoolSize}).");
}
return failures.Count > 0
? ValidateOptionsResult.Fail(failures)
: ValidateOptionsResult.Success;
}
}启动时验证配置/选项类,可访问DI服务:
csharp
public sealed class DatabaseOptions
{
public const string SectionName = "Database";
public string ConnectionString { get; set; } = "";
public int MaxRetryCount { get; set; } = 3;
public int CommandTimeoutSeconds { get; set; } = 30;
public int MaxPoolSize { get; set; } = 100;
public int MinPoolSize { get; set; } = 0;
}
public sealed class DatabaseOptionsValidator : IValidateOptions<DatabaseOptions>
{
public ValidateOptionsResult Validate(string? name, DatabaseOptions options)
{
var failures = new List<string>();
if (string.IsNullOrWhiteSpace(options.ConnectionString))
{
failures.Add("Database connection string is required.");
}
if (options.MaxRetryCount is < 0 or > 10)
{
failures.Add("MaxRetryCount must be between 0 and 10.");
}
if (options.MinPoolSize > options.MaxPoolSize)
{
failures.Add($"MinPoolSize ({options.MinPoolSize}) cannot exceed MaxPoolSize ({options.MaxPoolSize}).");
}
return failures.Count > 0
? ValidateOptionsResult.Fail(failures)
: ValidateOptionsResult.Success;
}
}Registration
注册方式
csharp
builder.Services
.AddOptions<DatabaseOptions>()
.BindConfiguration(DatabaseOptions.SectionName)
.ValidateDataAnnotations()
.ValidateOnStart();
builder.Services.AddSingleton<IValidateOptions<DatabaseOptions>, DatabaseOptionsValidator>();csharp
builder.Services
.AddOptions<DatabaseOptions>()
.BindConfiguration(DatabaseOptions.SectionName)
.ValidateDataAnnotations()
.ValidateOnStart();
builder.Services.AddSingleton<IValidateOptions<DatabaseOptions>, DatabaseOptionsValidator>();Pattern 5: FluentValidation Setup
模式5:FluentValidation配置
NuGet Packages
NuGet包安装
xml
<PackageReference Include="FluentValidation" Version="11.9.*" />
<PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.*" />xml
<PackageReference Include="FluentValidation" Version="11.9.*" />
<PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.*" />Configuration
配置代码
csharp
builder.Services.AddFluentValidationAutoValidation();
builder.Services.AddFluentValidationClientsideAdapters();
builder.Services.AddValidatorsFromAssemblyContaining<Program>();csharp
builder.Services.AddFluentValidationAutoValidation();
builder.Services.AddFluentValidationClientsideAdapters();
builder.Services.AddValidatorsFromAssemblyContaining<Program>();Basic Validator
基础验证器示例
csharp
public class SignUpRequest
{
public required string FirstName { get; set; }
public required string LastName { get; set; }
public required string Email { get; set; }
public required string Username { get; set; }
public required string Password { get; set; }
public required string ConfirmPassword { get; set; }
public required bool AcceptsTos { get; set; }
}
internal sealed class SignUpValidator : AbstractValidator<SignUpRequest>
{
public SignUpValidator()
{
RuleFor(x => x.FirstName)
.NotEmpty().WithMessage("Please enter a first name")
.MinimumLength(3).WithMessage("First name must be at least 3 characters long")
.MaximumLength(50).WithMessage("First name cannot exceed 50 characters")
.Matches(@"^[a-zA-Z\s'-]+$").WithMessage("First name contains invalid characters");
RuleFor(x => x.Email)
.NotEmpty().WithMessage("Please enter an email")
.EmailAddress().WithMessage("Please enter a valid email address")
.MustAsync(BeUniqueEmail).WithMessage("An account with this email already exists");
RuleFor(x => x.Password)
.NotEmpty().WithMessage("Please enter a password")
.MinimumLength(8).WithMessage("Password must be at least 8 characters long")
.Matches(@"[A-Z]").WithMessage("Password must contain at least one uppercase letter")
.Matches(@"[a-z]").WithMessage("Password must contain at least one lowercase letter")
.Matches(@"[0-9]").WithMessage("Password must contain at least one number")
.Matches(@"[^a-zA-Z0-9]").WithMessage("Password must contain at least one special character");
RuleFor(x => x.ConfirmPassword)
.Equal(x => x.Password).WithMessage("Passwords do not match");
RuleFor(x => x.AcceptsTos)
.Equal(true).WithMessage("You must accept our Terms of Service to sign up");
}
private async Task<bool> BeUniqueEmail(string email, CancellationToken cancellationToken)
{
return !await _dbContext.Users.AnyAsync(u => u.Email == email, cancellationToken);
}
}csharp
public class SignUpRequest
{
public required string FirstName { get; set; }
public required string LastName { get; set; }
public required string Email { get; set; }
public required string Username { get; set; }
public required string Password { get; set; }
public required string ConfirmPassword { get; set; }
public required bool AcceptsTos { get; set; }
}
internal sealed class SignUpValidator : AbstractValidator<SignUpRequest>
{
public SignUpValidator()
{
RuleFor(x => x.FirstName)
.NotEmpty().WithMessage("Please enter a first name")
.MinimumLength(3).WithMessage("First name must be at least 3 characters long")
.MaximumLength(50).WithMessage("First name cannot exceed 50 characters")
.Matches(@"^[a-zA-Z\s'-]+$").WithMessage("First name contains invalid characters");
RuleFor(x => x.Email)
.NotEmpty().WithMessage("Please enter an email")
.EmailAddress().WithMessage("Please enter a valid email address")
.MustAsync(BeUniqueEmail).WithMessage("An account with this email already exists");
RuleFor(x => x.Password)
.NotEmpty().WithMessage("Please enter a password")
.MinimumLength(8).WithMessage("Password must be at least 8 characters long")
.Matches(@"[A-Z]").WithMessage("Password must contain at least one uppercase letter")
.Matches(@"[a-z]").WithMessage("Password must contain at least one lowercase letter")
.Matches(@"[0-9]").WithMessage("Password must contain at least one number")
.Matches(@"[^a-zA-Z0-9]").WithMessage("Password must contain at least one special character");
RuleFor(x => x.ConfirmPassword)
.Equal(x => x.Password).WithMessage("Passwords do not match");
RuleFor(x => x.AcceptsTos)
.Equal(true).WithMessage("You must accept our Terms of Service to sign up");
}
private async Task<bool> BeUniqueEmail(string email, CancellationToken cancellationToken)
{
return !await _dbContext.Users.AnyAsync(u => u.Email == email, cancellationToken);
}
}Conditional Validation
条件验证
csharp
public class OrderValidator : AbstractValidator<OrderRequest>
{
public OrderValidator()
{
RuleFor(x => x.ShippingAddress)
.NotEmpty()
.When(x => x.RequiresShipping)
.WithMessage("Shipping address is required when shipping is needed");
RuleFor(x => x.PickupLocation)
.NotEmpty()
.When(x => !x.RequiresShipping)
.WithMessage("Pickup location is required for in-store pickup");
When(x => x.IsExpressShipping, () =>
{
RuleFor(x => x.ShippingAddress.Country)
.Must(BeSupportedCountry)
.WithMessage("Express shipping is not available for this country");
});
}
}csharp
public class OrderValidator : AbstractValidator<OrderRequest>
{
public OrderValidator()
{
RuleFor(x => x.ShippingAddress)
.NotEmpty()
.When(x => x.RequiresShipping)
.WithMessage("Shipping address is required when shipping is needed");
RuleFor(x => x.PickupLocation)
.NotEmpty()
.When(x => !x.RequiresShipping)
.WithMessage("Pickup location is required for in-store pickup");
When(x => x.IsExpressShipping, () =>
{
RuleFor(x => x.ShippingAddress.Country)
.Must(BeSupportedCountry)
.WithMessage("Express shipping is not available for this country");
});
}
}Collection Validation
集合验证
csharp
public class OrderRequestValidator : AbstractValidator<OrderRequest>
{
public OrderRequestValidator()
{
RuleFor(x => x.Items)
.NotEmpty().WithMessage("Order must contain at least one item")
.Must(items => items.Count <= 100).WithMessage("Order cannot contain more than 100 items");
RuleForEach(x => x.Items).ChildRules(item =>
{
item.RuleFor(x => x.ProductId)
.NotEmpty().WithMessage("Product is required");
item.RuleFor(x => x.Quantity)
.GreaterThan(0).WithMessage("Quantity must be greater than 0")
.LessThanOrEqualTo(999).WithMessage("Quantity cannot exceed 999");
});
}
}csharp
public class OrderRequestValidator : AbstractValidator<OrderRequest>
{
public OrderRequestValidator()
{
RuleFor(x => x.Items)
.NotEmpty().WithMessage("Order must contain at least one item")
.Must(items => items.Count <= 100).WithMessage("Order cannot contain more than 100 items");
RuleForEach(x => x.Items).ChildRules(item =>
{
item.RuleFor(x => x.ProductId)
.NotEmpty().WithMessage("Product is required");
item.RuleFor(x => x.Quantity)
.GreaterThan(0).WithMessage("Quantity must be greater than 0")
.LessThanOrEqualTo(999).WithMessage("Quantity cannot exceed 999");
});
}
}Pattern 6: MediatR Validation Pipeline Behavior
模式6:MediatR验证管道行为
csharp
internal sealed class ValidationBehavior<TRequest, TResponse>(IEnumerable<IValidator<TRequest>> validators)
: IPipelineBehavior<TRequest, TResponse>
where TRequest : IRequest<TResponse>
{
public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
{
if (!validators.Any())
{
return await next(cancellationToken).ConfigureAwait(false);
}
var context = new ValidationContext<TRequest>(request);
var validationResults = await Task.WhenAll(
validators.Select(v => v.ValidateAsync(context, cancellationToken)))
.ConfigureAwait(false);
var failures = validationResults
.SelectMany(r => r.Errors)
.Where(f => f != null)
.ToList();
if (failures.Count == 0)
{
return await next(cancellationToken).ConfigureAwait(false);
}
throw new ValidationException(failures);
}
}
public class ValidationException : Exception
{
public IReadOnlyList<ValidationFailure> Errors { get; }
public ValidationException(IEnumerable<ValidationFailure> failures)
: base("Validation failed")
{
Errors = failures.ToList().AsReadOnly();
}
public IDictionary<string, string[]> ToDictionary()
{
return Errors
.GroupBy(e => e.PropertyName)
.ToDictionary(
g => g.Key,
g => g.Select(e => e.ErrorMessage).ToArray());
}
}csharp
internal sealed class ValidationBehavior<TRequest, TResponse>(IEnumerable<IValidator<TRequest>> validators)
: IPipelineBehavior<TRequest, TResponse>
where TRequest : IRequest<TResponse>
{
public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
{
if (!validators.Any())
{
return await next(cancellationToken).ConfigureAwait(false);
}
var context = new ValidationContext<TRequest>(request);
var validationResults = await Task.WhenAll(
validators.Select(v => v.ValidateAsync(context, cancellationToken)))
.ConfigureAwait(false);
var failures = validationResults
.SelectMany(r => r.Errors)
.Where(f => f != null)
.ToList();
if (failures.Count == 0)
{
return await next(cancellationToken).ConfigureAwait(false);
}
throw new ValidationException(failures);
}
}
public class ValidationException : Exception
{
public IReadOnlyList<ValidationFailure> Errors { get; }
public ValidationException(IEnumerable<ValidationFailure> failures)
: base("Validation failed")
{
Errors = failures.ToList().AsReadOnly();
}
public IDictionary<string, string[]> ToDictionary()
{
return Errors
.GroupBy(e => e.PropertyName)
.ToDictionary(
g => g.Key,
g => g.Select(e => e.ErrorMessage).ToArray());
}
}Registration
注册方式
csharp
builder.Services.AddMediatR(cfg =>
{
cfg.RegisterServicesFromAssemblyContaining<Program>();
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});csharp
builder.Services.AddMediatR(cfg =>
{
cfg.RegisterServicesFromAssemblyContaining<Program>();
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});Pattern 7: Manual Validation
模式7:手动验证
Run DataAnnotations validation programmatically:
csharp
public static class ValidationHelper
{
public static (bool IsValid, IReadOnlyList<ValidationResult> Errors) Validate<T>(
T instance) where T : notnull
{
var results = new List<ValidationResult>();
var context = new ValidationContext(instance);
bool isValid = Validator.TryValidateObject(
instance, context, results, validateAllProperties: true);
return (isValid, results);
}
}Critical: Without , only checks attributes.
validateAllProperties: trueValidator.TryValidateObject[Required]通过编程方式执行DataAnnotations验证:
csharp
public static class ValidationHelper
{
public static (bool IsValid, IReadOnlyList<ValidationResult> Errors) Validate<T>(
T instance) where T : notnull
{
var results = new List<ValidationResult>();
var context = new ValidationContext(instance);
bool isValid = Validator.TryValidateObject(
instance, context, results, validateAllProperties: true);
return (isValid, results);
}
}重要提示: 如果不设置,仅会检查特性。
validateAllProperties: trueValidator.TryValidateObject[Required]Pattern 8: Validating File Uploads
模式8:文件上传验证
csharp
public class FileUploadValidator : AbstractValidator<FileUploadRequest>
{
private readonly string[] _allowedExtensions = [".jpg", ".jpeg", ".png", ".pdf"];
private const long MaxFileSize = 10 * 1024 * 1024; // 10MB
public FileUploadValidator()
{
RuleFor(x => x.File)
.NotNull()
.Must(BeValidSize).WithMessage("File size must not exceed 10MB")
.Must(BeValidExtension).WithMessage("Invalid file type. Allowed: .jpg, .jpeg, .png, .pdf");
RuleFor(x => x.Description)
.MaximumLength(500).When(x => !string.IsNullOrEmpty(x.Description));
}
private bool BeValidSize(IFormFile file) => file.Length <= MaxFileSize;
private bool BeValidExtension(IFormFile file)
{
var extension = Path.GetExtension(file.FileName).ToLowerInvariant();
return _allowedExtensions.Contains(extension);
}
}csharp
public class FileUploadValidator : AbstractValidator<FileUploadRequest>
{
private readonly string[] _allowedExtensions = [".jpg", ".jpeg", ".png", ".pdf"];
private const long MaxFileSize = 10 * 1024 * 1024; // 10MB
public FileUploadValidator()
{
RuleFor(x => x.File)
.NotNull()
.Must(BeValidSize).WithMessage("File size must not exceed 10MB")
.Must(BeValidExtension).WithMessage("Invalid file type. Allowed: .jpg, .jpeg, .png, .pdf");
RuleFor(x => x.Description)
.MaximumLength(500).When(x => !string.IsNullOrEmpty(x.Description));
}
private bool BeValidSize(IFormFile file) => file.Length <= MaxFileSize;
private bool BeValidExtension(IFormFile file)
{
var extension = Path.GetExtension(file.FileName).ToLowerInvariant();
return _allowedExtensions.Contains(extension);
}
}Anti-Patterns
反模式
Duplicate Validation
重复验证
csharp
// BAD: Validation in multiple places
if (string.IsNullOrEmpty(model.Email))
ModelState.AddModelError("Email", "Required");
RuleFor(x => x.Email).NotEmpty(); // Duplicate!
// GOOD: Centralize validation in validatorscsharp
// 错误示例:在多处重复实现验证逻辑
if (string.IsNullOrEmpty(model.Email))
ModelState.AddModelError("Email", "Required");
RuleFor(x => x.Email).NotEmpty(); // 重复验证!
// 正确示例:将验证逻辑集中在验证器中Silent Validation Failures
静默验证失败
csharp
// BAD: Ignoring validation results
catch (ValidationException)
{
return Page();
}
// GOOD: Always add errors to ModelState
catch (ValidationException ex)
{
foreach (var error in ex.Errors)
{
ModelState.AddModelError(error.PropertyName, error.ErrorMessage);
}
return Page();
}csharp
// 错误示例:忽略验证结果
catch (ValidationException)
{
return Page();
}
// 正确示例:始终将错误添加到ModelState中
catch (ValidationException ex)
{
foreach (var error in ex.Errors)
{
ModelState.AddModelError(error.PropertyName, error.ErrorMessage);
}
return Page();
}Trusting Client-Side Validation
完全依赖客户端验证
csharp
// BAD: Only client-side validation
public IActionResult OnPost(UserInput input)
{
SaveToDatabase(input);
}
// GOOD: Server-side always validates
public IActionResult OnPost(UserInput input)
{
if (!ModelState.IsValid)
return Page();
SaveToDatabase(input);
}csharp
// 错误示例:仅做客户端验证
public IActionResult OnPost(UserInput input)
{
SaveToDatabase(input);
}
// 正确示例:服务端始终执行验证
public IActionResult OnPost(UserInput input)
{
if (!ModelState.IsValid)
return Page();
SaveToDatabase(input);
}Agent Gotchas
开发注意事项
- Always pass to
validateAllProperties: true.Validator.TryValidateObject - Options classes must use not
{ get; set; }-- configuration binder needs to mutate properties.{ get; init; } - runs only after all attribute validations pass -- do not rely on it for primary validation.
IValidatableObject.Validate() - Do not inject services into via constructor -- use
ValidationAttributeinsidevalidationContext.GetService<T>().IsValid() - Register as singleton -- the options validation infrastructure resolves validators as singletons.
IValidateOptions<T> - Do not forget -- without it, options validation only runs on first access.
ValidateOnStart()
- 始终为传入
Validator.TryValidateObject。validateAllProperties: true - 选项类必须使用而非
{ get; set; }-- 配置绑定器需要修改属性值。{ get; init; } - 仅会在所有特性验证通过后执行 -- 不要将其作为主要验证手段。
IValidatableObject.Validate() - 不要通过构造函数向注入服务 -- 在
ValidationAttribute方法内部使用IsValid()获取服务。validationContext.GetService<T>() - 将注册为单例 -- 选项验证基础设施会以单例形式解析验证器。
IValidateOptions<T> - 不要忘记调用-- 不调用的话,选项验证仅会在首次访问时执行。
ValidateOnStart()