Newtonsoft.Json-dən istifadə — tətbiq

1. Giriş

Newtonsoft.Json yaxşı mənada bir növ dinosavrdır. O, uzun illər ərzində .NET ekosistemində JSON ilə işləmək üçün de-fakto standart olub, hətta System.Text.Json yaranmazdan əvvəl də. Milyonlarla layihə, minlərlə kitabxana və framework (hətta ASP.NET Core-un bəzi hissələri də əvvəlki dövrlərdə) məhz Json.NET-dən istifadə edib.

Onun üstünlükləri aşağıdakılardır:

• Faydalı və çevikdir: Json.NET serializasiya və deserializasiya prosesini fərdiləşdirmək üçün çoxlu parametrlər, atributlar və imkanlar təklif edir. O, bəzi şeyləri System.Text.Json-dən daha asan və ya bəzən ümumiyyətlə edə bilir.
• "Qeyri-ideal" JSON-a tolerantdır: xarici sistemlərdən gələn məlumatlar həmişə ideal olmur — Json.NET belə hallara qarşı daha dözümlüdür və deserializasiya prosesini daha az ağrıyla icra etməyə imkan verir.
• Geri uyğunluq saxlayır: əgər layihə və ya kitabxana Json.NET-ə bağlıdırsa, onunla işləmək bacarığı hələ də vacibdir.

Təbii ki, System.Text.Json daha sürətlidir və müasir tələblər nəzərə alınaraq hazırlanıb. Amma Newtonsoft.Json hələ də güclü alətdir, xüsusən xüsusi məntiq və ya maksimal çeviklik tələb olunursa.

Newtonsoft.Json necə quraşdırılır?

Bu xarici paket olduğuna görə, NuGet vasitəsilə əlavə edin:

1. Layihəni açın.
2. Solution Explorer-də layihənin üzərinə sağ klik edin.
3. “Manage NuGet Packages...” seçin.
4. Axtarışa Newtonsoft.Json yazın.
5. Paketi seçin və "Install" düyməsini klikləyin.

Quraşdırmadan sonra yeni asılılıq yaranacaq — Json.NET-i istifadə etməyə başlaya bilərsiniz!

Newtonsoft.Json və System.Text.Json imkanlarının müqayisəsi

2. Sadə obyektin serializasiyası və deserializasiyası nümunəsi

Sadə oyun strukturu götürək, bu struktur mühazirədən-mühazirəyə inkişaf edir:

public class Player
{
    public string Name { get; set; }
    public int Health { get; set; }
    public bool IsAlive { get; set; }
    public List<string> Inventory { get; set; }
    public Position Position { get; set; }
}

public class Position
{
    public int X { get; set; }
    public int Y { get; set; }
}

İndi Player obyektini JSON-a saxlayaq və geri bərpa edək:

using Newtonsoft.Json;

Player player1 = new Player
{
    Name = "Aragorn",
    Health = 100,
    IsAlive = true,
    Inventory = new List<string> { "sword", "bow", "healing potion" },
    Position = new Position { X = 10, Y = 25 }
};

// JSON sətirinə serializasiya
string json = JsonConvert.SerializeObject(player1, Formatting.Indented);
Console.WriteLine(json);

// Obyektə deserializasiya
Player player2 = JsonConvert.DeserializeObject<Player>(json);
Console.WriteLine($"Ad: {player2.Name}, sağlamlıq: {player2.Health}");

Hər şey? Demək olar, amma bu yalnız buzdağın ucu idi. Gəlin görək Newtonsoft.Json niyə digər kitabxanalardan daha maraqlıdır və necə daha çevikdir.

3. Formatlaşdırma, tənzimləmələr və geniş parametrlər

Obyekti serializasiya edərkən həm kompakt sətir, həm də gözəl formatlanmış JSON əldə edə bilərsiniz. Davranış parametrlər və tənzimləmələrlə idarə olunur.

Nümunə: Müxtəlif formatlaşdırma variantları

// Gözəl, oxunaqlı JSON
string prettyJson = JsonConvert.SerializeObject(player1, Formatting.Indented);

// Kompakt "minified" JSON
string compactJson = JsonConvert.SerializeObject(player1, Formatting.None);

Serializasiya tənzimləmələri

Lazım gəldikdə incə tənzimləmə üçün JsonSerializerSettings ötürə bilərsiniz:

var settings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore, // null dəyəri olan sahələri atla
    DefaultValueHandling = DefaultValueHandling.Ignore, // defolt dəyəri olan sahələri atla
    Formatting = Formatting.Indented
};
string customJson = JsonConvert.SerializeObject(player1, settings);

Çıxış formatı üzərində maksimal nəzarət əldə edirsiniz: boş sahələri atmaq istəyirsinizsə — buyurun. Hətta private xassələri serializasiya etmək lazımdırsa — kontraktı tənzimləyin.

4. Atributlarla sahələrə və xassələrə nəzarət

Newtonsoft.Json klass daxilində serializasiyanı tənzimləyən güclü atribut sistemini dəstəkləyir.

JsonProperty — Xassələrin adını dəyişdirmək

