Hogyan dolgozzunk JSON adatokkal C# és a Newtonsoft könyvtár segítségével?

A modern szoftverfejlesztésben az adatok cseréje kulcsfontosságú. Legyen szó webes API-król, konfigurációs fájlokról vagy adatbázisok közötti kommunikációról, a JSON (JavaScript Object Notation) formátum szinte mindenhol jelen van. Könnyen olvasható, írható és gépi feldolgozásra is optimalizált, így nem véletlen, hogy a világ egyik legnépszerűbb adatformátumává vált. Ha Ön C# fejlesztő, és hatékonyan szeretne JSON adatokkal dolgozni, akkor a Newtonsoft.Json – más néven Json.NET – könyvtár a legjobb választás. Ez a cikk egy átfogó útmutatót nyújt arról, hogyan aknázhatja ki a benne rejlő lehetőségeket.

Miért pont a Newtonsoft.Json?

Bár a .NET Core 3.1 óta a Microsoft rendelkezik saját beépített JSON szerializálóval (System.Text.Json), a Newtonsoft.Json továbbra is a piacvezető megoldás számos fejlett funkciójának, rugalmasságának és széles körű elterjedtségének köszönhetően. Számos régebbi projektben ez a szabvány, és sok speciális forgatókönyvre kínál egyszerű megoldást, mint például a polimorf szerializálás, a kommentek kezelése vagy a mélyebb hibaellenőrzés. Ráadásul rendkívül gyors és megbízható.

A kezdetek: Telepítés

Mielőtt belemerülnénk a részletekbe, telepítenünk kell a könyvtárat a projektünkbe. Ez a leggyakrabban a NuGet Csomagkezelő segítségével történik. Nyissuk meg a Visual Studio NuGet Csomagkezelő Konzolt (Tools -> NuGet Package Manager -> Package Manager Console), és futtassuk a következő parancsot:

Install-Package Newtonsoft.Json

Vagy a Visual Studio UI-ján keresztül keressünk rá a „Newtonsoft.Json” csomagra, és telepítsük.

Alapok: Szerializálás és Deszerializálás

A JSON adatokkal való munka két fő pillére a szerializálás és a deszerializálás.

1. Szerializálás: C# objektumból JSON string

A szerializálás az a folyamat, melynek során egy C# objektumot (vagy egy adatszerkezetet) egy JSON formátumú stringgé alakítunk. Ezt általában akkor használjuk, ha adatokat szeretnénk elküldeni egy webes API-nak, adatbázisba menteni vagy fájlba írni.

Képzeljünk el egy egyszerű Termék osztályt:

using System;
using Newtonsoft.Json;

public class Termek
{
    public int Id { get; set; }
    public string Nev { get; set; }
    public decimal Ar { get; set; }
    public bool Eladott { get; set; }
    public DateTime GyartasiDatum { get; set; }
}

public class Program
{
    public static void Main(string[] args)
    {
        Termek termek = new Termek
        {
            Id = 1,
            Nev = "Laptop",
            Ar = 1200.50m,
            Eladott = false,
            GyartasiDatum = new DateTime(2023, 10, 26, 14, 30, 0, DateTimeKind.Utc)
        };

        // Objektum szerializálása JSON stringgé
        string jsonString = JsonConvert.SerializeObject(termek);
        Console.WriteLine("Egyszerű JSON:");
        Console.WriteLine(jsonString);

        // Szebb, olvashatóbb formátum beállítása (indentálással)
        string formattedJsonString = JsonConvert.SerializeObject(termek, Formatting.Indented);
        Console.WriteLine("nFormázott JSON:");
        Console.WriteLine(formattedJsonString);
    }
}

A kimenet valami hasonló lesz:

Egyszerű JSON:
{"Id":1,"Nev":"Laptop","Ar":1200.50,"Eladott":false,"GyartasiDatum":"2023-10-26T14:30:00Z"}

Formázott JSON:
{
  "Id": 1,
  "Nev": "Laptop",
  "Ar": 1200.50,
  "Eladott": false,
  "GyartasiDatum": "2023-10-26T14:30:00Z"
}

Láthatjuk, hogy a JsonConvert.SerializeObject() metódus segítségével pillanatok alatt egy C# objektumból szabványos JSON stringet kaptunk. A Formatting.Indented opcióval emberibb olvasásra alkalmas kimenetet is generálhatunk.

2. Deszerializálás: JSON stringből C# objektum

A deszerializálás az előző folyamat fordítottja: egy JSON formátumú stringet alakítunk vissza C# objektummá. Ez tipikusan akkor hasznos, amikor adatokat kapunk egy külső forrásból (pl. egy REST API válaszából), és azokat strukturált C# objektumokként szeretnénk feldolgozni az alkalmazásunkban.

