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

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 ve ifadeleri MyPoco MyPoco? , ç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 System.Text.Json.Serialization.RespectNullableAnnotationsDefault ayarı genel olarak açabilirsinizRespectNullableAnnotations. 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"
    );

Ayrıca bkz.

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