Serileştirme davranışını özelleştirme

Tamamlandı

JsonSerializer.Serialize yöntemi, bir C# nesnesini JavaScript Nesne Gösterimi (JSON) dizesine dönüştürmek için kullanılır. Serileştirme, verileri diğer sistemler tarafından kolayca okunabilen ve işlenebilen basit bir biçimde depolamak veya iletmek istediğinizde kullanılır. JsonSerializer sınıfı, C# dilinde System.Text.Json JSON verileriyle çalışmaya yönelik işlevsellik sağlayan ad alanının bir parçasıdır.

Aşağıdaki kod kullanılarak bir nesnenin bir JSON dizesine JsonSerializer.Serializenasıl dönüştürüldüğünü gösterir:

var customer = new Employee { Name = "Anette Thomsen", Age = 30, Address = "123 Main St" };
string jsonString = JsonSerializer.Serialize(customer);

Varsayılan serileştirme davranışı

JSON seri hale getirildiğinde aşağıdaki varsayılan davranışlar geçerlidir:

• Varsayılan olarak, tüm genel özellikler serileştirilir. Yoksayılacak özellikleri belirtebilirsiniz. Özel üyeler de ekleyebilirsiniz.
• Varsayılan kodlayıcı, RFC 8259 JSON belirtimine göre ASCII olmayan karakterlerden, ASCII aralığındaki HTML'ye duyarlı karakterlerden ve kaçış yapılması gereken karakterlerden kaçar.
• Varsayılan olarak, JSON küçültüldü. JSON'ı oldukça yazdırabilirsiniz.
• Varsayılan olarak, JSON adlarının büyük/küçük harfle işareti .NET adlarla eşleşir. JSON ad büyük/küçük harflerini özelleştirebilirsiniz.
• Varsayılan olarak, döngüsel başvurular algılanıp özel durumlar oluşturulur. Başvuruları koruyabilir ve döngüsel başvuruları işleyebilirsiniz.
• Varsayılan olarak alanlar yoksayılır. Alanları ekleyebilirsiniz.

JsonSerializer sınıfı, serileştirme davranışını özelleştirmek için özellikleri yoksayma, alanları dahil etme ve JSON çıktısının biçimlendirmesini denetleme gibi çeşitli seçenekler ve yapılandırmalar sağlar.

JsonSerializerOptions kullanarak serileştirme davranışını özelleştirme

sınıfı, JsonSerializerOptions yönteminin serileştirme davranışını JsonSerializer.Serialize özelleştirmenize olanak tanır. Örneğin, null değerleri yoksaymak, alanları dahil etmek ve JSON çıkışının biçimlendirmesini denetlemek gibi seçenekleri belirtebilirsiniz.

Bu ünitede aşağıdaki özellikler gösterilmiştir:

• DefaultIgnoreCondition: Bu özellik, serileştirme sırasında varsayılan değerlere sahip özelliklerin hangi koşulda yoksayıldığını belirtir. Özellikleri varsayılan değerlerle dışlayarak serileştirilmiş JSON boyutunu azaltmaya yardımcı olabilir.
• WriteIndented: Bu özellik, girinti ve satır sonları ekleyerek JSON çıkışının daha kolay yazdırılabilir olmasını sağlar.
• IncludeFields: Bu özellik, alanların serileştirme işlemine dahil edilip edilmeyeceğini belirtir. Varsayılan olarak, yalnızca özellikler serileştirilir.

Yaygın olarak kullanılan diğer özellikler şunlardır:

• PropertyNameCaseInsensitive: Bu özellik, seri durumdan çıkarma sırasında özellik adlarının büyük/küçük harfe duyarsız eşleşmesini sağlar. JSON verilerinin sınıf tanımından farklı büyük/küçük harfe sahip özellik adları olduğunda yararlı olabilir.
• AllowTrailingCommas: Bu özellik JSON dizilerinde ve nesnelerinde sondaki virgüllere izin verir. Bu, sondaki virgüllere sahip olabilecek JSON verileriyle ilgilenirken yararlı olabilir.
• IgnoreNullValues: Bu özellik, serileştirme sırasında null değerlerin yoksayılıp yoksayılmayacağını belirtir. Özellikleri null değerlerle dışlayarak serileştirilmiş JSON boyutunu azaltmaya yardımcı olabilir.
• Kodlayıcı: Bu özellik, JSON dizelerinde kaçış karakterleri için özel bir kodlayıcı belirtmenize olanak tanır. Özellik adlarında veya değerlerinde özel karakterlerle ilgilenirken yararlı olabilir.