// Vegyük az előzőleg generált JSON stringet
string jsonInput = @"{
  ""Id"": 2,
  ""Nev"": ""Egér"",
  ""Ar"": 25.99,
  ""Eladott"": true,
  ""GyartasiDatum"": ""2023-09-15T10:00:00Z""
}";

// JSON string deszerializálása Termek objektummá
Termek deszerializaltTermek = JsonConvert.DeserializeObject<Termek>(jsonInput);

Console.WriteLine($"nDeszerializált termék adatai:");
Console.WriteLine($"Id: {deszerializaltTermek.Id}");
Console.WriteLine($"Név: {deszerializaltTermek.Nev}");
Console.WriteLine($"Ár: {deszerializaltTermek.Ar}");
Console.WriteLine($"Eladott: {deszerializaltTermek.Eladott}");
Console.WriteLine($"Gyártási dátum: {deszerializaltTermek.GyartasiDatum}");

A JsonConvert.DeserializeObject<T>() metódus a megadott generikus típusba (Termek) próbálja meg átalakítani a JSON string tartalmát. Fontos, hogy a JSON kulcsoknak meg kell egyezniük (kis- és nagybetű érzékenyen, vagy konfigurációtól függően) a C# osztály tulajdonságainak nevével.

Dinamikus JSON kezelés: JObject és JArray

Nem mindig tudjuk előre a JSON struktúráját, vagy csak bizonyos részeit szeretnénk lekérdezni és módosítani anélkül, hogy teljes osztályhierarchiákat kellene definiálnunk. Ilyen esetekben a Newtonsoft.Json JObject és JArray típusai jönnek a segítségünkre. Ezek lehetővé teszik a JSON adatok dinamikus, rugalmas kezelését.

JObject létrehozása és kezelése

A JObject egy JSON objektumot reprezentál, amely kulcs-érték párok gyűjteménye. Hasonlóan működik, mint egy Dictionary<string, object>.

using Newtonsoft.Json.Linq; // Fontos, hogy ezt a namespace-t is importáljuk!

// JObject létrehozása dinamikusan
JObject dynamicProduct = new JObject();
dynamicProduct["Id"] = 3;
dynamicProduct["Nev"] = "Billentyűzet";
dynamicProduct["Ar"] = 75.00m;
dynamicProduct["Jellemzok"] = new JArray("Mechanikus", "RGB világítás");

Console.WriteLine("nDinamikusan létrehozott JObject:");
Console.WriteLine(dynamicProduct.ToString(Formatting.Indented));

// Értékek lekérdezése
int dynamicId = (int)dynamicProduct["Id"];
string dynamicName = (string)dynamicProduct["Nev"];
Console.WriteLine($"nLekérdezett ID: {dynamicId}, Név: {dynamicName}");

// Részobjektum vagy tömb elérése
JArray jellemzok = (JArray)dynamicProduct["Jellemzok"];
Console.WriteLine($"Jellemzők: {string.Join(", ", jellemzok.Select(j => j.ToString()))}");

// Meglévő JSON string JObject-tá alakítása
string complexJson = @"{
  ""Felhasznalo"": {
    ""Nev"": ""Aladár"",
    ""Email"": ""[email protected]"",
    ""Cim"": {
      ""Utca"": ""Fő út 1."",
      ""Varos"": ""Budapest""
    },
    ""Rendelesek"": [
      { ""Id"": 101, ""Osszeg"": 500 },
      { ""Id"": 102, ""Osszeg"": 120 }
    ]
  }
}";

JObject userObject = JObject.Parse(complexJson);

// Értékek elérése JObject-ból
string userName = (string)userObject["Felhasznalo"]["Nev"];
string userCity = (string)userObject["Felhasznalo"]["Cim"]["Varos"];
Console.WriteLine($"Felhasználó neve: {userName}, Város: {userCity}");

// Rendelések száma
JArray rendelesek = (JArray)userObject["Felhasznalo"]["Rendelesek"];
Console.WriteLine($"Rendelések száma: {rendelesek.Count}");

A JObject.Parse() metódus segítségével egy meglévő JSON stringet alakíthatunk JObject-tá, amit aztán indexelővel (["Kulcs"]) vagy a SelectToken() metódussal is bejárhatunk.

JArray és lekérdezések

A JArray JSON tömböt reprezentál. Hasonlóan működik, mint egy List<JToken>.

JArray numbers = new JArray(1, 2, 3, 4, 5);
Console.WriteLine($"nJArray: {numbers.ToString()}");

