当前位置： 首页 > news >正文

C# System.Text.Json 中 JsonIgnoreCondition 使用详解

news 2025/7/27 22:14:13

总目录

一、JsonIgnoreCondition 枚举值详解

JsonIgnoreCondition 是一个枚举类型，用于控制序列化或反序列化时如何忽略属性或字段。其枚举值及其含义如下：

枚举值作用
Always始终忽略该成员（无论值是什么）。
Never从不忽略该成员（即使全局设置了 DefaultIgnoreCondition）。
WhenWritingDefault当属性值为 默认值 时忽略（如 int 的默认值 0、string 的 null）。
WhenWritingNull当属性值为 null 时忽略（仅对可为 null 的类型生效）。

二、核心使用场景

1. 通过 [JsonIgnore] 特性控制单个成员

使用 [JsonIgnore(Condition = ...)] 特性可对单个属性或字段的忽略行为进行细粒度控制。

1）始终忽略属性（Always）

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

    [JsonIgnore(Condition = JsonIgnoreCondition.Always)]
    public string Password { get; set; } // 始终忽略
}

class Program
{
    static void Main()
    {
        var user = new User { Name = "Alice", Password = "123" };
        string json = JsonSerializer.Serialize(user);
        Console.WriteLine(json);
        // 输出:{"Name":"Alice"}
    }
}

2）仅在值为 null 时忽略（WhenWritingNull）

public class Product
{
    public string Name { get; set; }

    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public string Description { get; set; } // 值为 null 时忽略
}

class Program
{
    static void Main()
    {
        // 场景 1：Description 为 null
        var product1 = new Product { Name = "Book", Description = null };
        string json1 = JsonSerializer.Serialize(product1);
        Console.WriteLine(json1);
        // 输出:{"Name":"Book"}

        // 场景 2：Description 有值
        var product2 = new Product { Name = "Pen", Description = "Writing tool" };
        string json2 = JsonSerializer.Serialize(product2);
        Console.WriteLine(json2);
        // 输出:{"Name":"Pen","Description":"Writing tool"}
    }
}

3）仅在默认值时忽略（WhenWritingDefault）

public class Settings
{
    public int MaxConnections { get; set; } // 默认值为 0
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
    public int Timeout { get; set; } // 默认值为 0
}

// 场景 1：Timeout 为默认值 0
var settings1 = new Settings { MaxConnections = 10 };
string json1 = JsonSerializer.Serialize(settings1);
// 输出：{"MaxConnections":10}（Timeout 被忽略）

// 场景 2：Timeout 被显式赋值
var settings2 = new Settings { MaxConnections = 10, Timeout = 30 };
string json2 = JsonSerializer.Serialize(settings2);
// 输出：{"MaxConnections":10,"Timeout":30}

2. 全局设置 DefaultIgnoreCondition

通过 JsonSerializerOptions.DefaultIgnoreCondition 可为所有未显式标记的成员设置默认忽略规则。

通过设置 JsonSerializerOptions 类中的 DefaultIgnoreCondition 属性 来设置全局忽略规则

1）全局忽略默认值

public class Data
{
    public string Name { get; set; } // 默认值为 null
    public int Count { get; set; }   // 默认值为 0
}

var options = new JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault // 全局设置
};

// 场景：对象未初始化
var data = new Data();
string json = JsonSerializer.Serialize(data, options);
// 输出：{}（Name 和 Count 均被忽略，因为它们是默认值）

// 场景：显式赋值
var data2 = new Data { Name = "Test", Count = 5 };
string json2 = JsonSerializer.Serialize(data2, options);
// 输出：{"Name":"Test","Count":5}

2）全局忽略 null 值

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Password { get; set; }
}
class Program
{
    static void Main()
    {
        var options = new JsonSerializerOptions
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull // 全局设置
        };

        // 场景：对象未初始化
        var user = new User();
        string json = JsonSerializer.Serialize(user, options);
        Console.WriteLine(json);
        // 输出：{"Id":0}

        // 场景：显式赋值
        var user2 = new User { Id = 1, Name = "Test" };
        string json2 = JsonSerializer.Serialize(user2, options);
        Console.WriteLine(json2);
        // 输出：{"Id":1,"Name":"Test"}
    }
}

3）全局忽略与 [JsonIgnore] 特性 混合设置

public class User
{
    public int Id { get; set; }
    [JsonIgnore(Condition = JsonIgnoreCondition.Never)]// 始终忽略
    public string Name { get; set; }
    [JsonIgnore(Condition = JsonIgnoreCondition.Never)]// 始终忽略
    public string Password { get; set; }
}

class Program
{
    static void Main()
    {
        var options = new JsonSerializerOptions
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault // 全局设置
        };

        // 场景：对象未初始化
        var user = new User();
        string json = JsonSerializer.Serialize(user, options);
        Console.WriteLine(json);
        // 输出：{"Name":null,"Password":null}

