必要屬性
您可以標記特定屬性，表示它們必須存在於 JSON 承載中，才能還原串行化成功。 同樣地，您可以設定選項來指定 JSON 承載中存在所有非選擇性建構函式參數。 如果這其中一或多個必要屬性不存在，JsonSerializer.Deserialize 方法就會擲回 JsonException。
有三種方式可將屬性或欄位標記為 JSON 還原序列化所需的項目：
- 藉由新增
required修飾詞。 - 使用 JsonRequiredAttribute標註它。
- 修改 JsonPropertyInfo.IsRequired 合約模型的屬性。
若要指定 JSON 還原串行化所需的所有非選擇性建構函式參數，請將 選項 （或，針對來源產生，RespectRequiredConstructorParameters屬性） 設定JsonSerializerOptions.RespectRequiredConstructorParameters為 true。 如需詳細資訊，請參閱 非選擇性建構函式參數 一節。
從串行化程序的觀點來看，C# required 修飾詞和 [JsonRequired] 屬性相等，而且兩者都對應至相同的元數據片段，也就是 JsonPropertyInfo.IsRequired。 在大部分情況下，您只要使用內建的 C# 關鍵字即可。 不過，在下列情況下，您應該改用 JsonRequiredAttribute：
- 如果您使用的是 C# 或舊版 C# 以外的程式設計語言。
- 如果您只想將需求套用至 JSON 還原序列化。
- 如果您在來源產生模式中使用
System.Text.Json序列化。 在此情況下，如果您使用required修飾元，您的程式碼將不會編譯，因為來源產生會在編譯時間發生。
下列程式碼片段顯示使用 required 關鍵字修改的屬性範例。 此屬性必須存在於 JSON 承載中，還原序列化才能成功。
public static void RunIt()
{
// The following line throws a JsonException at run time.
Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
}
public class Person
{
public required string Name { get; set; }
public int Age { get; set; }
}
或者，您可以使用 JsonRequiredAttribute：
public static void RunIt()
{
// The following line throws a JsonException at run time.
Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
}
public class Person
{
[JsonRequired]
public string Name { get; set; }
public int Age { get; set; }
}
您也可以使用 JsonPropertyInfo.IsRequired 屬性，透過合約模型來控制是否需要屬性：
public static void RunIt()
{
var options = new JsonSerializerOptions
{
TypeInfoResolver = new DefaultJsonTypeInfoResolver
{
Modifiers =
{
static typeInfo =>
{
if (typeInfo.Kind != JsonTypeInfoKind.Object)
return;
foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
{
// Strip IsRequired constraint from every property.
propertyInfo.IsRequired = false;
}
}
}
}
};
// Deserialization succeeds even though
// the Name property isn't in the JSON payload.
JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);
}
public class Person
{
public required string Name { get; set; }
public int Age { get; set; }
}
非選擇性建構函式參數
在 .NET 9 之前，建構函式還原串行化會將所有建構函式參數視為選擇性，如下列範例所示：
var result = JsonSerializer.Deserialize<Person>("{}");
Console.WriteLine(result); // Person { Name = , Age = 0 }
record Person(string Name, int Age);
從 .NET 9 開始，您可以設定 RespectRequiredConstructorParameters 旗標，視需要處理非選擇性建構函式參數。
public static void RunIt()
{
JsonSerializerOptions options = new()
{
RespectRequiredConstructorParameters = true
};
string json = """{"Age": 42}""";
// The following line throws a JsonException at run time.
JsonSerializer.Deserialize<Person>(json, options);
}
record Person(string Name, int? Age = null);
功能切換
您可以使用功能參數全域System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault開啟RespectRequiredConstructorParameters設定。 將下列 MSBuild 專案新增至項目檔（例如 .csproj 檔案）：
<ItemGroup>
<RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" Value="true" />
</ItemGroup>
RespectRequiredConstructorParametersDefault API 已在 .NET 9 中實作為加入宣告旗標，以避免中斷現有的應用程式。 如果您要撰寫新的應用程式，強烈建議您在程式代碼中啟用此旗標。
