asp.net json教程

ASP.NET JSON 完整教程

JSON (JavaScript Object Notation) 是一种轻量级的数据交换格式，因其易于人阅读和编写，也易于机器解析和生成，已成为 Web 开发中事实上的标准，在 ASP.NET 中，处理 JSON 是一项核心技能，主要用于前后端数据交互。

本教程将分为以下几个部分：

1. JSON 基础回顾
2. ASP.NET Web API 中的 JSON 处理 (传统 .NET Framework)
3. ASP.NET Core 中的 JSON 处理 (现代推荐)
4. 高级主题与最佳实践
5. 总结与资源

---

第一部分：JSON 基础回顾

在深入代码之前,我们先快速回顾一下 JSON 的基本结构。

• 数据结构：键值对集合。
• 语法规则：
  • 数据在键值对中
  • 键名使用双引号 包裹
  • 值可以是字符串（双引号）、数字、布尔值 (true/false)、数组 ([])、对象 () 或 null
  • 数据由逗号 分隔
  • 花括号 保存对象
  • 方括号 [] 保存数组

示例 JSON 对象：

{
  "name": "John Doe",
  "age": 30,
  "isStudent": false,
  "courses": [
    { "title": "History", "credits": 3 },
    { "title": "Math", "credits": 4 }
  ],
  "address": null
}

---

第二部分：ASP.NET Web API 中的 JSON 处理 (.NET Framework)

在传统的 ASP.NET Web API 中，JSON 的处理主要通过 System.Web.Http 命名空间下的类来完成。

序列化：将 C# 对象转为 JSON

当你的 API 控制器返回一个对象时，Web API 的格式化器会自动将其序列化为 JSON 并返回给客户端。

示例：创建一个简单的 API 控制器

using System.Web.Http;
using System.Web.Http.Cors; // 启用跨域支持
// 启用跨域请求，方便前端调试
[EnableCors(origins: "*", headers: "*", methods: "*")]
public class ProductsController : ApiController
{
    // GET api/products
    public IHttpActionResult GetProducts()
    {
        var products = new List<Product>
        {
            new Product { Id = 1, Name = "Laptop", Price = 1200.50m, Category = "Electronics" },
            new Product { Id = 2, Name = "Coffee Mug", Price = 15.99m, Category = "Home Goods" }
        };
        // Web API 会自动将这个 List<Product> 序列化为 JSON 数组
        return Ok(products);
    }
    // GET api/products/5
    public IHttpActionResult GetProduct(int id)
    {
        var product = new Product { Id = id, Name = "Product " + id, Price = 100.00m, Category = "General" };
        // Web API 会自动将这个 Product 对象序列化为 JSON 对象
        return Ok(product);
    }
}
// 定义一个简单的 C# 模型类
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Category { get; set; }
}

当你访问 api/products 时，你会得到如下 JSON 响应：

[
  {
    "Id": 1,
    "Name": "Laptop",
    "Price": 1200.50,
    "Category": "Electronics"
  },
  {
    "Id": 2,
    "Name": "Coffee Mug",
    "Price": 15.99,
    "Category": "Home Goods"
  }
]

反序列化：将 JSON 转为 C# 对象

当客户端向你的 API 发送 POST 或 PUT 请求并携带 JSON 数据时，你需要将这些数据反序列化为 C# 对象。

Web API 默认会使用 JsonMediaTypeFormatter 自动完成这个过程，你只需要在 Action 方法的参数中定义一个对应的 C# 类即可。

示例：接收 JSON 数据

// POST api/products
public IHttpActionResult PostProduct(Product product)
{
    if (product == null)
    {
        return BadRequest("Product data is null.");
    }
    // 在这里处理 product 对象，例如保存到数据库
    // product.Id = someDatabaseService.Create(product);
    // 返回 201 Created 状态码和创建的资源
    return Created<Product>(Request.RequestUri + "/" + product.Id, product);
}

客户端发送如下 JSON 请求体：

{
  "Name": "Wireless Mouse",
  "Price": 25.75,
  "Category": "Electronics"
}