Əgər JSON protokolu fərqli ad tələb edirsə:

public class Player
{
    [JsonProperty("player_name")]
    public string Name { get; set; }
    // ...
}

Alınan JSON:

{ "player_name": "Aragorn", ... }

JsonIgnore — Xassəni gözardı etmək

public class Player
{
    [JsonIgnore]
    public int Health { get; set; }
}

İndi Health sahəsi serializasiya zamanı JSON-dan yox olacaq.

JsonConverter — Xüsusi çevirmələr

Hər hansı bir sahəni xüsusi konvertorla necə işləmək lazım olduğunu göstərə bilərsiniz.

public class Player
{
    [JsonConverter(typeof(InventoryToStringConverter))]
    public List<string> Inventory { get; set; }
}

(Konvertorlardan daha ətraflı aşağıda.)

5. Daxili obyektlər və kolleksiyalarla işləmək

Json.NET nested obyektlər, massivelər, kolleksiyalar və sözlüklərlə əla işləyir.

Nümunə: Sözlüklər

public class GameStats
{
    public Dictionary<string, int> Scores { get; set; }
}

GameStats stats = new GameStats
{
    Scores = new Dictionary<string, int>
    {
        ["Alice"] = 1023,
        ["Bob"] = 999
    }
};

string statsJson = JsonConvert.SerializeObject(stats, Formatting.Indented);
Console.WriteLine(statsJson);

JSON belə olacaq:

{
  "Scores": {
    "Alice": 1023,
    "Bob": 999
  }
}

6. Mürəkkəb strukturlar: dövri istinadlar, Self-Referencing Objects

Bəzən obyektlər bir-birinə istinad edir. Newtonsoft.Json belə strukturların serializasiyasını xüsusi tənzimləmələrlə dəstəkləyir.

Nümunə: Dövri istinadların həlli

public class Person
{
    public string Name { get; set; }
    public Person Parent { get; set; }
    public List<Person> Children { get; set; }
}

// Dövrləri idarə etmək üçün serializasiya tənzimləyirik
var settings = new JsonSerializerSettings
{
    ReferenceLoopHandling = ReferenceLoopHandling.Ignore // və ya .Serialize
};

Person p1 = new Person { Name = "Ata" };
Person p2 = new Person { Name = "Oğul", Parent = p1 };
p1.Children = new List<Person> { p2 };

string json = JsonConvert.SerializeObject(p1, settings);
Console.WriteLine(json);

Varsayılanda, əgər ReferenceLoopHandling = Error qoysanız, istisna ilə qarşılaşacaqsınız. Bu təsadüfi sonsuz serializasiyadan qoruyur.

7. Dinamik strukturlarla işləmək: JObject, JArray

JSON strukturu əvvəlcədən məlum deyilsə və ya uçuşda dəyişirsə, C#-da sərt tipdən imtina edərək dinamik obyektlərdən istifadə edin.

Əsas tiplər:

• JObject — JSON-obyektin təmsili.
• JArray — massivin təmsili.

using Newtonsoft.Json.Linq;

// Sətiri JObject-ə çevirmək
string json = @"{ 'name': 'Aragorn', 'health': 100 }";
JObject obj = JObject.Parse(json);

Console.WriteLine((string)obj["name"]); // Aragorn
Console.WriteLine((int)obj["health"]);  // 100

// Dinamik şəkildə xüsusiyyət əlavə etmək
obj["class"] = "Ranger";
Console.WriteLine(obj.ToString());

Massiv üzərində iterasiya

string jsonArr = @"['apple', 'banana', 'cherry']";
JArray array = JArray.Parse(jsonArr);

foreach (JToken item in array)
{
    Console.WriteLine(item);
}

8. Versiyalaşdırma və tələb olunan sahələrə dəstək

JSON formatı dəyişə bilər, sahələr yox ola bilər. Atributlar və tənzimləmələrdən istifadə edin:

• [JsonProperty(Required = Required.Always)] — sahənin mövcudluğunu tələb edir (əks halda istisna).
• [JsonProperty(DefaultValueHandling = DefaultValueHandling.Populate)] — sahə yoxdursa defolt dəyəri doldurmaq üçün istifadə olunur.

public class Player
{
    [JsonProperty(Required = Required.Always)]
    public string Name { get; set; }

    [JsonProperty(DefaultValueHandling = DefaultValueHandling.Populate)]
    [DefaultValue(50)]
    public int Health { get; set; }
}

9. Tarixlərin və vaxt formatlarının çevrilməsi

Tarixlərlə işləmək adətən açıq format tələb edir.

var dateSettings = new JsonSerializerSettings
{
    DateFormatString = "yyyy-MM-dd"
};
string json = JsonConvert.SerializeObject(DateTime.Now, dateSettings);
Console.WriteLine(json); // "2024-06-15"

Və deserializasiya zamanı:

string dateJson = "\"2024-06-15\""; // Diqqət: bu dırnaq içində olan sətrdir!
DateTime dt = JsonConvert.DeserializeObject<DateTime>(dateJson);
Console.WriteLine(dt);