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

于 2025-04-03 22:00:00 发布
阅读量905 收藏 14
点赞数 13
分类专栏： C# 文章标签： c# json 开发语言 microsoft
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/qq_39847278/article/details/146982027
版权

总目录

一、JsonNamingPolicy 是什么？

1. 定义

JsonNamingPolicy 是 System.Text.Json 中用于 控制属性名称在序列化/反序列化时的命名格式的策略类。它允许开发者将 .NET 对象的属性名称转换为指定的格式（如 camelCase、snake_case 等），或自定义其他命名规则。

JsonNamingPolicy 是 System.Text.Json 命名空间中的一个类，用于定义如何在序列化和反序列化过程中处理属性名称与 JSON 字段名称之间的映射关系。

  • 通过使用 JsonNamingPolicy，开发者可以自定义 JSON 字段的命名约定，例如将 C# 中的驼峰命名约定转换为 JSON 中的蛇形命名约定，或者反之。
  • JsonNamingPolicy 通过重写 ConvertName 方法来实现名称转换逻辑。在序列化过程中，ConvertName 方法接收 C# 属性名称并返回 JSON 字段名称；在反序列化过程中，它接收 JSON 字段名称并返回 C# 属性名称。这种双向映射机制确保了在序列化和反序列化过程中名称转换的一致性。

2. 核心作用

  • 序列化时：将 C# 属性名转换为指定格式（如 PascalCase → camelCase）。
  • 反序列化时：将 JSON 中的键名转换为对象的属性名。
  • 命名优先级：显式标记 [JsonPropertyName] 的属性优先级高于命名策略。

3. 适用场景

JsonNamingPolicy 是 System.Text.Json 中 控制属性名称格式的核心工具，适用于以下场景：

  • 适配前后端命名规范（如 C# 的 PascalCase 转为前端的 camelCase）。
  • 统一 API 接口的键名格式（如 snake_case）。
  • 自定义特殊命名规则（如添加前缀/后缀）。

通过内置策略或自定义实现，开发者可以灵活控制 JSON 的属性名称，确保与外部系统的兼容性及代码的可维护性。

二、内置命名策略

System.Text.Json 提供了多种内置命名策略，以满足不同的命名约定需求：

1. 默认策略

默认情况下，无策略（null） ，即保留原始属性名（如 UserName → UserName）。

不过通常在 C# 中 属性会遵守PascalCase 命名策略

public class User
{
    public string UserName { get; set; }
    public int UserAge { get; set; }
}
class Program
{
    static void Main()
    {
        var user = new User { UserName = "John", UserAge = 15 };
        
        // 序列化
        string json = JsonSerializer.Serialize(user);
        Console.WriteLine(json);
        // 输出：{"UserName":"John","UserAge":15}

        // 反序列化
        string jsonString = """{"UserName":"John","UserAge":15}""";
        var u= JsonSerializer.Deserialize<User>(jsonString);
        Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
        // 输出：UserName = John ,UserAge = 15
    }
}

2. CamelCase

JsonNamingPolicy.CamelCase 策略将 PascalCase 的 C# 属性名称转换为 camelCase 的 JSON 字段名称。例如，PublicProperty 将被转换为 “publicProperty”。

public class User
{
    public string UserName { get; set; }
    public int UserAge { get; set; }
}
class Program
{
    static void Main()
    {
        var user = new User { UserName = "John", UserAge = 15 };

        var options = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        };
        // 序列化
        string json = JsonSerializer.Serialize(user,options);
        Console.WriteLine(json);
        // 输出：{"userName":"John","userAge":15}

        // 反序列化
        string jsonString = """{"userName":"John","userAge":15}""";
        var u= JsonSerializer.Deserialize<User>(jsonString);
        Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
        // 输出：UserName =  ,UserAge = 0