Web API 会自动将其反序列化为 Product 类的实例，并传递给 PostProduct 方法。

手动序列化/反序列化

虽然自动处理很方便,但有时你可能需要手动控制。

using System.Web.Script.Serialization; // 需要引用 System.Web.Extensions
// 手动序列化
var product = new Product { Id = 1, Name = "Manual Product" };
var js = new JavaScriptSerializer();
string jsonString = js.Serialize(product);
// jsonString 结果: '{"Id":1,"Name":"Manual Product"}'
// 手动反序列化
string receivedJson = "{\"Id\":3,\"Name\":\"Received Product\"}";
Product deserializedProduct = js.Deserialize<Product>(receivedJson);
// deserializedProduct.Name 是 "Received Product"

注意: JavaScriptSerializer 功能相对有限，且已过时，在 .NET Framework 项目中，更推荐使用 Newtonsoft.Json (Json.NET) 库，它更强大、更灵活。

---

第三部分：ASP.NET Core 中的 JSON 处理 (现代推荐)

ASP.NET Core 对 JSON 的处理进行了优化，默认使用高性能的 System.Text.Json 库，并提供了对 Newtonsoft.Json 的原生支持。

默认行为：System.Text.Json

在 ASP.NET Core 中，默认情况下，当你返回一个对象或接收一个 JSON 请求体时，框架会自动使用 System.Text.Json 进行序列化和反序列化。

示例：一个简单的 ASP.NET Core 控制器

using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class ProductsCoreController : ControllerBase
{
    // GET api/productscore
    [HttpGet]
    public ActionResult<IEnumerable<Product>> GetProducts()
    {
        var products = new List<Product>
        {
            new Product { Id = 1, Name = "Laptop", Price = 1200.50m }
        };
        return Ok(products); // 自动序列化为 JSON
    }
    // POST api/productscore
    [HttpPost]
    public ActionResult<Product> PostProduct([FromBody] Product product)
    {
        if (product == null)
        {
            return BadRequest();
        }
        // 在这里处理 product 对象...
        // product.Id = 1; // 假设已创建
        // 返回 201 Created
        return CreatedAtAction(nameof(GetProduct), new { id = product.Id }, product);
    }
    // GET api/productscore/5
    [HttpGet("{id}")]
    public ActionResult<Product> GetProduct(int id)
    {
        var product = new Product { Id = id, Name = "Product " + id };
        return Ok(product);
    }
}
// C# 模型类
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

配置 JSON 选项

你可以在 Program.cs (或 Startup.cs) 中配置 JSON 的行为，例如处理循环引用、命名策略等。

// Program.cs (ASP.NET 6+)
var builder = WebApplication.CreateBuilder(args);
// 添加服务到容器
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 1. 使用驼峰命名法 (camelCase) 输出 JSON 属性名
        options.JsonSerializerOptions.PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase;
        // 2. 允许循环引用 (默认会抛出异常)
        // options.JsonSerializerOptions.ReferenceHandler = System.Text.Json.ReferenceHandler.Preserve; 
        // 3. 忽略 null 值
        // options.JsonSerializerOptions.DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull;
    });
var app = builder.Build();
// ... (中间件配置)
app.MapControllers();
app.Run();

手动序列化/反序列化

using System.Text.Json;
// 手动序列化
var product = new Product { Id = 1, Name = "Manual Product" };
string jsonString = JsonSerializer.Serialize(product);
// jsonString 结果: '{"id":1,"name":"Manual Product"}' (受命名策略影响)
// 手动反序列化
string receivedJson = "{\"id\":3,\"name\":\"Received Product\"}";
Product deserializedProduct = JsonSerializer.Deserialize<Product>(receivedJson);
// deserializedProduct.Name 是 "Received Product"

使用 Newtonsoft.Json (Json.NET)

如果你习惯了 Newtonsoft.Json 或者需要使用它特有的功能（如 [JsonProperty] 特性），可以轻松切换。

步骤 1: 安装 NuGet 包

dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson

步骤 2: 在 Program.cs 中注册服务

