C#如何使用System.Text.Json？完整教程与代码实例

System.Text.Json是.NET Core 3.0及以上版本内置的JSON处理库，提供了高性能的序列化与反序列化能力，无需引入第三方依赖即可完成JSON相关操作。它支持多种数据类型转换，同时允许开发者自定义转换规则适配复杂业务场景。

基础序列化与反序列化

最基础的用法是将对象转换为JSON字符串，或者将JSON字符串转换为对应对象，核心类是JsonSerializer。

序列化示例

首先定义一个简单的实体类，然后将其序列化为JSON字符串：

using System;
using System.Text.Json;

// 定义实体类
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public DateTime RegisterTime { get; set; }
}

class Program
{
    static void Main()
    {
        // 创建对象实例
        User user = new User
        {
            Id = 1,
            Name = "张三",
            Age = 25,
            RegisterTime = DateTime.Now
        };
        
        // 执行序列化
        string jsonString = JsonSerializer.Serialize(user);
        Console.WriteLine(jsonString);
    }
}

反序列化示例

将JSON字符串转换为对应的C#对象：

using System;
using System.Text.Json;

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public DateTime RegisterTime { get; set; }
}

class Program
{
    static void Main()
    {
        string json = "{"Id":1,"Name":"张三","Age":25,"RegisterTime":"2024-05-20T10:30:00"}";
        
        // 执行反序列化
        User user = JsonSerializer.Deserialize<User>(json);
        
        Console.WriteLine($"用户ID：{user.Id}");
        Console.WriteLine($"用户名称：{user.Name}");
        Console.WriteLine($"用户年龄：{user.Age}");
        Console.WriteLine($"注册时间：{user.RegisterTime}");
    }
}

自定义序列化选项

默认情况下System.Text.Json的序列化行为可能不符合需求，比如属性名大小写、日期格式、忽略空值等，可以通过JsonSerializerOptions自定义配置。

常用配置项

• PropertyNamingPolicy：设置属性名命名策略，默认是保持原样，可设置为JsonNamingPolicy.CamelCase转为驼峰命名
• WriteIndented：是否格式化输出JSON，默认false，设置为true会添加缩进换行
• DefaultIgnoreCondition：设置忽略空值的规则，可配置忽略null值属性
• Converters：添加自定义转换器，处理特殊类型的序列化逻辑

配置示例

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int? Age { get; set; }
    public DateTime RegisterTime { get; set; }
}

class Program
{
    static void Main()
    {
        User user = new User
        {
            Id = 1,
            Name = "张三",
            Age = null,
            RegisterTime = DateTime.Now
        };
        
        JsonSerializerOptions options = new JsonSerializerOptions
        {
            // 属性名转为驼峰命名
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            // 格式化输出
            WriteIndented = true,
            // 忽略null值属性
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
            // 日期格式转为字符串
            Converters = { new JsonStringEnumConverter() }
        };
        
        string json = JsonSerializer.Serialize(user, options);
        Console.WriteLine(json);
    }
}

处理嵌套对象与集合

System.Text.Json支持直接处理嵌套对象和集合类型，无需额外配置。

嵌套对象序列化

using System;
using System.Text.Json;

public class Address
{
    public string Province { get; set; }
    public string City { get; set; }
}

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Address UserAddress { get; set; }
}

class Program
{
    static void Main()
    {
        User user = new User
        {
            Id = 1,
            Name = "张三",
            UserAddress = new Address
            {
                Province = "广东",
                City = "深圳"
            }
        };
        
        string json = JsonSerializer.Serialize(user);
        Console.WriteLine(json);
        
        // 反序列化嵌套对象
        User deserializedUser = JsonSerializer.Deserialize<User>(json);
        Console.WriteLine($"所在城市：{deserializedUser.UserAddress.City}");
    }
}

集合序列化

using System;
using System.Collections.Generic;
using System.Text.Json;

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
}

class Program
{
    static void Main()
    {
        List<User> userList = new List<User>
        {
            new User { Id = 1, Name = "张三" },
            new User { Id = 2, Name = "李四" },
            new User { Id = 3, Name = "王五" }
        };
        
        string json = JsonSerializer.Serialize(userList);
        Console.WriteLine(json);
        
        // 反序列化集合
        List<User> deserializedList = JsonSerializer.Deserialize<List<User>>(json);
        foreach (var item in deserializedList)
        {
            Console.WriteLine($"用户ID：{item.Id}，名称：{item.Name}");
        }
    }
}

自定义转换器

当默认转换规则无法满足需求时，可以自定义转换器处理特殊类型的序列化逻辑，比如自定义日期格式、处理特殊枚举等。

自定义日期转换器示例

默认日期序列化格式是ISO 8601格式，如果需要转为yyyy-MM-dd格式，可以自定义转换器：

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

public class CustomDateTimeConverter : JsonConverter<DateTime>
{
    private readonly string _format;
    
    public CustomDateTimeConverter(string format)
    {
        _format = format;
    }
    
    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTime.Parse(reader.GetString());
    }
    
    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(_format));
    }
}

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime RegisterTime { get; set; }
}

class Program
{
    static void Main()
    {
        User user = new User
        {
            Id = 1,
            Name = "张三",
            RegisterTime = DateTime.Now
        };
        
        JsonSerializerOptions options = new JsonSerializerOptions();
        // 添加自定义日期转换器，指定格式
        options.Converters.Add(new CustomDateTimeConverter("yyyy-MM-dd"));
        
        string json = JsonSerializer.Serialize(user, options);
        Console.WriteLine(json);
    }
}

常见问题与注意事项

• System.Text.Json默认是区分属性名大小写的，反序列化时如果JSON属性名和类属性名大小写不一致会失败，可通过JsonSerializerOptions.PropertyNameCaseInsensitive = true设置为不区分大小写
• 对于不可序列化的类型（比如带有只读属性的类），需要额外配置或者添加自定义转换器
• 处理大型JSON数据时，System.Text.Json提供了基于Utf8JsonReader和Utf8JsonWriter的低级API，性能更高，适合高性能场景

System.Text.JsonC#JSON序列化JSON反序列化修改时间：2026-06-20 23:15:36