C# ASP.NET Core如何统一配置JsonOptions实现全局JSON序列化

在ASP.NET Core项目中，默认的JSON序列化配置可能无法满足所有业务需求，比如需要将日期格式统一为yyyy-MM-dd HH:mm:ss，或者将属性名按照驼峰命名之外的规则输出，又或者忽略空值属性。如果逐个接口单独设置序列化参数，不仅工作量大，还容易出现规则不一致的问题，因此统一配置JsonOptions实现全局JSON序列化是非常有必要的。

JsonOptions配置的作用范围

JsonOptions是ASP.NET Core中用于配置JSON序列化行为的选项类，通过修改它的属性，可以影响所有使用System.Text.Json进行序列化的接口返回结果，包括控制器接口的返回值、HTTP响应中的JSON内容等，无需在每个Action中单独编写序列化配置代码。

常用全局配置项说明

System.Text.Json提供了丰富的配置选项，以下是开发中最常用的几个配置项：

• PropertyNamingPolicy：控制属性名的命名规则，默认是驼峰命名，可设置为null保持原属性名，或者自定义命名策略
• JsonSerializerOptions.Converters：添加自定义的JSON转换器，比如处理特殊日期格式、枚举转换等
• DefaultIgnoreCondition：设置默认忽略条件，比如忽略值为null的属性
• Encoder：设置字符编码，避免中文等特殊字符被转义

在Program.cs中统一配置JsonOptions

ASP.NET Core 6及以上版本使用顶级语句的Program.cs文件，我们可以直接在添加控制器服务时配置JsonOptions，具体代码如下：

// 添加控制器服务并配置全局JsonOptions
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 1. 配置属性命名规则：设置为null表示保持实体类的原始属性名，不使用驼峰命名
        options.JsonSerializerOptions.PropertyNamingPolicy = null;
        
        // 2. 配置日期格式：添加自定义日期转换器，统一日期格式为yyyy-MM-dd HH:mm:ss
        options.JsonSerializerOptions.Converters.Add(new System.Text.Json.Serialization.JsonConverterFactory());
        // 自定义日期转换器实现
        options.JsonSerializerOptions.Converters.Add(new DateTimeJsonConverter());
        
        // 3. 配置忽略空值属性：当属性值为null时，不序列化该属性
        options.JsonSerializerOptions.DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull;
        
        // 4. 配置字符编码：不转义中文等特殊字符
        options.JsonSerializerOptions.Encoder = System.Text.Json.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping;
    });

// 自定义日期转换器，实现日期格式统一
public class DateTimeJsonConverter : System.Text.Json.Serialization.JsonConverter<DateTime>
{
    private readonly string _format = "yyyy-MM-dd HH:mm:ss";
    
    public override DateTime Read(ref System.Text.Json.Utf8JsonReader reader, Type typeToConvert, System.Text.Json.JsonSerializerOptions options)
    {
        // 反序列化时解析日期字符串
        return DateTime.ParseExact(reader.GetString(), _format, System.Globalization.CultureInfo.InvariantCulture);
    }
    
    public override void Write(System.Text.Json.Utf8JsonWriter writer, DateTime value, System.Text.Json.JsonSerializerOptions options)
    {
        // 序列化时按照指定格式输出日期
        writer.WriteStringValue(value.ToString(_format));
    }
}

验证配置是否生效

我们可以创建一个简单的测试控制器，验证全局配置是否生效：

[ApiController]
[Route("api/test")]
public class TestController : ControllerBase
{
    [HttpGet("getdata")]
    public ActionResult<TestModel> GetData()
    {
        return new TestModel
        {
            UserName = "测试用户",
            Age = 25,
            BirthDate = DateTime.Now,
            Address = null // 该属性值为null，根据配置应该不会被序列化
        };
    }
}

// 测试实体类
public class TestModel
{
    public string UserName { get; set; }
    public int Age { get; set; }
    public DateTime BirthDate { get; set; }
    public string Address { get; set; }
}

调用api/test/getdata接口后，返回的JSON结果应该符合我们的全局配置：属性名保持原始大小写，日期格式为yyyy-MM-dd HH:mm:ss，Address属性因为值为null没有被序列化，中文也没有被转义。

注意事项

如果项目中同时使用Newtonsoft.Json（即Json.NET）作为JSON序列化库，配置方式会有所不同，需要在添加服务时指定使用Newtonsoft.Json，然后配置MvcNewtonsoftJsonOptions，示例代码如下：

// 使用Newtonsoft.Json时的全局配置
builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        // 设置日期格式
        options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";
        // 忽略空值
        options.SerializerSettings.NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore;
        // 保持属性名原样
        options.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver();
    });

需要注意，一旦选择了System.Text.Json或者Newtonsoft.Json作为序列化库，就不要混合使用两者的配置，否则可能导致配置不生效或者序列化异常。

C#ASP.NET_CoreJsonOptionsJSON序列化修改时间：2026-07-06 14:45:26