// Program.cs
var builder = WebApplication.CreateBuilder(args);
// 添加 NewtonSoft.Json 支持
builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        // 配置选项，例如驼峰命名法
        options.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver();
    });
// ... 其余代码

步骤 3: 使用 Newtonsoft.Json 特性 现在你可以在你的模型类中使用 Newtonsoft.Json 的特性了。

using Newtonsoft.Json;
public class Product
{
    [JsonProperty("product_id")]
    public int Id { get; set; }
    public string Name { get; set; }
    // [JsonIgnore] // 如果你想忽略这个属性
    public decimal Price { get; set; }
}

---

第四部分：高级主题与最佳实践

循环引用

当对象之间相互引用时（Order 包含一个 Customer，而 Customer 又有一个 Orders 列表），序列化时会进入无限循环，导致 StackOverflowException。

解决方案：

• ASP.NET Web API (Newtonsoft.Json):

  // 在 Global.asax 或 WebApiConfig 中配置
  GlobalConfiguration.Configuration.Formatters.JsonFormatter.SerializerSettings.ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Ignore;

• ASP.NET Core (System.Text.Json):

  // 在 Program.cs 中配置
  builder.Services.AddControllers().AddJsonOptions(options =>
  {
      options.JsonSerializerOptions.ReferenceHandler = System.Text.Json.ReferenceHandler.Preserve;
      // 或者使用 Ignore 来忽略循环引用的属性
      // options.JsonSerializerOptions.ReferenceHandler = System.Text.Json.ReferenceHandler.IgnoreCycles;
  });

大小写与命名策略

前端 JavaScript 通常使用驼峰命名法 (camelCase)，而 C# 约定使用帕斯卡命名法 (PascalCase)，最佳实践是让后端自动进行转换。

• ASP.NET Core (System.Text.Json): 如上所示，在 AddJsonOptions 中设置 PropertyNamingPolicy = JsonNamingPolicy.CamelCase。
• ASP.NET Web API (Newtonsoft.Json): 使用 CamelCasePropertyNamesContractResolver。

数据注解

使用数据注解可以更精细地控制 JSON 的生成。

• [JsonIgnore]: 忽略此属性，不参与序列化/反序列化。
• [JsonProperty("new_name")] (Newtonsoft.Json) / [JsonPropertyName("new_name")] (System.Text.Json): 指定 JSON 中的属性名。
• [Required]: 确保反序列化时该字段存在。

性能考虑

• System.Text.Json: .NET Core 3.0+ 引入，是微软官方的高性能 JSON 库，内存占用低，速度快，如果你的项目不需要 Newtonsoft.Json 的特定功能，应优先使用它。
• Newtonsoft.Json (Json.NET): 功能非常丰富，拥有庞大的生态系统，但在纯 .NET Core 性能上略逊于 System.Text.Json。

---

第五部分：总结与资源

特性	ASP.NET Web API (.NET Framework)	ASP.NET Core
默认 JSON 库	System.Web.Http 内置 (基于 JavaScriptSerializer)	System.Text.Json
推荐库	Newtonsoft.Json (Json.NET)	System.Text.Json (或 Newtonsoft.Json)
配置方式	GlobalConfiguration.Configuration.Formatters.JsonFormatter...	builder.Services.AddControllers().AddJsonOptions(...)
跨域支持	[EnableCors] 特性	[EnableCors] 特性
循环引用处理	ReferenceLoopHandling.Ignore	ReferenceHandler.Preserve 或 IgnoreCycles

推荐资源

1. 官方文档:

   • ASP.NET Core 中的 Web API
   • 在 .NET 中使用 System.Text.Json
   • ASP.NET Web API 2

2. NuGet 包:

   • Newtonsoft.Json
   • Microsoft.AspNetCore.Mvc.NewtonsoftJson

3. 在线工具:

   • JSONLint: 验证 JSON 格式。
   • JSON to C# Class Generator: 快速将 JSON 字符串生成 C# 类。

希望这份详细的教程能帮助你全面掌握 ASP.NET 中的 JSON 处理！