Helló C#! Helló Világ! 2.1

  2. Home
  4. Docs
  6. Helló C#! Helló Világ! 2.1
  8. 12. Modern alkalmazásfejlesztés
  10. JSON Serialization – System.Text.Json

JSON Serialization – System.Text.Json

.NET Core 3.0 óta a keretrendszer beépítetten tartalmaz egy JSON szerializálót, ami a System.Text.Json névtérben található. Használata hasonló a Newtonsoft JSON szerializálóhoz. A szerializálásra és deszerializálásra itt a JsonSerializer statikus osztályt használhatjuk.

string Serialize<TValue> (TValue value, JsonSerializerOptions? options = default);
void Serialize<TValue> (Stream utf8Json, TValue value, JsonSerializerOptions? options = default);

Szerializáció esetén megadhatunk egy JsonSerializerOptions példányt, ami a szerializáló működését befolyásolja. A JsonSerializerOptions lehetőséget biztosít arra, hogy a null értékek ne kerüljenek szerializálásra (IgnoreNullValues), megadhatjuk, hogy a JSON dokumentumot formázni szeretnénk-e, (WriteIndented), illetve sok egyéb beállítást is.

Deszerializálni itt a Deserialize metódussal tudunk:

TValue? Deserialize<TValue> (string json, JsonSerializerOptions? options = default);
TValue?  Deserialize<TValue> (Stream utf8Json, JsonSerializerOptions? options = default);

Itt is opcionálisan megadhatunk egy JsonSerializerOptions példányt, ami a deszerializáló működését befolyásolja.

Beállítások

Ha úgy döntenénk, hogy nem az alap beállításokat használjuk, akkor szerializáció és deszerializáció közben is ugyan azokat a beállításokat használjuk. Ha ezek eltérnek szerializáció és deszerializáció közben, akkor könnyen kivételre futhat a visszaolvasás.

Az osztály fontosabb beállításai:

public bool IncludeFields { get; set; }
public bool IgnoreReadOnlyFields { get; set; }

Osztályon belüli field-ek szerializációját befolyásolja az IncludeFields tulajdonság. Alapértelmezetten ki van kapcsolva, vagyis csak az osztály tulajdonságai szerializálódnak. Az IgnoreReadOnlyFields bekapcsolt IncludeFields esetén jön jól, mivel ebben az esetben a readonly módosítóval ellátott adattagok nem szerializálódnak. A kettőt együtt érdemes használni.

public bool IgnoreReadOnlyProperties { get; set; }

Csak olvasható (get) property-k kihagyása. Alapértelmezetten kikapcsolt.

public bool WriteIndented { get; set; }

Formázott kimenet írása, vagy sem. Alapértelmezetten kikapcsolt, vagyis a kimeneti JSON sortörések és formázások nélkül kerül kiírásra, ami hálózati átvitel esetén hasznos. Azonban ha lemezre írjuk a fájlt és feltétel, hogy kézzel is könnyen szerkeszthető legyen a fájl, akkor érdemes bekapcsolni.

public JsonNamingPolicy? PropertyNamingPolicy { get; set; }

Kiírt adattagok elnevezéséhez használt beállítás. C# esetén a tulajdonságok nevei PascalCase-t követnek, de JavaScript és ebből adódóan JSON esetén a camelCase a bevett szokás. A JsonNamingPolicy egy absztakt osztály, ami segítségével saját elnevezési szabályokat is implementálhatunk, vagy használhatjuk az osztály CamelCase statikus adattagját, ha camelCase kell. Ezt érdemes beállítani, ha a szerializált adat JavaScript-ből lesz feldolgozva. Ha nem állítunk neki értéket, akkor marad PascalCase beállításon.

public bool PropertyNameCaseInsensitive { get; set; }

Ez a beállítás deszerializáció során alkalmazott. Bekapcsolt állapotában nem számít különbségnek, hogy kis vagy nagybetűk szerepelnek egy tulajdonság nevében. Ez hasznos lehet, ha kézzel szerkesztett bemenetet dolgozunk fel, de a teljesítményre negatív hatása van.

JsonIgnoreCondition DefaultIgnoreCondition { get; set; }

