Sabit türleri ve özellikleri kullanma

Makale
10/26/2023

Sabit tür, bir nesnenin örneğini oluşturduktan sonra herhangi bir özellik veya alan değerini değiştirmenizi engelleyen türdür . Tür bir kayıt olabilir, ortak özellikleri veya alanları olmayabilir, salt okunur özelliklere veya özel veya yalnızca başlatma ayarlayıcılarına sahip özelliklere sahip olabilir. System.String sabit bir tür örneğidir. System.Text.Json JSON'ı sabit türler olarak seri durumdan çıkarmanın farklı yollarını sağlar.

Parametreli oluşturucular

Varsayılan olarak, System.Text.Json varsayılan genel parametresiz oluşturucuyu kullanır. Ancak, sabit bir sınıfın veya yapının seri durumdan çıkarılmasına olanak tanıyan parametreli bir oluşturucu kullanmasını söyleyebilirsiniz.

Bir sınıf için, tek oluşturucu parametreli bir oluşturucu ise, bu oluşturucu kullanılır.

Bir yapı veya birden çok oluşturucuya sahip bir sınıf için ,[JsonConstructor] özniteliğini uygulayarak kullanılacak olanı belirtin. Öznitelik kullanılmadığında, varsa her zaman genel parametresiz bir oluşturucu kullanılır.

Aşağıdaki örnekte özniteliği kullanılır [JsonConstructor] :

using System.Text.Json;
using System.Text.Json.Serialization;

namespace ImmutableTypes
{
    public struct Forecast
    {
        public DateTime Date { get; }
        public int TemperatureC { get; }
        public string Summary { get; }

        [JsonConstructor]
        public Forecast(DateTime date, int temperatureC, string summary) =>
            (Date, TemperatureC, Summary) = (date, temperatureC, summary);
    }

    public class Program
    {
        public static void Main()
        {
            string json = """
                {
                    "date":"2020-09-06T11:31:01.923395-07:00",
                    "temperatureC":-1,
                    "summary":"Cold"
                }
                """;
            Console.WriteLine($"Input JSON: {json}");

            var options = JsonSerializerOptions.Web;

            Forecast forecast = JsonSerializer.Deserialize<Forecast>(json, options);

            Console.WriteLine($"forecast.Date: {forecast.Date}");
            Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}");
            Console.WriteLine($"forecast.Summary: {forecast.Summary}");

            string roundTrippedJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);

            Console.WriteLine($"Output JSON: {roundTrippedJson}");
        }
    }
}

// Produces output like the following example:
//
//Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}
//forecast.Date: 9 / 6 / 2020 11:31:01 AM
//forecast.TemperatureC: -1
//forecast.Summary: Cold
//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}

Imports System.Text.Json
Imports System.Text.Json.Serialization

Namespace ImmutableTypes

    Public Structure Forecast
        Public ReadOnly Property [Date] As Date
        Public ReadOnly Property TemperatureC As Integer
        Public ReadOnly Property Summary As String

        <JsonConstructor>
        Public Sub New([Date] As Date, TemperatureC As Integer, Summary As String)
            Me.Date = [Date]
            Me.TemperatureC = TemperatureC
            Me.Summary = Summary
        End Sub

    End Structure

    Public NotInheritable Class Program

        Public Shared Sub Main()
            Dim json As String = "{""date"":""2020-09-06T11:31:01.923395-07:00"",""temperatureC"":-1,""summary"":""Cold""}"
            Console.WriteLine($"Input JSON: {json}")

            Dim forecast1 As Forecast = JsonSerializer.Deserialize(Of Forecast)(json, JsonSerializerOptions.Web)

            Console.WriteLine($"forecast.Date: {forecast1.[Date]}")
            Console.WriteLine($"forecast.TemperatureC: {forecast1.TemperatureC}")
            Console.WriteLine($"forecast.Summary: {forecast1.Summary}")

            Dim roundTrippedJson As String = JsonSerializer.Serialize(forecast1, JsonSerializerOptions.Web)

            Console.WriteLine($"Output JSON: {roundTrippedJson}")
        End Sub

    End Class

End Namespace