// Elemek elérése index alapján
int thirdNumber = (int)numbers[2];
Console.WriteLine($"Harmadik szám: {thirdNumber}");

// JSONPath lekérdezések (erőteljesebb keresés)
// Példa: Összes rendelési összeg kinyerése
IEnumerable<JToken> orderAmounts = userObject.SelectTokens("$.Felhasznalo.Rendelesek[*].Osszeg");
Console.WriteLine($"Rendelési összegek:");
foreach (var amount in orderAmounts)
{
    Console.WriteLine($"- {amount.Value<int>}");
}

A JSONPath egy rendkívül erős eszköz komplex JSON struktúrák lekérdezésére, a SelectTokens() metódussal használhatjuk.

Haladó funkciók és attribútumok

A Newtonsoft.Json számos attribútumot és konfigurációs opciót kínál a szerializálási és deszerializálási folyamat finomhangolásához.

1. Tulajdonságok átnevezése: [JsonProperty]

Ha a JSON-ban használt kulcsnév eltér a C# osztály tulajdonságának nevétől, használhatjuk a [JsonProperty] attribútumot:

public class FelhasznaloiAdat
{
    [JsonProperty("userId")] // A JSON-ban "userId", C#-ban "Id"
    public int Id { get; set; }

    [JsonProperty("full_name")] // A JSON-ban "full_name", C#-ban "TeljesNev"
    public string TeljesNev { get; set; }
}

// ...
FelhasznaloiAdat adat = new FelhasznaloiAdat { Id = 123, TeljesNev = "Gipsz Jakab" };
string json = JsonConvert.SerializeObject(adat);
Console.WriteLine($"nJsonProperty használata:n{json}");
// Kimenet: {"userId":123,"full_name":"Gipsz Jakab"}

2. Tulajdonságok figyelmen kívül hagyása: [JsonIgnore]

Néha nem szeretnénk egy adott tulajdonságot szerializálni JSON-ba. Erre szolgál a [JsonIgnore]:

public class BizalmasAdat
{
    public string NyilvanosInfo { get; set; }

    [JsonIgnore] // Ez a tulajdonság nem fog szerepelni a JSON-ban
    public string BizalmasJelszo { get; set; }
}

// ...
BizalmasAdat bAdat = new BizalmasAdat { NyilvanosInfo = "Publikus", BizalmasJelszo = "Titkos123" };
string jsonB = JsonConvert.SerializeObject(bAdat);
Console.WriteLine($"nJsonIgnore használata:n{jsonB}");
// Kimenet: {"NyilvanosInfo":"Publikus"}

3. Kötelező tulajdonságok: [JsonRequired]

Ha egy tulajdonságnak feltétlenül szerepelnie kell a JSON-ban a deszerializálás során, használhatjuk a [JsonRequired] attribútumot. Ha hiányzik, JsonSerializationException dobódik:

public class KotelezoMezo
{
    [JsonRequired]
    public string Nev { get; set; }
    public int Kor { get; set; }
}

// ...
try
{
    string hibasJson = "{ "Kor": 30 }"; // Hiányzik a "Nev" mező
    KotelezoMezo kMezo = JsonConvert.DeserializeObject<KotelezoMezo>(hibasJson);
}
catch (JsonSerializationException ex)
{
    Console.WriteLine($"nHIBA (JsonRequired): {ex.Message}");
    // Kimenet: HIBA (JsonRequired): Required property 'Nev' not found in JSON. Path '', line 1, position 15.
}

4. Egyedi konverterek: JsonConverter

A Newtonsoft.Json nagyszerűen kezeli a legtöbb szabványos adattípust, de előfordulhat, hogy egyedi logikára van szükségünk egy adott típus szerializálásához vagy deszerializálásához. Például, ha egy egyedi enum értéket szeretnénk másképp reprezentálni, vagy egy komplex objektumot egy egyszerű stringgé alakítani. Erre a célra szolgálnak az JsonConverter osztályból származtatott egyedi konverterek.

Létrehozunk egy osztályt, ami örökli a JsonConverter osztályt, és felülírjuk a CanConvert, ReadJson és WriteJson metódusokat.

public class DateTimeToEpochConverter : JsonConverter<DateTime>
{
    public override void WriteJson(JsonWriter writer, DateTime value, JsonSerializer serializer)
    {
        long epoch = (long)(value.ToUniversalTime() - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalSeconds;
        writer.WriteValue(epoch);
    }

    public override DateTime ReadJson(JsonReader reader, Type objectType, DateTime existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        if (reader.TokenType == JsonToken.Integer)
        {
            long epoch = (long)reader.Value;
            return new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc).AddSeconds(epoch).ToLocalTime();
        }
        return DateTime.MinValue; // Vagy dobjunk hibát, ha nem várt formátum
    }
}

