语言
不可变 类型 是阻止在实例化对象后更改对象的任何属性或字段值。 该类型可以是记录、没有公共属性或字段、具有只读属性,或者包含具有专用资源库或仅初始化资源库的属性。 System.String 是不可变类型的一个示例。 System.Text.Json 提供了将 JSON 反序列化为不可变类型的不同方法。
参数化构造函数
默认情况下,System.Text.Json 使用默认的公共无参数构造函数。 但是,可以告诉它使用参数化构造函数,这样就可以反序列化不可变类或结构。
对于类,如果唯一的构造函数是参数化构造函数,将使用该构造函数。
对于结构或具有多个构造函数的类,请通过应用 [JsonConstructor] 属性来指定要使用的结构。 如果未使用该属性,则始终使用公共无参数构造函数(如果存在)。
以下示例使用
[JsonConstructor]属性:using System.Text.Json; using System.Text.Json.Serialization; namespace ImmutableTypes { public struct Forecast { public DateTime Date { get; } public int TemperatureC { get; } public string Summary { get; } [JsonConstructor] public Forecast(DateTime date, int temperatureC, string summary) => (Date, TemperatureC, Summary) = (date, temperatureC, summary); } public class Program { public static void Run() { string json = """ { "date":"2020-09-06T11:31:01.923395-07:00", "temperatureC":-1, "summary":"Cold" } """; Console.WriteLine($"Input JSON: {json}"); var options = JsonSerializerOptions.Web; Forecast forecast = JsonSerializer.Deserialize<Forecast>(json, options); Console.WriteLine($"forecast.Date: {forecast.Date}"); Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}"); Console.WriteLine($"forecast.Summary: {forecast.Summary}"); string roundTrippedJson = JsonSerializer.Serialize<Forecast>(forecast, options); Console.WriteLine($"Output JSON: {roundTrippedJson}"); } } } // Produces output like the following example: // //Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"} //forecast.Date: 9 / 6 / 2020 11:31:01 AM //forecast.TemperatureC: -1 //forecast.Summary: Cold //Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}Imports System.Text.Json Imports System.Text.Json.Serialization Namespace ImmutableTypes Public Structure Forecast Public ReadOnly Property [Date] As Date Public ReadOnly Property TemperatureC As Integer Public ReadOnly Property Summary As String <JsonConstructor> Public Sub New([Date] As Date, TemperatureC As Integer, Summary As String) Me.Date = [Date] Me.TemperatureC = TemperatureC Me.Summary = Summary End Sub End Structure Public NotInheritable Class Program Public Shared Sub Main() Dim json As String = "{""date"":""2020-09-06T11:31:01.923395-07:00"",""temperatureC"":-1,""summary"":""Cold""}" Console.WriteLine($"Input JSON: {json}") Dim forecast1 As Forecast = JsonSerializer.Deserialize(Of Forecast)(json, JsonSerializerOptions.Web) Console.WriteLine($"forecast.Date: {forecast1.[Date]}") Console.WriteLine($"forecast.TemperatureC: {forecast1.TemperatureC}") Console.WriteLine($"forecast.Summary: {forecast1.Summary}") Dim roundTrippedJson As String = JsonSerializer.Serialize(forecast1, JsonSerializerOptions.Web) Console.WriteLine($"Output JSON: {roundTrippedJson}") End Sub End Class End Namespace ' Produces output like the following example: ' 'Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"} 'forecast.Date: 9 / 6 / 2020 11:31:01 AM 'forecast.TemperatureC: -1 'forecast.Summary: Cold 'Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}在 .NET 7 和更早版本中,
[JsonConstructor]属性只能与公共构造函数一起使用。
在 .NET 8 及更高版本中,反射模式支持标记为[JsonConstructor]非公共构造函数。 从 .NET 11 开始,源生成模式也支持它们。
参数化构造函数的参数名称必须与属性名称和类型匹配。 匹配不区分大小写,即使使用 [JsonPropertyName] 重命名属性,构造函数参数也必须与实际属性名称匹配。 在以下示例中,TemperatureC 属性的名称更改为 JSON 中的 celsius,但构造函数参数仍命名为 temperatureC:
using System.Text.Json;
using System.Text.Json.Serialization;
namespace ImmutableTypesCtorParms
{
public readonly struct Forecast
{
public DateTime Date { get; }
[JsonPropertyName("celsius")]
public int TemperatureC { get; }
public string Summary { get; }
[JsonConstructor]
public Forecast(DateTime date, int temperatureC, string summary) =>
(Date, TemperatureC, Summary) = (date, temperatureC, summary);
}
public class Program
{
public static void Run()
{
string json = """
{
"date":"2020-09-06T11:31:01.923395-07:00",
"celsius":-1,
"summary":"Cold"
}
""";
Console.WriteLine($"Input JSON: {json}");
var options = JsonSerializerOptions.Web;
Forecast forecast = JsonSerializer.Deserialize<Forecast>(json, options);
Console.WriteLine($"forecast.Date: {forecast.Date}");
Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}");
Console.WriteLine($"forecast.Summary: {forecast.Summary}");
string roundTrippedJson =
JsonSerializer.Serialize<Forecast>(forecast, options);
Console.WriteLine($"Output JSON: {roundTrippedJson}");
}
}
}
// Produces output like the following example:
//
//Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","celsius":-1,"summary":"Cold"}
//forecast.Date: 9 / 6 / 2020 11:31:01 AM
//forecast.TemperatureC: -1
//forecast.Summary: Cold
//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","celsius":-1,"summary":"Cold"}
除了 [JsonPropertyName],以下属性还支持使用参数化构造函数进行反序列化:
按引用构造函数参数
从 .NET 11 开始,
| 参数修饰符 | 反序列化行为 |
|---|---|
in、 ref和 ref readonly |
序列化程序按名称绑定每个参数,并使用其基础元素类型进行类型匹配。 |
out |
序列化程序不会将参数绑定到 JSON。 它放弃构造函数分配的值。 |
在以下构造函数中,序列化程序从 JSON 绑定 temperatureC 。 它不绑定 isValid:
public Forecast(in int temperatureC, out bool isValid)
{
TemperatureC = temperatureC;
isValid = true;
}
在Visual Basic中,ByRef构造函数参数遵循ref表中所示的行为:
Public Sub New(ByRef temperatureC As Integer)
TemperatureC = temperatureC
End Sub
记录
序列化和反序列化也支持记录,如以下示例所示:
using System.Text.Json;
namespace Records
{
public record Forecast(DateTime Date, int TemperatureC)
{
public string? Summary { get; init; }
};
public class Program
{
public static void Run()
{
Forecast forecast = new(DateTime.Now, 40)
{
Summary = "Hot!"
};
string forecastJson = JsonSerializer.Serialize<Forecast>(forecast);
Console.WriteLine(forecastJson);
Forecast? forecastObj = JsonSerializer.Deserialize<Forecast>(forecastJson);
Console.WriteLine(forecastObj);
}
}
}
// Produces output like the following example:
//
//{ "Date":"2020-10-21T15:26:10.5044594-07:00","TemperatureC":40,"Summary":"Hot!"}
//Forecast { Date = 10 / 21 / 2020 3:26:10 PM, TemperatureC = 40, Summary = Hot! }
可以使用 property: 特性上的目标,将任何特性应用于属性名称。 有关位置记录的详细信息,请参阅 C# 语言参考中有关 记录 的文章。
非公共成员和属性访问器
可以使用 [JsonInclude] 属性启用非公共属性访问器,如下例所示:
using System.Text.Json;
using System.Text.Json.Serialization;
namespace NonPublicAccessors
{
public class Forecast
{
public DateTime Date { get; init; }
[JsonInclude]
public int TemperatureC { get; private set; }
[JsonInclude]
public string? Summary { private get; set; }
};
public class Program
{
public static void Run()
{
string json = """
{
"Date":"2020-10-23T09:51:03.8702889-07:00",
"TemperatureC":40,
"Summary":"Hot"
}
""";
Console.WriteLine($"Input JSON: {json}");
Forecast forecastDeserialized = JsonSerializer.Deserialize<Forecast>(json)!;
Console.WriteLine($"Date: {forecastDeserialized.Date}");
Console.WriteLine($"TemperatureC: {forecastDeserialized.TemperatureC}");
json = JsonSerializer.Serialize<Forecast>(forecastDeserialized);
Console.WriteLine($"Output JSON: {json}");
}
}
}
// Produces output like the following example:
//
//Input JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}
//Date: 10 / 23 / 2020 9:51:03 AM
//TemperatureC: 40
//Output JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}
Imports System.Text.Json
Imports System.Text.Json.Serialization
Namespace NonPublicAccessors
Public Class Forecast
Public Property [Date] As Date
Private _temperatureC As Integer
<JsonInclude>
Public Property TemperatureC As Integer
Get
Return _temperatureC
End Get
Private Set(Value As Integer)
_temperatureC = Value
End Set
End Property
Private _summary As String
<JsonInclude>
Public Property Summary As String
Private Get
Return _summary
End Get
Set(Value As String)
_summary = Value
End Set
End Property
End Class
Public NotInheritable Class Program
Public Shared Sub Main()
Dim json As String = "{""Date"":""2020-10-23T09:51:03.8702889-07:00"",""TemperatureC"":40,""Summary"":""Hot""}"
Console.WriteLine($"Input JSON: {json}")
Dim forecastDeserialized As Forecast = JsonSerializer.Deserialize(Of Forecast)(json)
Console.WriteLine($"Date: {forecastDeserialized.[Date]}")
Console.WriteLine($"TemperatureC: {forecastDeserialized.TemperatureC}")
json = JsonSerializer.Serialize(forecastDeserialized)
Console.WriteLine($"Output JSON: {json}")
End Sub
End Class
End Namespace
' Produces output like the following example:
'
'Input JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}
'Date: 10 / 23 / 2020 9:51:03 AM
'TemperatureC: 40
'Output JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}
通过包含具有专用资源库的属性,你仍然可以反序列化该属性。
在 .NET 8 及更高版本中,还可使用 [JsonInclude] 属性将非公共成员加入到给定类型的序列化协定中。
从 .NET 11 开始,源生成支持private和internalprotected标记[JsonInclude]的成员。 它还支持private标记internal的属性[JsonInclude]和protected访问器。 源生成还支持使用 [JsonConstructor] 标记的不可访问构造函数。
注意
在 .NET 10 及更早版本中,源生成不支持private或protected成员或访问器。 将 [JsonInclude] 属性应用于成员或属性不会消除此限制。 仅当成员和访问器与生成的JsonSerializerContext程序集位于同一程序集中时,源生成才支持internal成员和访问器。 它不支持不可访问的构造函数,即使使用 < a0/> 标记它们
仅限 Init 的属性
System.Text.Json 反序列化 init-only 属性,就像任何其他可设置的属性一样。 从 .NET 11 开始,仅当 JSON 有效负载包含该属性时,才会运行源生成的 setter。 省略的属性保留其初始值设定项值。
只读属性
在 .NET 8 及更高版本中,也可反序列化只读属性,或者没有专用或公共资源库的属性。 虽然无法更改属性引用的实例,但如果属性的类型是可变的,则可以对其进行修改。 例如,可以将元素添加到列表中。 若要反序列化只读属性,需要将其对象创建处理行为设置为 填充 而不是 替换。 例如,可以使用 JsonObjectCreationHandlingAttribute 属性对属性进行批注。
class A
{
[JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)]
public List<int> Numbers1 { get; } = new List<int>() { 1, 2, 3 };
}
有关详细信息,请参阅填充初始化的属性。