Serileştirme sırasında özellikleri yoksay

sınıfı, JsonSerializer serileştirme sırasında özellikleri yoksaymak için seçenekler sağlar. Bu, hassas bilgiler veya serileştirmeyle ilgili olmayan özellikler gibi belirli özellikleri JSON çıkışının dışında tutmak istediğinizde kullanışlıdır.

Aşağıdaki ölçütlere göre özellikleri yoksayabilirsiniz:

• Ayrı özellikler
• Tüm salt okunur özellikler
• Tüm null-değer özellikleri
• Tüm varsayılan değer özellikleri

Tek tek özellikleri yoksay

Tek tek özellikleri yoksaymak için [JsonIgnore] özniteliğini kullanın.

Aşağıdaki örnekte seri hale getirecek bir tür gösterilmektedir. Ayrıca JSON çıkışını da gösterir:

public class WeatherForecastWithIgnoreAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    [JsonIgnore]
    public string? Summary { get; set; }
}

class Program
{
    static void Main()
    {
        var forecast = new WeatherForecastWithIgnoreAttribute
        {
            Date = DateTimeOffset.Now,
            TemperatureCelsius = 25,
            Summary = "Warm"
        };

        string jsonString = JsonSerializer.Serialize(forecast);
        Console.WriteLine(jsonString);
    }
}

// Output: {"Date":"2023-10-01T12:00:00Z","TemperatureCelsius":25}

Özniteliğin [JsonIgnore]Condition özelliğini ayarlayarak koşullu dışlama belirtebilirsiniz. sabit JsonIgnoreCondition listesi aşağıdaki seçenekleri sağlar:

• Always - Özelliği her zaman yoksayılır. Koşul belirtilmezse, bu seçenek varsayılır.
• Hiçbir zaman - DefaultIgnoreCondition, IgnoreReadOnlyProperties ve IgnoreReadOnlyFields genel ayarları ne olursa olsun özellik her zaman serileştirilir ve seri durumdan çıkarılır.
• WhenWritingDefault - Bir başvuru türü null, null atanabilir değer türü null veya varsayılan değer türüyse, serileştirme sırasında özellik yoksayılır.
• WhenWritingNull - Özellik, başvuru türü null veya null değer türü null olduğunda serileştirme sırasında yoksayılır.

Aşağıdaki örnekte [JsonIgnore] özniteliğinin Condition özelliğinin kullanımı gösterilmektedir:

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

namespace JsonIgnoreAttributeExample
{
    public class Forecast
    {
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
        public DateTime Date { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.Never)]
        public int TemperatureC { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = default,
                Summary = null,
                TemperatureC = default
            };

            JsonSerializerOptions options = new()
            {
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
            };

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

            Console.WriteLine(forecastJson);
        }
    }
}

// Produces output like the following example:
//
//{"TemperatureC":0}

Tüm salt okunur özellikleri yoksay

Bir özellik, genel bir alıcı içeriyorsa ancak ortak ayarlayıcı içermiyorsa salt okunurdur. Seri hale getirildiğinde tüm salt okunur özellikleri yoksaymak içinJsonSerializerOptions.IgnoreReadOnlyProperties, aşağıdaki örnekte gösterildiği gibi değerini olarak ayarlayıntrue:

var options = new JsonSerializerOptions
{
    IgnoreReadOnlyProperties = true,
    WriteIndented = true
};

jsonString = JsonSerializer.Serialize(weatherForecast, options);

Aşağıdaki örnekte seri hale getirecek bir tür gösterilmektedir. Ayrıca JSON çıkışını da gösterir:

public class WeatherForecastWithROProperty
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    public int WindSpeedReadOnly { get; private set; } = 35;
}

// {
//   "Date": "2019-08-01T00:00:00-07:00",
//   "TemperatureCelsius": 25,
//   "Summary": "Hot",
// }

Uyarı

Bu seçenek yalnızca özellikler için geçerlidir. Alanları serileştirirken salt okunur alanları yoksaymak için genel ayarı kullanın JsonSerializerOptions.IgnoreReadOnlyFields .

Tüm null-değer özelliklerini yoksay

Tüm null-değer özelliklerini yoksaymak DefaultIgnoreConditioniçin, aşağıdaki örnekte gösterildiği gibi özelliğini olarak ayarlayınWhenWritingNull:

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

