ASP.NET Core Web API中结构体接收参数正常，替换为C# 7元组失效原因咨询

嘿，这个问题我之前帮不少开发者排查过，本质是ASP.NET Core的模型绑定器对结构体和C#7值元组的处理逻辑不一样，咱们一步步拆解：

结构体能正常工作的原因 #

你的UserNameAndPassword结构体定义了明确的公共字段username和password：

public struct UserNameAndPassword { 
    public string username; 
    public string password; 
}

当用[FromBody]标记这个结构体参数时，ASP.NET Core默认的JSON输入格式化器（比如System.Text.Json）会自动把请求体JSON中的键名（username、password）和结构体的字段做一一匹配，完美完成模型绑定，所以代码能正常运行。

元组失效的核心问题 #

当你换成C#7的值元组（比如(string username, string password)）时，这里的username和password只是编译时的友好别名——编译完成后，元组在运行时的实际字段名还是Item1和Item2。

如果你的请求体仍然是{"username":"xxx", "password":"xxx"}，模型绑定器找不到对应的Item1、Item2键，就会导致元组的两个元素都被设为null，后续的用户验证自然失败，看起来就像“无法正常工作”。

另外补充一点：如果你的项目用的是**.NET Core 3.1及更早版本**，System.Text.Json根本不识别元组的友好名称，哪怕你在代码里给了名字，绑定器也只会认Item1/Item2；而.NET 5及以后的版本虽然支持识别元组命名，但默认可能没开启字段绑定的配置。

解决办法 #

这里给你几个实用的方案，按推荐程度排序：

1. 继续用结构体/改用C#9+记录类型（最推荐） #

结构体本身就很适合这种简单的参数承载场景，如果你用的是C#9及以上版本，更推荐用记录类型，代码更简洁且功能一致：

public record UserNameAndPassword(string Username, string Password);

模型绑定器能完美识别记录类型的属性，完全不会有绑定问题。

2. （仅.NET 5+）配置JSON序列化器支持元组命名 #

如果你非要用元组，先确保项目是.NET 5及以上版本，然后在Program.cs（.NET 6+）或Startup.cs（.NET 5）中添加JSON配置，开启字段绑定并允许识别元组命名：

// .NET 6+ Program.cs示例
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.IncludeFields = true;
    });

这样修改后，请求体用{"username":"xxx", "password":"xxx"}就能正确绑定到命名元组上了。

3. 修改请求体键名（不推荐） #

把请求体的键改成Item1和Item2，比如：

{"Item1":"your-username", "Item2":"your-password"}

这种方式虽然能解决问题，但可读性极差，完全不推荐在生产环境使用。

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