Gerekli özellikler

  • Makale

Seri durumdan çıkarmanın başarılı olması için JSON yükünde bulunmaları gerektiğini göstermek için belirli özellikleri işaretleyebilirsiniz. Benzer şekilde, isteğe bağlı olmayan tüm oluşturucu parametrelerinin JSON yükünde mevcut olduğunu belirtmek için bir seçenek ayarlayabilirsiniz. Bu gerekli özelliklerden biri veya daha fazlası yoksa, JsonSerializer.Deserialize yöntemler bir JsonExceptionoluşturur.

JSON seri durumdan çıkarma için bir özelliği veya alanı gerektiği gibi işaretlemenin üç yolu vardır:

JSON seri durumdan çıkarma için isteğe bağlı olmayan tüm oluşturucu parametrelerinin gerekli olduğunu belirtmek için seçeneğini (veya kaynak oluşturma için özellikRespectRequiredConstructorParameters) trueolarak ayarlayınJsonSerializerOptions.RespectRequiredConstructorParameters. Daha fazla bilgi için İsteğe bağlı olmayan oluşturucu parametreleri bölümüne bakın.

Seri hale getiricinin perspektifinden, C# required değiştiricisi ve [JsonRequired] özniteliği eşdeğerdir ve her ikisi de aynı meta veri parçası olan ile eşlenir JsonPropertyInfo.IsRequired. Çoğu durumda, yerleşik C# anahtar sözcüğünü kullanmanız yeterlidir. Ancak, aşağıdaki durumlarda bunun yerine kullanmanız JsonRequiredAttribute gerekir:

  • C# dışında bir programlama dili veya C# 'nin alt düzey bir sürümünü kullanıyorsanız.
  • Gereksinimin yalnızca JSON seri durumdan çıkarma işlemine uygulanmasını istiyorsanız.
  • Kaynak oluşturma modunda serileştirme kullanıyorsanızSystem.Text.Json. Bu durumda, kaynak oluşturma işlemi derleme zamanında gerçekleştiğinden değiştiriciyi required kullanırsanız kodunuz derlenmez.

Aşağıdaki kod parçacığında anahtar sözcüğüyle değiştirilen bir özellik örneği gösterilmektedir required . Seri durumdan çıkarmanın başarılı olması için bu özelliğin JSON yükünde mevcut olması gerekir.

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; }
}

Alternatif olarak, kullanabilirsiniz 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; }
}

Ayrıca, özelliğini kullanarak JsonPropertyInfo.IsRequired sözleşme modeli aracılığıyla bir özelliğin gerekli olup olmadığını denetlemek de mümkündür:

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; }
}

İsteğe bağlı olmayan oluşturucu parametreleri

.NET 9'un öncesinde, oluşturucu tabanlı seri durumdan çıkarma, aşağıdaki örnekte gösterildiği gibi tüm oluşturucu parametrelerini isteğe bağlı olarak değerlendirdi:

var result = JsonSerializer.Deserialize<Person>("{}");
Console.WriteLine(result); // Person { Name = , Age = 0 }

record Person(string Name, int Age);

.NET 9'dan başlayarak, isteğe bağlı olmayan oluşturucu parametrelerini gerektiği gibi işlemek için bayrağını ayarlayabilirsiniz 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);

Özellik geçişi

Özellik anahtarını kullanarak System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault ayarı genel olarak açabilirsinizRespectRequiredConstructorParameters. Proje dosyanıza aşağıdaki MSBuild öğesini ekleyin (örneğin, .csproj dosyası):

<ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" Value="true" />
</ItemGroup>

API, RespectRequiredConstructorParametersDefault mevcut uygulamaları bozmamak için .NET 9'da bir kabul bayrağı olarak uygulandı. Yeni bir uygulama yazıyorsanız, kodunuzda bu bayrağı etkinleştirmeniz kesinlikle önerilir.

Ayrıca bkz.