ASP.NET 6.0中传递空白字符时[FromQuery]字符串为何为null？

问题背景 #

在ASP.NET 6.0中，当传递全空白字符（包括空格、+、%20等URL编码的空白）作为可选查询字符串参数时，参数值会被默认模型绑定解析为null，而非保留空白字符串。需求是仅当查询参数完全缺失时返回null，其他情况需保留包含空白的字符串以支持空格搜索。

测试代码示例：

[HttpGet("test")]
public string Search(string q = null)
{
  return q;
}

// 或使用[FromQuery]标记
[HttpGet("test")]
public string Search([FromQuery] string q = null)
{
  return q;
}

现有不符合预期的测试结果：

• test?q=a → 返回a（正常）
• test?q= a → 返回 a（正常，非全空白）
• test?q= → 返回null（不符合预期，应返回空格）
• test?q=+ → 返回null（不符合预期，应返回空格）
• test?q=%20 → 返回null（不符合预期，应返回空格）
• test?q=+ + %20 + → 返回null（不符合预期，应返回对应空白组合）

原因分析 #

ASP.NET Core默认模型绑定逻辑中，对于可空字符串参数（默认值为null），会自动修剪空白字符并将全空白输入转换为null。这是StringTrimConverter和NullableConverter的组合行为，虽简化了空值处理，但与保留空白搜索的需求冲突。

解决方法 #

方法1：自定义模型绑定器（针对单个参数）

创建自定义模型绑定器，绕过默认的空白修剪和null转换逻辑，直接保留原始查询值：

// 自定义模型绑定器
public class PreserveWhitespaceModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var valueProviderResult = bindingContext.ValueProvider.GetValue(bindingContext.ModelName);
        if (valueProviderResult == ValueProviderResult.None)
            return Task.CompletedTask;

        bindingContext.ModelState.SetModelValue(bindingContext.ModelName, valueProviderResult);
        // 直接赋值原始值，不做修剪或null转换
        bindingContext.Result = ModelBindingResult.Success(valueProviderResult.FirstValue);
        return Task.CompletedTask;
    }
}

在接口参数上应用绑定器：

[HttpGet("test")]
public string Search(
    [FromQuery, ModelBinder(typeof(PreserveWhitespaceModelBinder))] 
    string q = null)
{
    return q;
}

优点：仅影响目标参数，不干扰其他接口的默认行为；灵活可控。
缺点：需要为每个需要保留空白的参数单独配置。

方法2：全局配置修改字符串绑定行为

通过全局配置替换默认的字符串模型绑定逻辑，让所有字符串参数都保留空白值：

首先实现自定义绑定器提供者：

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

        // 仅对string类型参数应用自定义绑定器
        if (context.Metadata.ModelType == typeof(string))
            return new PreserveWhitespaceModelBinder();

        return null;
    }
}

然后在Program.cs中注册全局绑定器：

var builder = WebApplication.CreateBuilder(args);

// 添加控制器并替换默认字符串绑定器
builder.Services.AddControllers(options =>
{
    // 移除默认的字符串模型绑定器提供者
    var defaultProvider = options.ModelBinderProviders
        .OfType<StringModelBinderProvider>()
        .FirstOrDefault();
    if (defaultProvider != null)
    {
        options.ModelBinderProviders.Remove(defaultProvider);
    }
    // 添加自定义绑定器提供者
    options.ModelBinderProviders.Insert(0, new PreserveWhitespaceStringModelBinderProvider());
});

var app = builder.Build();

// 中间件配置...
app.MapControllers();
app.Run();

优点：一次配置，所有字符串参数生效，适合全局需要保留空白的场景。
缺点：会改变所有接口的默认行为，可能影响其他业务逻辑的预期。

方法3：手动读取查询字符串（绕过模型绑定）

直接从HttpContext中读取查询参数，完全绕过默认模型绑定的处理逻辑：

[HttpGet("test")]
public string Search(HttpContext context)
{
    // 判断参数是否存在：存在则返回原始值，不存在则返回null
    return context.Request.Query.ContainsKey("q") 
        ? context.Request.Query["q"].ToString() 
        : null;
}

优点：实现最简单，无需配置模型绑定，直接控制参数解析逻辑。
缺点：需要手动处理参数存在性判断，若参数较多会增加代码量。

验证结果 #

应用上述任一方法后，测试结果将符合预期：

• test?q= → 返回空字符串""
• test?q= → 返回空格" "
• test?q=%20 → 返回空格" "
• test?q=+ + %20 + → 返回对应的空白组合字符串" "
• test（无q参数）→ 返回null

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