' Produces output like the following example:
'
'Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}
'forecast.Date: 9 / 6 / 2020 11:31:01 AM
'forecast.TemperatureC: -1
'forecast.Summary: Cold
'Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}

.NET 7 ve önceki sürümlerinde özniteliği [JsonConstructor] yalnızca ortak oluşturucularla kullanılabilir.

Parametreli bir oluşturucunun parametre adları özellik adları ve türleriyle eşleşmelidir. Eşleştirme büyük/küçük harfe duyarlı değildir ve bir özelliği yeniden adlandırmak için [JsonPropertyName] kullansanız bile oluşturucu parametresinin gerçek özellik adıyla eşleşmesi gerekir. Aşağıdaki örnekte, özelliğin TemperatureC adı JSON'da olarak değiştirilmiştir celsius , ancak oluşturucu parametresi hala olarak adlandırılmıştır temperatureC:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace ImmutableTypesCtorParms
{
    public readonly struct Forecast
    {
        public DateTime Date { get; }
        [JsonPropertyName("celsius")]
        public int TemperatureC { get; }
        public string Summary { get; }

        [JsonConstructor]
        public Forecast(DateTime date, int temperatureC, string summary) =>
            (Date, TemperatureC, Summary) = (date, temperatureC, summary);
    }

    public class Program
    {
        public static void Main()
        {
            string json = """
                {
                    "date":"2020-09-06T11:31:01.923395-07:00",
                    "celsius":-1,
                    "summary":"Cold"
                }
                """;
            Console.WriteLine($"Input JSON: {json}");

            var options = JsonSerializerOptions.Web;

            Forecast forecast = JsonSerializer.Deserialize<Forecast>(json, options);

            Console.WriteLine($"forecast.Date: {forecast.Date}");
            Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}");
            Console.WriteLine($"forecast.Summary: {forecast.Summary}");

            string roundTrippedJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);

            Console.WriteLine($"Output JSON: {roundTrippedJson}");

        }
    }
}

// Produces output like the following example:
//
//Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","celsius":-1,"summary":"Cold"}
//forecast.Date: 9 / 6 / 2020 11:31:01 AM
//forecast.TemperatureC: -1
//forecast.Summary: Cold
//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","celsius":-1,"summary":"Cold"}

[JsonPropertyName]Ayrıca, aşağıdaki öznitelikler parametreli oluşturucularla seri durumdan çıkarma özelliğini destekler:

Kayıtlar

Kayıtlar, aşağıdaki örnekte gösterildiği gibi hem serileştirme hem de seri durumdan çıkarma için de desteklenir:

using System.Text.Json;

namespace Records
{
    public record Forecast(DateTime Date, int TemperatureC)
    {
        public string? Summary { get; init; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new(DateTime.Now, 40)
            {
                Summary = "Hot!"
            };

            string forecastJson = JsonSerializer.Serialize<Forecast>(forecast);
            Console.WriteLine(forecastJson);
            Forecast? forecastObj = JsonSerializer.Deserialize<Forecast>(forecastJson);
            Console.WriteLine(forecastObj);
        }
    }
}

// Produces output like the following example:
//
//{ "Date":"2020-10-21T15:26:10.5044594-07:00","TemperatureC":40,"Summary":"Hot!"}
//Forecast { Date = 10 / 21 / 2020 3:26:10 PM, TemperatureC = 40, Summary = Hot! }

Özniteliklerdeki hedefi kullanarak property: özniteliklerden herhangi birini özellik adlarına uygulayabilirsiniz. Konumsal kayıtlar hakkında daha fazla bilgi için C# dil başvurusundaki kayıtlara ilişkin makaleye bakın.

Genel olmayan üyeler ve özellik erişimcileri

Aşağıdaki örnekte gösterildiği gibi [JsonInclude] özniteliğini kullanarak bir özellikte genel olmayan erişimci kullanımını etkinleştirebilirsiniz:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace NonPublicAccessors
{
    public class Forecast
    {
        public DateTime Date { get; init; }

        [JsonInclude]
        public int TemperatureC { get; private set; }

        [JsonInclude]
        public string? Summary { private get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            string json = """
                {
                    "Date":"2020-10-23T09:51:03.8702889-07:00",
                    "TemperatureC":40,
                    "Summary":"Hot"
                }
                """;
            Console.WriteLine($"Input JSON: {json}");

            Forecast forecastDeserialized = JsonSerializer.Deserialize<Forecast>(json)!;
            Console.WriteLine($"Date: {forecastDeserialized.Date}");
            Console.WriteLine($"TemperatureC: {forecastDeserialized.TemperatureC}");

            json = JsonSerializer.Serialize<Forecast>(forecastDeserialized);
            Console.WriteLine($"Output JSON: {json}");
        }
    }
}