        var u2 = JsonSerializer.Deserialize<User>(jsonString,options);
        Console.WriteLine($"UserName = {u2.UserName} ,UserAge = {u2.UserAge}");
        // 输出：UserName = John ,UserAge = 15
    }
}

注意：序列化和反序列化的时候需要保持使用一致的命名策略，否则就会出现如上案例所示的问题

3. SnakeCaseLower/SnakeCaseUpper

  • JsonNamingPolicy.SnakeCaseLower 策略将 PascalCase 的 C# 属性名称转换为 snake_case 的 JSON 字段名称，并且字段名称为小写。例如，PublicProperty 将被转换为 “public_property”。
  • JsonNamingPolicy.SnakeCaseUpper 策略将 PascalCase 的 C# 属性名称转换为 SNAKE_CASE 的 JSON 字段名称，并且字段名称为大写。例如，PublicProperty 将被转换为 “PUBLIC_PROPERTY”。
public class User
{
    public string UserName { get; set; }
    public int UserAge { get; set; }
}
class Program
{
    static void Main()
    {
        var user = new User { UserName = "John", UserAge = 15 };

        var options = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper
        };

        var options2 = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
        };

        // 序列化
        string json = JsonSerializer.Serialize(user,options);
        Console.WriteLine(json);
        // 输出：{"USER_NAME":"John","USER_AGE":15}

        json = JsonSerializer.Serialize(user, options2);
        Console.WriteLine(json);
        // 输出：{"user_name":"John","user_age":15}


        // 反序列化
        string jsonString = """{"USER_NAME":"John","USER_AGE":15}""";
        var u= JsonSerializer.Deserialize<User>(jsonString,options);
        Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
        // 输出：UserName = John ,UserAge = 15
    }
}

4. KebabCaseUpper/KebabCaseLower

  • JsonNamingPolicy.KebabCaseLower 策略将 PascalCase 的 C# 属性名称转换为 kebab-case 的 JSON 字段名称，并且字段名称为小写。例如，UserName 将被转换为 “user-name”。
  • JsonNamingPolicy.KebabCaseUpper 策略将 PascalCase 的 C# 属性名称转换为 KEBAB_CASE 的 JSON 字段名称，并且字段名称为大写。例如，UserName 将被转换为 “USER-NAME”。
public class User
{
    public string UserName { get; set; }
    public int UserAge { get; set; }
}
class Program
{
    static void Main()
    {
        var user = new User { UserName = "John", UserAge = 15 };

        var options = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.KebabCaseUpper
        };

        var options2 = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.KebabCaseLower
        };

        // 序列化
        string json = JsonSerializer.Serialize(user,options);
        Console.WriteLine(json);
        // 输出：{"USER-NAME":"John","USER-AGE":15}

        json = JsonSerializer.Serialize(user, options2);
        Console.WriteLine(json);
        // 输出：{"user-name":"John","user-age":15}


        // 反序列化
        string jsonString = """{"USER-NAME":"John","USER-AGE":15}""";
        var u= JsonSerializer.Deserialize<User>(jsonString,options);
        Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
        // 输出：UserName = John ,UserAge = 15
    }
}

5. 示例：内置策略与 WriteIndented 配合使用

