.NET Web API如何配置XML格式化器

.net 6+ Web API 默认不支持 xml 响应，因移除了 XmlSerializerOutputFormatter，需手动安装 microsoft.AspNetCore.mvc.Formatters.Xml 包并注册该格式化器，且模型须满足无参构造、public 属性等要求。

为什么默认不支持 XML 响应

.NET 6+ 的 Web API 模板默认只注册 SystemTextjsonOutputFormatter，完全移除了对 XML 的自动支持。即使你返回 IActionResult 或启用了 [Produces("application/xml")]，请求带 Accept: application/xml 也会直接 406 Not Acceptable。

添加 XmlSerializerOutputFormatter 的正确方式

必须显式注册基于 XmlSerializer 的格式化器（XmlDataContractSerializer 已被弃用且不推荐用于 Web API）。注意：.NET 5+ 不再内置 XML 支持包，需先安装 NuGet 包：

dotnet add package Microsoft.AspNetCore.Mvc.Formatters.Xml

然后在 Program.cs 中注册：

builder.Services.AddControllers(options => {     options.OutputFormatters.Add(new XmlSerializerOutputFormatter());     // 可选：禁用默认的 json 格式化器（仅需 XML 时）     // options.OutputFormatters.RemoveType(); });

关键点：

• XmlSerializerOutputFormatter 要求模型类有无参构造函数，且属性必须是 public get/set
• 不支持 record 类型（会抛 InvalidOperationException: Type 'X' cannot be serialized）
• 若控制器方法返回 Task，确保实际返回值类型可被 XmlSerializer 序列化（如 Ok(MyModel)）

处理 XML 请求（POST/PUT）

仅配置输出格式化器不够——接收 XML 请求体还需注册输入格式化器：

builder.Services.AddControllers(options => {     options.InputFormatters.Add(new XmlSerializerInputFormatter(options));     options.OutputFormatters.Add(new XmlSerializerOutputFormatter()); });

此时需确保请求头包含 Content-Type: application/xml，且 XML 结构与模型字段名严格匹配（区分大小写，无命名空间更稳妥）。常见失败原因：

• XML 根节点名 ≠ 模型类名（XmlRoot 特性可覆盖）
• 字段名含下划线或驼峰，但 XML 使用短横线（如 ）→ 需加 [XmlElement("user-name")]
• 传了空字符串给非 Nullable 引用类型字段 → 反序列化失败

调试 406 或空响应的快速检查项

当 XML 响应不生效时，优先验证以下三点：

• 是否漏装 Microsoft.AspNetCore.Mvc.Formatters.Xml 包？没有它，XmlSerializerOutputFormatter 类型根本不存在
• 是否在 AddControllers() 后才调用 Build()？顺序错误会导致注册失效
• 是否误用了 services.AddMvc()（已过时）？.NET 6+ 推荐统一用 AddControllers() + AddEndpointsApiExplorer()
• 是否在 Startup.Configure() 中忘了调用 app.UseRouting() 和 app.UseEndpoints()？中间件链中断会导致格式化器不触发

XML 格式化器本身不处理缩进或编码声明，生成的 XML 默认无换行、UTF-8 无 bom。如果需要美化输出，得自己封装 XmlWriterSettings 并继承 XmlSerializerOutputFormatter —— 这部分容易被低估工作量。