namespace IgnoreNullOnSerialize
{
    public class Forecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = DateTime.Now,
                Summary = null,
                TemperatureC = default
            };

            JsonSerializerOptions options = new()
            {
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
            };

            string forecastJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);
            
            Console.WriteLine(forecastJson);
        }
    }
}

// Produces output like the following example:
//
//{"Date":"2020-10-30T10:11:40.2359135-07:00","TemperatureC":0}

Tüm varsayılan değer özelliklerini yoksay

Değer türü özelliklerindeki varsayılan değerlerin serileştirilmesini önlemek için, aşağıdaki örnekte gösterildiği gibi özelliğini DefaultIgnoreConditionolarak ayarlayınWhenWritingDefault:

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

namespace IgnoreValueDefaultOnSerialize
{
    public class Forecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = DateTime.Now,
                Summary = null,
                TemperatureC = default
            };

            JsonSerializerOptions options = new()
            {
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
            };

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

            Console.WriteLine(forecastJson);
        }
    }
}

// Produces output like the following example:
//
//{ "Date":"2020-10-21T15:40:06.8920138-07:00"}

Bu WhenWritingDefault ayar, null-değer başvuru türü ve null atanabilir değer türü özelliklerinin seri hale getirilmesini de engeller.

Serileştirme sırasında alanları dahil et

Varsayılan olarak, yalnızca özellikler serileştirilir, ancak seri hale getiriciyi alanları da içerecek şekilde yapılandırabilirsiniz. JsonSerializerOptions.IncludeFields Aşağıdaki örnekte gösterildiği gibi, seri hale getirme veya seri durumdan çıkarma sırasında alanları eklemek için genel ayarı veya [JsonInclude] özniteliğini kullanın:

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

namespace Fields
{
    public class Forecast
    {
        public DateTime Date;
        public int TemperatureC;
        public string? Summary;
    }

    public class Forecast2
    {
        [JsonInclude]
        public DateTime Date;
        [JsonInclude]
        public int TemperatureC;
        [JsonInclude]
        public string? Summary;
    }

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

            var options = new JsonSerializerOptions
            {
                IncludeFields = true,
            };
            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}");

            Forecast2 forecast2 = JsonSerializer.Deserialize<Forecast2>(json)!;

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

            roundTrippedJson = JsonSerializer.Serialize<Forecast2>(forecast2);
            
            Console.WriteLine($"Output JSON: {roundTrippedJson}");
        }
    }
}

// Produces output like the following example:
//
//Input JSON: { "Date":"2020-09-06T11:31:01.923395","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","TemperatureC":-1,"Summary":"Cold"}
//forecast2.Date: 9/6/2020 11:31:01 AM
//forecast2.TemperatureC: -1
//forecast2.Summary: Cold
//Output JSON: { "Date":"2020-09-06T11:31:01.923395","TemperatureC":-1,"Summary":"Cold"}

Salt okunur alanları yoksaymak için JsonSerializerOptions.IgnoreReadOnlyFields genel ayarını kullanın.

JSON dosyaları yazma

JSON dosyaları yazmak, JSON verileriyle çalışırken sık kullanılan bir görevdir. JsonSerializer sınıfı, nesneleri JSON dizelerine seri hale getirmek için yöntemler sağlar ve daha sonra dosyalara kaydedilebilir. File.WriteAllText yöntemi, JSON dizesini bir dosyaya yazmak için kullanılabilir.

Aşağıdaki örnekte, bir nesnenin JSON'a seri hale getirilip bir dosyaya nasıl kaydedilecekleri gösterilmektedir:

using System;
using System.IO;
using System.Text.Json;

class Program
{
      static void Main()
      {
          var customer = new BankCustomer {  };
          string jsonString = JsonSerializer.Serialize(customer);
          File.WriteAllText("customer.json", jsonString);
          Console.WriteLine("JSON file created and saved.");
      }
}

Özet

Bu ünitede, yöntemini kullanarak C# nesnelerini seri hale getirdiğinizde serileştirme davranışını özelleştirmeyi JsonSerializer.Serialize öğrendiniz. Serileştirme sırasında özellikleri ve alanları yoksayma ve dosyalara JSON verileri yazma hakkında bilgi edindiyseniz. Bu bilgi, C# uygulamalarında JSON verileriyle çalışmak için gereklidir.