public class UjTermek
{
    public int Id { get; set; }
    public string Nev { get; set; }

    [JsonConverter(typeof(DateTimeToEpochConverter))]
    public DateTime MunkabaHozasDatuma { get; set; }
}

// ...
UjTermek ujTermek = new UjTermek
{
    Id = 4,
    Nev = "Okostelefon",
    MunkabaHozasDatuma = new DateTime(2024, 1, 1, 12, 0, 0, DateTimeKind.Local)
};

string customJson = JsonConvert.SerializeObject(ujTermek, Formatting.Indented);
Console.WriteLine($"nEgyedi konverter (epoch idő) használata:n{customJson}");
// Kimenet: "MunkabaHozasDatuma": 1704116400 (körülbelül, időzónától függően)

Ezt a konvertert aztán attribútumként ([JsonConverter(typeof(DateTimeToEpochConverter))]) adhatjuk meg a tulajdonság felett, vagy globálisan a JsonSerializerSettings-ben is regisztrálhatjuk.

Hibakezelés

Amikor külső forrásból származó JSON adatokkal dolgozunk, elengedhetetlen a megfelelő hibakezelés. A JSON string lehet hibásan formázott, hiányozhatnak belőle kötelező mezők, vagy a típusok nem egyeznek. A Newtonsoft.Json ilyen esetekben JsonSerializationException kivételt dobhat.

try
{
    string hibasFormatum = "{ "Id": "nem_egy_szam", "Nev": "Teszt" }";
    Termek t = JsonConvert.DeserializeObject<Termek>(hibasFormatum);
}
catch (JsonSerializationException ex)
{
    Console.WriteLine($"nHIBA a deszerializálás során: {ex.Message}");
    // Kimenet: HIBA a deszerializálás során: Error converting value "nem_egy_szam" to type 'System.Int32'. Path 'Id', line 1, position 19.
}
catch (Exception ex)
{
    Console.WriteLine($"nÁltalános hiba: {ex.Message}");
}

Mindig javasolt a try-catch blokk használata a szerializálási és deszerializálási műveletek körül, különösen, ha nem megbízható adatforrásból származik a JSON.

Ajánlott gyakorlatok

Erősen tipizált objektumok előnyben részesítése: Amikor csak lehetséges, definiáljunk C# osztályokat a JSON struktúrájához. Ez javítja a kód olvashatóságát, karbantarthatóságát és a fordítási idejű típusellenőrzést.
Dinamikus JSON (JObject/JArray) használata: Akkor folyamodjunk hozzá, ha a JSON struktúra ismeretlen, vagy csak nagyon kis részét szeretnénk manipulálni anélkül, hogy teljes osztályhierarchiákat kellene létrehozni.
Null értékek kezelése: Gondoskodjunk róla, hogy az objektumaink kezeljék a null értékeket, ha a JSON-ban előfordulhatnak. Például használjunk nullálható típusokat (int?, DateTime?). A JsonSerializerSettings segítségével konfigurálhatjuk, hogy a null értékeket ignorálja-e a szerializálás.
Teljesítmény: Nagy méretű JSON fájlok vagy adatfolyamok esetén érdemes megfontolni a JsonTextReader és JsonTextWriter közvetlen használatát stream alapú feldolgozáshoz, ami memória-hatékonyabb lehet, mint a teljes string memóriába töltése.
Biztonság: Soha ne deszerializáljunk megbízhatatlan forrásból származó JSON adatokat anélkül, hogy ne validálnánk azokat. Rosszindulatú JSON payload-ok kihasználhatják az alkalmazásunk sebezhetőségeit.

Összefoglalás

A Newtonsoft.Json könyvtár egy rendkívül sokoldalú és erőteljes eszköz a C# fejlesztők számára a JSON adatok kezeléséhez. Legyen szó egyszerű szerializálásról, komplex adatszerkezetek dinamikus manipulálásáról, vagy egyedi konverziós logikák implementálásáról, a Json.NET szinte minden igényt kielégít. A megfelelő attribútumok és a robusztus hibakezelés alkalmazásával stabil és megbízható alkalmazásokat építhetünk, amelyek hatékonyan kommunikálnak a külvilággal JSON formátumban.

Ne habozzon, merüljön el a Newtonsoft.Json világában, kísérletezzen a különböző funkciókkal, és tegye hatékonyabbá a JSON-nal kapcsolatos munkáját C# projektekben!

.NET C++deszerializálás JArray JObject JSON Json.NET Newtonsoft.Json szerializálás Web API