必須プロパティ
特定のプロパティをマークして、逆シリアル化を成功させるためにはそれらのプロパティが JSON ペイロード内に存在する必要があることを示すことができます。 同様に、オプションを設定して、すべての非オプションのコンストラクター パラメーターが JSON ペイロードに存在することを指定できます。 これらの必須プロパティの 1 つ以上が存在しない場合、JsonSerializer.Deserialize メソッドは JsonException をスローします。
JSON の逆シリアル化に必要なプロパティまたはフィールドをマークするには、次の 3 つの方法があります。
required
修飾子を追加します。- JsonRequiredAttribute を使用して注釈を付けます。
- コントラクトモデルの JsonPropertyInfo.IsRequired プロパティを変更する。
JSON 逆シリアル化にオプション以外のすべてのコンストラクター パラメーターが必要であることを指定するには、JsonSerializerOptions.RespectRequiredConstructorParameters オプション (または、ソース生成の場合は 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 でオプトイン フラグとして実装されました。 新しいアプリケーションを作成する場合は、コードでこのフラグを有効にすることを強くお勧めします。
関連項目
.NET