Aracılığıyla paylaş

Boş değer atanabilir ek açıklamalara saygı gösterin

.NET 9'dan başlayarak, JsonSerializer hem seri hale getirme hem de seri durumdan çıkarmada null atanamaz başvuru türü zorlama desteği (sınırlı) vardır. Bayrağını kullanarak JsonSerializerOptions.RespectNullableAnnotations bu desteği değiştirebilirsiniz.

Örneğin, aşağıdaki kod parçacığı serileştirme sırasında aşağıdaki gibi bir iletiyle bir oluşturur JsonException :

'Person' türündeki 'Name' özelliği veya alanı null değerler almaya izin vermez. Boş değer atanabilirlik ek açıklamasını güncelleştirmeyi göz önünde bulundurun.

    public static void RunIt()
    {
#nullable enable
        JsonSerializerOptions options = new()
        {
            RespectNullableAnnotations = true
        };

        Person invalidValue = new(Name: null!);
        JsonSerializer.Serialize(invalidValue, options);
    }

    record Person(string Name);

Benzer şekilde, RespectNullableAnnotations seri durumdan çıkarmada null atanabilirliği zorlar. Aşağıdaki kod parçacığı, serileştirme sırasında aşağıdaki gibi bir iletiyle bir oluşturur JsonException :

'Person' türündeki 'Name' oluşturucu parametresi null değerlere izin vermiyor. Boş değer atanabilirlik ek açıklamasını güncelleştirmeyi göz önünde bulundurun.

    public static void RunIt()
    {
#nullable enable
        JsonSerializerOptions options = new()
        {
            RespectNullableAnnotations = true
        };

        string json = """{"Name":null}""";
        JsonSerializer.Deserialize<Person>(json, options);
    }

    record Person(string Name);

İpucu

Sınırlamalar

Null değer atanamayan başvuru türlerinin uygulanması nedeniyle bu özellik bazı önemli sınırlamalarla birlikte gelir. Özelliği açmadan önce bu sınırlamaları tanıyın. Sorunun kökü, başvuru türü nullability'nin ara dilde (IL) birinci sınıf gösterimi olmamasıdır. Bu nedenle, MyPoco ve MyPoco? ifadeleri çalışma zamanı yansıması açısından ayırt edilemez. Derleyici öznitelik meta verilerini yayarak bunu telafi etmeye çalışsa da (bkz . sharplab.io örnek), bu meta veriler belirli bir tür tanımı kapsamındaki genel olmayan üye ek açıklamalarıyla sınırlıdır. Bu sınırlama, bayrağın yalnızca genel olmayan özelliklerde, alanlarda ve oluşturucu parametrelerinde mevcut olan null atanabilirlik ek açıklamalarını doğrulamasının nedenidir. System.Text.Json nullability zorlamayı desteklemez:

  • En üst düzey türler veya ilk JsonSerializer.Deserialize() veya JsonSerializer.Serialize() çağrı yapılırken geçirilen tür.
  • Koleksiyon öğesi türleri; örneğin, List<string> ve List<string?> türleri ayırt edilemez.
  • Genel özellikler, alanlar veya oluşturucu parametreleri.

Bu gibi durumlarda null atanabilirlik zorlaması eklemek istiyorsanız, türünüzü bir yapı (null değerleri kabul etmedikleri için) olacak şekilde modelleyebilirsiniz veya özelliğini 'de geçersiz kılan HandleNull özel bir dönüştürücü yazabilirsiniz true.

Özellik geçişi

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

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

API, RespectNullableAnnotationsDefault 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.

Null atanabilir ve isteğe bağlı parametreler arasındaki ilişki

RespectNullableAnnotations zorunlu ve null değer atanamayan özellikleri ortogonal kavramlar olarak değerlendirdiğinden System.Text.Json zorlamayı belirtilmeyen JSON değerlerine genişletmez. Örneğin, aşağıdaki kod parçacığı seri durumdan çıkarma sırasında bir özel durum oluşturmaz:

public static void RunIt()
{
    JsonSerializerOptions options = new()
    {
        RespectNullableAnnotations = true
    };
    var result = JsonSerializer.Deserialize<MyPoco>("{}", options);
    Console.WriteLine(result.Name is null); // True.
}

class MyPoco
{
    public string Name { get; set; }
}

Bu davranış C# dilinin kendisinden kaynaklanır ve burada null atanabilir gerekli özelliklere sahip olabilirsiniz:

MyPoco poco = new() { Value = null }; // No compiler warnings.

class MyPoco
{
    public required string? Value { get; set; }
}

Ayrıca, null değer atanamayan isteğe bağlı özelliklere de sahip olabilirsiniz:

class MyPoco
{
    public string Value { get; set; } = "default";
}

Aynı ortogonalite oluşturucu parametreleri için de geçerlidir:

record MyPoco(
    string RequiredNonNullable,
    string? RequiredNullable,
    string OptionalNonNullable = "default",
    string? OptionalNullable = "default"
    );

Eksik değerler ve null değerler

değerini ayarladığınızda eksik JSON özellikleri ile açık değerli özellikler arasındaki ayrımı anlamak önemlidir. JavaScript undefined (eksik özellik) ile null (açık null değer) arasında ayrım sağlar. Ancak, .NET'in bir undefined kavramı yoktur, bu nedenle her iki durumda da .NET'te null ile aynı nesne türüne serileştirilir.

Seri durumdan çıkarma sırasında, RespectNullableAnnotationstrue olduğunda:

  • Belirgin null değeri, null atanamayan özellikler için bir hata fırlatır. Örneğin, {"Name":null} null atanamayan string Name özelliğe seri durumdan çıkarılırken bir istisna fırlatır.

  • Eksik bir özellik, null atanamayan özellikler için bile özel durum oluşturmaz. Örneğin, {} null kabul etmeyen string Name bir özelliğe seri durumdan çıkarılırken Özel Durum atmaz. Serileştirici, özelliği ayarlamaz ve varsayılan oluşturucudan gelen değerinde bırakır. Başlatılmamış null olamaz bir başvuru türü için bu, null ile sonuçlanır ve derleyici uyarısını tetikler.

    Aşağıdaki kod, seri durumdan çıkarma sırasında eksik bir özelliğin nasıl özel durum oluşturmadığını gösterir:

        public static void RunIt()
    {
#nullable enable
        JsonSerializerOptions options = new()
        {
            RespectNullableAnnotations = true
        };

        // Missing property - does NOT throw an exception.
        string jsonMissing = """{}""";
        var resultMissing = JsonSerializer.Deserialize<Person>(jsonMissing, options);
        Console.WriteLine(resultMissing.Name is null); // True.
    }

    record Person(string Name);

Bu davranış farkı, eksik özellikler isteğe bağlı (sağlanmaz) olarak kabul edildiğinden, açık null değerler ise null atanamayan kısıtlamayı ihlal eden sağlanan değerler olarak kabul edildiğinden oluşur. Bir özelliğin JSON'da mevcut olmasını zorunlu kılmanız gerekiyorsa, değiştiriciyi required kullanın veya özelliğini veya sözleşme modelini kullanarak JsonRequiredAttribute gerektiği gibi yapılandırın.

Ayrıca bkz.

  • Last updated on