        // 场景：显式赋值
        var user2 = new User { Id=1, Name = "Test"};
        string json2 = JsonSerializer.Serialize(user2, options);
        Console.WriteLine(json2);
        // 输出：{"Id":1,"Name":"Test","Password":null}
    }
}

4）优先级规则

  • 局部优先级：[JsonIgnore(Condition = ...)] 的设置会覆盖全局 DefaultIgnoreCondition。
  • 组合条件：多个条件（如 WhenWritingNull 和 WhenWritingDefault）可同时生效。

三、扩展

1. 忽略只读属性

通过 JsonSerializerOptions.IgnoreReadOnlyProperties 可全局忽略只读属性：

public class Book
{
    public string Title { get; set; }
    public int Pages { get; private set; } = 300; // 只读属性
}
class Program
{
    static void Main()
    {
        var options = new JsonSerializerOptions
        {
            IgnoreReadOnlyProperties = true // 忽略只读属性
        };

        var book = new Book { Title = "C# in Depth" };
        string json = JsonSerializer.Serialize(book, options);
        Console.WriteLine(json);
        // 输出：{"Title":"C# in Depth"}（Pages 被忽略）
    }
}

2. 与 JsonInclude 的配合

若需序列化非公共属性或字段，需结合 [JsonInclude] 特性：

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

    [JsonInclude]
    public int _age;
}
class Program
{
    static void Main()
    {
        var user = new User { Id = 1, Name = "Jack", Password = "121", _age = 12 };      
        
        string json = JsonSerializer.Serialize(user);
        Console.WriteLine(json);
        // 输出：{"Id":1,"Name":"Jack","Password":"121","_age":12}
    }
}

3. 同时忽略默认值和 null？

1）指定属性

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

    [JsonIgnore(Condition =JsonIgnoreCondition.WhenWritingDefault| JsonIgnoreCondition.WhenWritingNull)]
    public string Password { get; set; }
}

2）全局设置

var options = new JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull | JsonIgnoreCondition.WhenWritingDefault
};

四、实际应用

  • 场景 1：在 API 响应中，某些字段可能需要根据环境动态显示/隐藏（例如调试模式下包含 Age 属性）。
  • 场景 2：处理第三方 JSON 数据时，临时禁用 [JsonIgnore] 标记以兼容旧版接口。

通过灵活配置 DefaultIgnoreCondition，可以精准控制序列化的输出内容，提升代码的灵活性和可维护性。

结语

回到目录页：C#/.NET 知识汇总
希望以上内容可以帮助到大家，如文中有不对之处，还请批评指正。

http://www.dtcms.com/a/106628.html

相关文章：

  • Linux2 CD LL hostnamectl type mkdir dudo
  • 跨系统平台实践：在内网自建kylin服务版系统yum源
  • 面基JavaEE银行金融业务逻辑层处理金融数据类型BigDecimal
  • AI提示词：好评生成器
  • 鸿蒙NEXT小游戏开发：数字华容道
  • 详解相机的内参和外参，以及内外参的标定方法
  • 背包DP总结
  • GO语言 使用protobuf
  • 【第十三届“泰迪杯”数据挖掘挑战赛】【2025泰迪杯】【代码篇】A题解题全流程（持续更新）
  • 全国产ADC 16bit 2通道1G采样 双FMC子板
  • C++多继承
  • 【抓包工具】win 10 / win 11：Charles 下载、安装、配置（快捷方式、默认端口、登录、https 证书）
  • 【git】VScode修改撤回文件总是出现.lh文件，在 ​所有 Git 项目 中全局忽略特定文件
  • MacOS 的 AI Agent 新星，本地沙盒驱动，解锁 macOS 操作新体验！
  • 地表-地下水系统交互模拟关键技术突破：SWAT-MODFLOW耦合模型构建、验证及多情景预测研究
  • 离线语音识别 （ 小语种国家都支持）可定制词组
  • 项目管理管什么？理什么？
  • 《云端都市：云计算如何重塑未来城市形态》
  • spikingjelly：使用单层全连接 SNN 识别 MNIST
  • Java UnsupportedOperationException 深度解析及解决方案
  • 在HarmonyOS NEXT 开发中，如何指定一个号码，拉起系统拨号页面
  • Python从入门到精通4：计算机网络及TCP网络应用程序开发入门指南
  • JuiceFS vs HDFS，最简单的 JuiceFS 入门
  • Muduo网络库实现 [八] - Acceptor模块
  • 【Harmony OS】TypeScrip基础
  • 小米汽车就 SU7 事故回应六点问题，称「事故车起火并非自燃」、「无法分析车门能否打开」，如何看待？
  • 从头开发一个Flutter插件（二）高德地图定位插件
  • [GESP 202503 二级 T2] 时间跨越
  • Docker 镜像导出与导入：export/import vs save/load
  • AI战略群与星际之门：软银AI投资版图计划深度解析