JsonNamingPolicy 不仅可以处理简单的对象，还可以处理包含嵌套对象和集合的复杂对象图。命名策略会递归地应用于对象图中的所有对象。

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public Address Address { get; set; }
}
public class Address
{
    public string Street { get; set; }
    public string City { get; set; }
    public List<PhoneNumber> PhoneNumbers { get; set; }
}
public class PhoneNumber
{
    public string Type { get; set; }
    public string Number { get; set; }
}
var person = new Person
{
    FirstName = "John",
    LastName = "Doe",
    Address = new Address
    {
        Street = "123 Main St",
        City = "New York",
        PhoneNumbers = new List<PhoneNumber>
        {
            new PhoneNumber { Type = "home", Number = "555-1234" },
            new PhoneNumber { Type = "work", Number = "555-5678" }
        }
    }
};
var options = new JsonSerializerOptions
{
    NamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
string json = JsonSerializer.Serialize(person, options);
// 输出:
//{
//  "firstName": "John",
//  "lastName": "Doe",
//  "address": {
//    "street": "123 Main St",
//    "city": "New York",
//    "phoneNumbers": [
//      {
//        "type": "home",
//        "number": "555-1234"
//      },
//      {
//        "type": "work",
//        "number": "555-5678"
//      }
//    ]
//  }
//}

三、自定义命名策略

除了内置的命名策略外，System.Text.Json 还允许开发者创建自定义的命名策略，以满足特定的命名转换需求。要创建自定义命名策略，需要创建一个继承自 JsonNamingPolicy 的类，并重写 ConvertName 方法。

1. 创建并使用自定义命名策略

1）创建自定义命名策略

通过继承 JsonNamingPolicy 并重写 ConvertName 方法，可以实现自定义的命名规则。

public class AllUppercaseNamingPolicy : JsonNamingPolicy
{
    public override string ConvertName(string name)
    {
        return name.ToUpper();
    }
}

在上述示例中，AllUppercaseNamingPolicy 类将所有属性名称转换为全大写。

2）使用自定义命名策略

要使用这个自定义策略，可以将其配置到 JsonSerializerOptions 中：

public class User
{
    public string UserName { get; set; }
    public int UserAge { get; set; }
}
class Program
{
    static void Main()
    {
        var user = new User { UserName = "John", UserAge = 15 };

        var options = new JsonSerializerOptions
        {
            PropertyNamingPolicy = new AllUppercaseNamingPolicy()
        };

        // 序列化
        string json = JsonSerializer.Serialize(user,options);
        Console.WriteLine(json);
        // 输出：{"USERNAME":"John","USERAGE":15}

        // 反序列化
        string jsonString = """{"USERNAME":"John","USERAGE":15}""";
        var u= JsonSerializer.Deserialize<User>(jsonString,options);
        Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
        // 输出：UserName = John ,UserAge = 15
    }
}

2. 自定义命名策略处理命名冲突

在某些情况下，JSON 字段名称可能与 C# 属性名称不匹配，或者存在命名冲突。通过创建自定义的命名策略，可以解决这些问题。

public class CustomNamingPolicy : JsonNamingPolicy
{
    public override string ConvertName(string name)
    {
        // 处理特定的命名转换
        if (name == "CreatedDate")
            return "created_at";
        
        // 对于其他属性，使用默认的 PascalCase 到 snake_case 转换
        return name.Replace(" ", "_").ToLower();
    }
}

四、字典键的命名策略（DictionaryKeyPolicy）

通过 JsonSerializerOptions.DictionaryKeyPolicy，可以控制 字典键名的格式。
示例：字典键转为驼峰命名

class Program
{
    static void Main()
    {
        var dictionary = new Dictionary<string, string>
        {
            ["UserName"] = "John",
            ["UserPwd"] = "123"
        };

        var options = new JsonSerializerOptions
        {
            DictionaryKeyPolicy = JsonNamingPolicy.CamelCase // 字典键转为 camelCase
        };

        string json = JsonSerializer.Serialize(dictionary, options);
        Console.WriteLine(json); //输出：{"userName":"John","userPwd":"123"}

        var options2 = new JsonSerializerOptions
        {
            DictionaryKeyPolicy = new CustomCamelCasePolicy()
        };
        json = JsonSerializer.Serialize(dictionary, options2);
        Console.WriteLine(json); //输出：{"userName":"John","userPwd":"123"}
    }
}

public class CustomCamelCasePolicy : JsonNamingPolicy
{
    public override string ConvertName(string name)
    {
        return  char.ToLower(name[0]) + name.Substring(1);
    }
}

五、与 JsonPropertyName 特性结合

JsonPropertyNameAttribute 的优先级高于 JsonNamingPolicy，可覆盖命名策略。

public class Product
{
    [JsonPropertyName("product_id")] // 显式指定名称
    public int Id { get; set; }
    public string Name { get; set; } // 使用命名策略
}

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

var product = new Product { Id = 1, Name = "Laptop" };
string json = JsonSerializer.Serialize(product, options);
// 输出：{"product_id":1,"name":"Laptop"}（Name 转为 name）

六、命名策略的注意事项

在使用 JsonNamingPolicy 时，需要注意以下几点：

  1. 策略一致性：在序列化和反序列化过程中，应使用相同的命名策略，以确保名称映射的一致性。

    // 序列化时使用驼峰命名
var serializedJson = JsonSerializer.Serialize(user, options); // 输出 {"userName":"Alice"}

// 反序列化时需使用相同策略
var deserializedUser = JsonSerializer.Deserialize<User>(serializedJson, options);
// 成功匹配属性

  2. 性能考虑：使用命名策略可能会对性能产生轻微的影响，因为需要进行额外的字符串转换操作。对于性能敏感的应用

    • 可以考虑优化名称转换逻辑。
    • 避免频繁创建 JsonSerializerOptions：如果命名策略是固定的，可以创建一个静态的 JsonSerializerOptions 实例，并在应用程序中复用它。

  3. 忽略大小写：默认情况下，System.Text.Json 在反序列化过程中是大小写敏感的。如果需要进行大小写不敏感的匹配，可以设置 PropertyNameCaseInsensitive 选项为 true。

    var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true
};