// Produces output like the following example:
//
//Input JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}
//Date: 10 / 23 / 2020 9:51:03 AM
//TemperatureC: 40
//Output JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}

Imports System.Text.Json
Imports System.Text.Json.Serialization

Namespace NonPublicAccessors

    Public Class Forecast
        Public Property [Date] As Date

        Private _temperatureC As Integer

        <JsonInclude>
        Public Property TemperatureC As Integer
            Get
                Return _temperatureC
            End Get
            Private Set(Value As Integer)
                _temperatureC = Value
            End Set
        End Property

        Private _summary As String

        <JsonInclude>
        Public Property Summary As String
            Private Get
                Return _summary
            End Get
            Set(Value As String)
                _summary = Value
            End Set
        End Property

    End Class

    Public NotInheritable Class Program

        Public Shared Sub Main()
            Dim json As String = "{""Date"":""2020-10-23T09:51:03.8702889-07:00"",""TemperatureC"":40,""Summary"":""Hot""}"
            Console.WriteLine($"Input JSON: {json}")

            Dim forecastDeserialized As Forecast = JsonSerializer.Deserialize(Of Forecast)(json)
            Console.WriteLine($"Date: {forecastDeserialized.[Date]}")
            Console.WriteLine($"TemperatureC: {forecastDeserialized.TemperatureC}")

            json = JsonSerializer.Serialize(forecastDeserialized)
            Console.WriteLine($"Output JSON: {json}")
        End Sub

    End Class

End Namespace

' Produces output like the following example:
'
'Input JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}
'Date: 10 / 23 / 2020 9:51:03 AM
'TemperatureC: 40
'Output JSON: { "Date":"2020-10-23T09:51:03.8702889-07:00","TemperatureC":40,"Summary":"Hot"}

Özel ayarlayıcıya sahip bir özellik ekleyerek, yine de bu özelliği seri durumdan çıkarabilirsiniz.

.NET 8 ve sonraki sürümlerde, [JsonInclude] özniteliğini kullanarak genel olmayan üyeleri belirli bir tür için serileştirme sözleşmesine kabul edebilirsiniz.

Not

Kaynak oluşturma modunda üyeleri seri hale private getiremez veya [JsonInclude] özniteliğiyle ek açıklama ekleyerek erişimcileri kullanamazsınızprivate. Ayrıca üyeleri yalnızca oluşturulan JsonSerializerContextile aynı derlemedeyse serileştirebilir internal veya erişimcileri kullanabilirsinizinternal.

Salt okunur özellikler

.NET 8 ve sonraki sürümlerde salt okunur özellikler veya özel veya genel ayarlayıcı içermeyenler de seri durumdan çıkarılabilir. Özelliğin başvurduğunu örneği değiştiremezsiniz, ancak özelliğin türü değişebilirse değiştirebilirsiniz. Örneğin, bir öğeyi listeye ekleyebilirsiniz. Salt okunur bir özelliği seri durumdan çıkarmak için, nesne oluşturma işleme davranışını değiştirmek yerine doldurulacak şekilde ayarlamanız gerekir. Örneğin, özniteliğiyle özelliğine JsonObjectCreationHandlingAttribute açıklama ekleyebilirsiniz.

class A
{
    [JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)]
    public List<int> Numbers1 { get; } = new List<int>() { 1, 2, 3 };
}

Daha fazla bilgi için bkz . Başlatılan özellikleri doldurma.

Aracılığıyla paylaş

Sabit türleri ve özellikleri kullanma

Parametreli oluşturucular

Kayıtlar

Genel olmayan üyeler ve özellik erişimcileri

Salt okunur özellikler

Ayrıca bkz.

Ek kaynaklar