Azt befolyásolja, hogy az alapértelmezett értékkel rendelkező (pl. egy int esetén 0, vagy string esetén null) tulajdonság szerializálva legyen-e vagy sem. A JsonIgnoreCondition egy enum típus, ami az alábbi értékeket veheti fel:

  • Never

    Alapbeállítás. A tulajdonság mindig szerializálva és deszerializálva lesz.

  • WhenWritingDefault

    A tulajdonság kihagyásra kerül, ha az értéke megegyezik a típus alapértelmezett értékével.

  • WhenWritingNull

    A tulajdonság kihagyásra kerül, ha az értéke null.

public IList<JsonConverter> Converters { get; }

A szerializáció során használt konvertereket határozza meg.

Típus konverterek

Mivel a JSON a JavaScript típusrendszerét örökli, közel sem rendelkezik olyan széleskörű típusrendszerrel, mint a .NET és a C#. Ez a legtöbb esetben nem okoz problémát, de összetett típusok kezelése esetén okozhat fejfájást. Például ha enum értékekkel dolgozunk. JSON esetén nincs enum, ezért ezek az értékek számként íródnak ki. Azonban enum értékek szám szerinti kiírása nem a legjobb megoldás.

Mégpedig azért, mert ha az enum típusunkban nincs az értékeknek explicit szám megfeleltetés, akkor a kiírt fájlban a 12-es index érték elég kritikus, arról nem is beszélve, hogy mi van akkor, ha később bővül az enum és nem a végén bővíti a programozó? Ebben az esetben a 12-es kiírt érték már nem biztos, hogy azt jelenti, amit kíírtunk. Éppen ezért jobb lenne ezen típusokat szövegesen, név alapján kiírni.

Itt jönnek képbe a típus konverterek, amik segítségével bármilyen összetett típust tudunk egy primitív JSON típusra konvertálni. Jelen esetben például szöveggé.

A korábban említett enum példára gondoltak a .NET fejlesztők, ezért van rá beépített konverter, aminek a neve JsonStringEnumConverter, így ezt nem kell magunknak lefejleszteni. Azonban számos típus van, amit hasonlóan egy soros szövegként is tárolhatunk, ahelyett, hogy komplett objektumként szerializálnánk. Ilyen például a CultureInfo, amit egy előre meghatározott int szám alapján is helyre tudunk állítani, vagy név alapján is. 1

Ahhoz, hogy típus konvertert írjunk, több lehetőségünk is van. A legegyszerűbb azonban, ha a JsonConverter<T> típusból származunk le.

Ez az osztály két metódussal rendelkezik, amit meg kell valósítanunk:

T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)

A Read metódus a típus felolvasásakor fog meghívódni, míg a Write íráskor. A metódusok esetén kapott Utf8JsonReader és Utf8JsonWriter objektumok JSON tokenek2 (szövegek, számok, azonosítók) olvasását és írását teszik lehetővé.

Nézzünk egy példát, ami segítségével egy CultureInfo példány szerializálható szövegként:

public class CultureInfoConverter : JsonConverter<CultureInfo>
{
    public override CultureInfo? Read(ref Utf8JsonReader reader, 
                                      Type typeToConvert, 
                                      JsonSerializerOptions options)
    {
        return new CultureInfo(reader.GetString()!);
    }

     public override void Write(Utf8JsonWriter writer,
                                CultureInfo value, 
                                JsonSerializerOptions options)
     {
        writer.WriteStringValue(value.Name);
     }
}

Példaprogram

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

namespace JsonConvertPelda
{
    //Osztály a CultureInfo osztállyal
    //Ezt szerializáljuk
    public class Class
    {
        public CultureInfo Culture { get; init; }

        public Class()
        {
            Culture = CultureInfo.InvariantCulture;
        }
    }

    //Konverter
    public class CultureInfoConverter : JsonConverter<CultureInfo>
    {
        public override CultureInfo? Read(ref Utf8JsonReader reader,
                                          Type typeToConvert,
                                          JsonSerializerOptions options)
        {
            return new CultureInfo(reader.GetString()!);
        }

        public override void Write(Utf8JsonWriter writer,
                                   CultureInfo value,
                                   JsonSerializerOptions options)
        {
            writer.WriteStringValue(value.Name);
        }
    }

