ASP.NET [FromQuery]模型绑定使用EnumMember值反序列化枚举

问题本质 #

.NET 6 基于Microsoft.NET.Sdk.Web构建的Web项目中，使用[FromQuery]特性绑定查询参数到模型时，走的是MVC独立的模型绑定管道，而非Json序列化管道，默认的枚举绑定逻辑只支持枚举名、数字字符串转换，不会识别枚举成员上[EnumMember]特性配置的自定义映射值。

涉及的典型代码结构如下：
控制器代码：

[Route("[controller]")]
public class SamplesController : ControllerBase
{
    [HttpGet]
    public IActionResult Get([FromQuery]QueryModel queryModel)
    {
        if (!queryModel.Status.HasValue)
        {
            return BadRequest("枚举绑定失败");
        }
        
        return Ok(queryModel.Status.Value.GetEnumDisplayName());
    }
}

查询模型代码：

public class QueryModel
{
    /// <summary>
    /// The foo parameter
    /// </summary>
    /// <example>bar</example>
    public string? Foo { get; init; } = null;
    
    /// <summary>
    /// The status
    /// </summary>
    /// <example>on-hold</example>
    public Status? Status { get; set; } = null;
}

枚举定义代码：

public enum Status
{
    [EnumMember(Value = "open")]
    Open,
    
    [EnumMember(Value = "on-hold")]
    OnHold
}

预期效果：访问http://localhost:5000/Samples?Foo=bar&Status=on-hold时，queryModel.Status能正确映射为Status.OnHold枚举值，而非绑定为null。

注意：针对Json序列化配置的自定义枚举转换器、第三方Json枚举扩展库，都不会作用于Query参数的绑定流程，这也是很多同类方案无效的根本原因。

原生实现方案（无任何第三方依赖） #

仅需通过.NET原生提供的模型绑定扩展点实现，分三步完成：

1. 实现支持EnumMember匹配的枚举模型绑定器 #

自定义通用枚举绑定器，反射读取枚举类型的EnumMember配置构建值映射表，优先匹配自定义值，同时兼容默认的枚举名、数字传值逻辑：

using System.Reflection;
using System.Runtime.Serialization;
using Microsoft.AspNetCore.Mvc.ModelBinding;

public class EnumMemberEnumBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        Type modelType = bindingContext.ModelType;
        Type enumType = Nullable.GetUnderlyingType(modelType) ?? modelType;
        if (!enumType.IsEnum)
        {
            bindingContext.Result = ModelBindingResult.Failed();
            return Task.CompletedTask;
        }

        ValueProviderResult valueResult = bindingContext.ValueProvider.GetValue(bindingContext.ModelName);
        if (valueResult == ValueProviderResult.None || string.IsNullOrWhiteSpace(valueResult.FirstValue))
        {
            if (Nullable.GetUnderlyingType(modelType) != null)
            {
                bindingContext.Result = ModelBindingResult.Success(null);
            }
            return Task.CompletedTask;
        }

        string rawValue = valueResult.FirstValue.Trim();
        Dictionary<string, object> valueMap = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
        FieldInfo[] enumFields = enumType.GetFields(BindingFlags.Public | BindingFlags.Static);
        
        foreach (FieldInfo field in enumFields)
        {
            EnumMemberAttribute? enumMemberAttr = field.GetCustomAttribute<EnumMemberAttribute>();
            object enumValue = field.GetValue(null)!;
            // 优先注册EnumMember配置的自定义值
            if (!string.IsNullOrEmpty(enumMemberAttr?.Value))
            {
                valueMap.TryAdd(enumMemberAttr.Value, enumValue);
            }
            // 兼容默认枚举名匹配
            valueMap.TryAdd(field.Name, enumValue);
        }

        // 优先匹配自定义值、枚举名
        if (valueMap.TryGetValue(rawValue, out object? matchedValue))
        {
            bindingContext.Result = ModelBindingResult.Success(matchedValue);
            return Task.CompletedTask;
        }

        // 兼容数字传值
        if (int.TryParse(rawValue, out int numericValue) && Enum.IsDefined(enumType, numericValue))
        {
            bindingContext.Result = ModelBindingResult.Success(Enum.ToObject(enumType, numericValue));
            return Task.CompletedTask;
        }

        bindingContext.ModelState.TryAddModelError(bindingContext.ModelName, $"值“{rawValue}”无法转换为{enumType.Name}枚举类型");
        bindingContext.Result = ModelBindingResult.Failed();
        return Task.CompletedTask;
    }
}

2. 实现模型绑定器提供器 #

通过绑定器提供器让框架自动识别枚举、可空枚举类型，自动使用上面实现的自定义绑定器，无需在每个属性上手动标注[ModelBinder]：

using Microsoft.AspNetCore.Mvc.ModelBinding;
using Microsoft.AspNetCore.Mvc.ModelBinding.Binders;

public class EnumMemberEnumBinderProvider : IModelBinderProvider
{
    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {
        if (context == null)
            throw new ArgumentNullException(nameof(context));

        Type targetType = Nullable.GetUnderlyingType(context.Metadata.ModelType) ?? context.Metadata.ModelType;
        return targetType.IsEnum ? new BinderTypeModelBinder(typeof(EnumMemberEnumBinder)) : null;
    }
}

3. 全局注册绑定器提供器 #

在Program.cs中注册服务时，将自定义绑定器提供器插入到内置绑定器集合的最前面，保证优先于默认枚举绑定器执行：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    // 必须插入到集合首位，否则会被默认枚举绑定器抢先处理
    options.ModelBinderProviders.Insert(0, new EnumMemberEnumBinderProvider());
});

// 其余服务配置（Swagger、鉴权等）保持不变

var app = builder.Build();
// 其余中间件配置保持不变
app.Run();

效果验证 #

配置完成后以下请求都可以正常绑定：

• 传Status=on-hold：正确映射为Status.OnHold
• 传Status=open：正确映射为Status.Open
• 原有默认逻辑不受影响：传Status=OnHold（枚举名）、Status=1（枚举数字值）依然可以正常绑定
• 传非法枚举值时会自动写入模型状态错误，可通过ModelState.IsValid做统一参数校验

内容的提问来源于stack exchange，提问作者diegosasw