结语

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

参考资料：

.NET ASP.NET C#中JSON详解
qq_43434300的博客
05-07 1812
JSON AJAX传递复杂数据如果自己进行格式定义的话会经历组装、解析的过程，因此AJAX中有一个事实上的数据传输标准JSon。Json（是一个标准，就像XML一样，Json规定了对象以什么样的格式保存为一个字符串）将复杂对象序列化为一个字符串，在浏览器端再将字符串反序列化为JavaScript可以读取的对象。看一下Json的格式。Json被几乎所有语言支持。 C#中将.Net对象序列化为Json...
JSON序列化-System.Text.Json
ceclar123的专栏
08-18 971
JSON序列化，System.Text.Json
C# System.Text.Json 中 JsonConverter 使用详解
最新发布
鲤籽鲲的博客
04-03 966
C# System.Text.Json 中 JsonConverter 使用详解
C# System.Text.Json 中 JsonIgnoreCondition 使用详解
鲤籽鲲的博客
04-02 1342
C# System.Text.Json 中 JsonIgnoreCondition 使用详解
C# System.Text.Encoding 使用详解
鲤籽鲲的博客
03-21 992
C# System.Text.Encoding 使用详解
C# 解析JSON详解
热门推荐
一名热爱技术的工程师的博客。分享技术干货，记录美好生活。永远相信美好的事情即将发生。
09-26 1万+
JSON的全称是，是一种轻量级的数据交换格式，主要用于数据的序列化和交互。
C# Newtonsoft.Json库使用详解
记录点滴
03-14 620
可以通过实现来自定义序列化和反序列化逻辑。set;set;get;set;get;set;// 创建一个Person对象 Person person = new Person {// 使用自定义的PersonConverter进行序列化 string json = JsonConvert . SerializeObject(person , new PersonConverter());// 输出JSON字符串 Console . WriteLine(json);
使用Newtonsoft.Json.dll进行.NET JSON处理
weixin_42186015的博客
09-11 1394
本文还有配套的精品资源，点击获取 简介：Newtonsoft.Json.dll 是.NET开发中处理JSON数据的核心库，支持多种.NET版本。它提供了强大的序列化和反序列化功能，以及灵活的动态解析、自定义序列化选项和LINQ to JSON支持。还具有异步操作、嵌套JSON处理能力，并在WebAPI和MVC应用中集成良好。通过丰富的API和性能优化手段，Newtonsof...
c# timer 销毁_C# System.Timers.Timer定时器的使用和定时自动清理内存应用
weixin_28728443的博客
12-24 2311
项目比较大有时候会比较卡，虽然有GC自动清理机制，但是还是有不尽人意的地方。所以尝试在项目启动文件中，手动写了一个定时器，定时清理内存，加快项目运行速度。public class Program{[DllImport("psapi.dll")]static extern int EmptyWorkingSet(IntPtr hwProc); //清理内存相关static void Main(){/...
C#使用Newtonsoft.Json操作JSON详解
System.Runtime.Serialization.dll提供了基本的序列化功能，而System.Web.Extensions.dll则主要在Web项目中使用，用于处理ASP.NET相关的JSON操作。然而，有一个限制需要注意，即System.Web.Extensions.dll只能在Web...
Newtonsoft.Json.dll
03-11
它在Unity引擎中广泛使用，因为Unity支持C#编程，而`Newtonsoft.Json`库提供了强大的JSON序列化和反序列化功能，使得在Unity项目中处理JSON数据变得简单而高效。 **JSON（JavaScript Object Notation）** JSON是一...
基于 C# 开发 SQL Server 数据库应用：深入解析与实战指南
zhu1996zhu的博客
04-01 1548
本文围绕基于C#开发SQL Server数据库应用展开，详述开发环境准备，重点呈现数据库连接、查询、插入、更新及删除操作的专业代码示例，还提及可优化方向，助力开发者掌握相关技能，为用C#开发此类数据库应用提供全面实用的参考。
c# 获取redis中所有的value
A_nanda的博客
03-31 831
通过上述代码，可安全高效地获取 Redis 中所有键的值，并根据需要扩展对不同数据类型的支持。// 使用 SCAN 分页遍历键（避免 KEYS * 的性能问题）// 仅获取字符串类型的值（按需扩展其他类型）/// 安全获取所有键的值（分页扫描模式，避免阻塞 Redis）/// 高性能批量获取字符串值（Pipeline 优化）：全量扫描操作（即使分页）仍可能影响性能，建议在低峰期执行。分页遍历键，减少对 Redis 的阻塞风险。// 方法2：批量获取指定键。// 方法1：安全分页扫描。
C#里第一个WPF程序
大坡3D软件开发
04-03 92
WPF程序对界面进行优化，但是比WINFORMS的程序要复杂很多，并且界面UI基本上不适合拖放，所以需要比较多的时间来布局界面，随着客户对界面的需求提高，还是需要采用这样的方式来实现。产且需要开发人员编写更多的代码。即使如此，在面对诱人的界面表现，App.xaml文件中定义。从这几堆代码来看，就比较多。
C# 从代码创建选型卡+表格
TrueLink的博客
04-03 86
【代码】C# 从代码创建选型卡+表格。
Win10定时任务计划无法显示要执行的EXE任务程序界面，问题解决办法
luckyext的博客
04-03 239
Win10定时任务计划无法显示要执行的EXE任务程序界面，问题解决办法。用C#开发的一款WINFORM程序，在电脑测试一切顺利，运行结果正确。但用电脑的定时任务执行时，程序界面不显示，重启电脑、各种试都不行，最终问题解决。
贤小二c#版Yolov5 yolov8 yolov10 yolov11自动标注工具 + 免python环境 GPU一键训练包
wuminghang的专栏
04-03 166
Yolov5 Yolov8 Yolov10 Yolov11 自动标注训练工具 ， 免python环境 GPU一键训练包，c#开发 ，完全免费 下载地址：https://pan.baidu.com/s/11PD2ln4xqiMzpS2uZ2mfyg?pwd=1828
C# System.Net.Dns 使用详解
鲤籽鲲的博客
03-31 772
C# System.Net.Dns 使用详解
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

鲤籽鲲

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值