    internal static class Program
    {
        private static void Main(string[] args)
        {
            Class toSerialize = new Class
            {
                Culture = new CultureInfo("hu-HU")
            };

            Console.Write("Serializáció előtt: ");
            Console.WriteLine(toSerialize.Culture.DisplayName);

            Console.Write("Konverter nélkül: ");
            try
            {
                //Konverter nélkül megpróbáljuk szerializálni
                string withoutConverter = JsonSerializer.Serialize(toSerialize);
                Console.WriteLine(withoutConverter);
            }
            catch (Exception) 
            {
                //Nem fog sikerülni
                Console.WriteLine($"Nem sikerült");
            }

            //Konverter beállítása
            var options = new JsonSerializerOptions
            {
                WriteIndented = true,
            };
            options.Converters.Add(new CultureInfoConverter());

            //szerializáció
            string withConverter = JsonSerializer.Serialize(toSerialize, options);

            Console.Write("Konverterrel: ");
            Console.WriteLine(withConverter);

            //Deszerializáció és teszt:
            Class? read = JsonSerializer.Deserialize<Class>(withConverter, options);

            Console.Write("Deszerializáció után: ");
            Console.WriteLine(read?.Culture.DisplayName);
        }
    }
}

A program kimenete:

$
Serializáció elÅ‘tt: magyar (Magyarország)
Konverter nélkül: Nem sikerült
Konverterrel: {
  "Culture": "hu-HU"
}
Deszerializáció után: magyar (Magyarország)

Polimorfikus szerializáció

A System.Text.Json szerializáló előnye, hogy a 7.0-ás változattól támogatja a polimorfikus szerializációt is. Ez azt jelenti, hogy ha van egy osztály struktúránk és az őst szerializáljuk, akkor nem csak az őstípusban megtalálható tulajdonságok szerializálódnak, hanem a leszármazott osztályok tulajdonságai is és deszerializációkor pedig megfelelően helyreállnak. Az alábbi példa ezt szemlélteti:

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

namespace JsonPolimorph
{

    [JsonDerivedType(typeof(Point3D), typeDiscriminator: "3d")]
    public class Point2D
    {
        public float X { get; init; }
        public float Y { get; init; }

        public override string ToString()
            => $"x: {X}; y:{Y}";
    }

    public class Point3D : Point2D
    {
        public float Z { get; init; }

        public override string ToString()
            => $"x: {X}; y:{Y}; z: {Z}";
    }

    internal static class Program
    {
        private static void Main(string[] args)
        {
            Point2D[] array = new[]
            {
                new Point2D { X = 1, Y = 2 },
                new Point3D { X = 3, Y = 4, Z = 5 },
            };

            string json = JsonSerializer.Serialize(array, new JsonSerializerOptions
            {
                WriteIndented = true
            });

            Console.WriteLine(json);

            Point2D[]? deserialized = JsonSerializer.Deserialize<Point2D[]>(json);
            if (deserialized != null)
            {
                foreach (var item in deserialized)
                {
                    Console.WriteLine(item);
                }
            }
        }
    }
}

A program kimenete:

$
[
  {
    "X": 1,
    "Y": 2
  },
  {
    "$type": "3d",
    "Z": 5,
    "X": 3,
    "Y": 4
  }
]
x: 1; y:2
x: 3; y:4; z: 5

A példa kimenetéből látszódik, hogy ugyan Point2D típusú tömböt szerializálunk, deszerializációkor mégis visszakapjuk az eredeti kollekciót, mintha mi sem történt volna.

A Point2D ősosztályon egy JsonDerivedType attribútum lett megadva, ami a kiszerializált JSON dokumentumban a $type mezőt hozzáadja a leszármazott objektumunk szerializációjakor. Ezen typeDiscriminator azonosító segítségével tudja deszerializációkor a rendszer, hogy milyen objektumot is hozzon létre. Ha ennek az attribútumnak a megadását elmulasztanánk, akkor numerikus azonosítókat használna a rendszer, amivel ugyanúgy működne, de emberileg nehezebben olvasható lenne a JSON dokumentum. Ez nem feltétlen baj, de hibakereséshez nagy segítség tud lenni, ha valami szöveges typeDiscriminator értéket használunk. Itt megjegyezném, hogy ugyan bármilyen szöveget megadhatunk, de van, amit nem érdemes. Például a typeDiscriminator értéke sose reprezentálja közvetlenül a kódunkban a típus nevét, mert ez lehet biztonsági kockázat: információt árul el a programunk belső struktúrájáról.

Ha több örökölt típus van, amit szerializálni szeretnénk, akkor mindegyikhez egy JsonDerivedType attribútumot fel kell vennünk.

  1. A Windows és a .NET által támogatott Language ID-k numerikus és szöveges változatait a https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c címen található dokumentum részletezi.↩

  2. A JSON szabvány által elfogadott karakterek, jelölÅ‘k: https://www.json.org/json-en.html↩

Tags , , , , ,