Tilpasse serialiseringsvirkemåte

  • 10 minutter

Metoden JsonSerializer.Serialize brukes til å konvertere et C#-objekt til en JSON-streng (JavaScript Object Notation). Serialisering brukes når du vil lagre eller overføre data i et lett format som enkelt kan leses og behandles av andre systemer. Klassen JsonSerializer er en del av navneområdet System.Text.Json , som gir funksjonalitet for å arbeide med JSON-data i C#.

Følgende kode viser hvordan du konverterer et objekt til en JSON-streng ved hjelp av JsonSerializer.Serialize:


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

Standard virkemåte for serialisering

Følgende standardvirkemåter gjelder når du serialiserer JSON:

  • Som standard serialiseres alle offentlige egenskaper. Du kan angi egenskaper som skal ignoreres. Du kan også inkludere private medlemmer.
  • Standardkoderen unnslipper ikke-ASCII-tegn, HTML-sensitive tegn innenfor ASCII-området og tegn som må unnslippes i henhold til RFC 8259 JSON-spesifikasjonen.
  • JSON er som standard minifisert. Du kan skrive ut JSON.
  • Som standard samsvarer casing av JSON-navn med .NET-navnene. Du kan tilpasse JSON-navnehylsen.
  • Som standard oppdages sirkelreferanser, og unntak oppstod. Du kan bevare referanser og håndtere sirkelreferanser.
  • Felt ignoreres som standard. Du kan inkludere felt.

Klassen JsonSerializer inneholder ulike alternativer og konfigurasjoner for å tilpasse serialiseringsvirkemåten, inkludert muligheten til å ignorere egenskaper, inkludere felt og kontrollere formateringen av JSON-utdataene.

Tilpasse serialiseringsvirkemåte ved hjelp av JsonSerializerOptions

Klassen JsonSerializerOptions lar deg tilpasse serialiseringsvirkemåten for JsonSerializer.Serialize metoden. Du kan for eksempel angi alternativer som om du vil ignorere nullverdier, inkludere felt og kontrollere formateringen av JSON-utdataene.

Følgende egenskaper demonstreres under denne enheten:

  • DefaultIgnoreCondition: Denne egenskapen angir betingelsen der egenskaper med standardverdier ignoreres under serialisering. Det kan bidra til å redusere størrelsen på den serialiserte JSON ved å utelate egenskaper med standardverdier.
  • WriteIndented: Denne egenskapen muliggjør pen utskrift av JSON-utdataene, noe som gjør den mer lesbar ved å legge til innrykk og linjeskift.
  • IncludeFields: Denne egenskapen angir om felt skal inkluderes i serialiseringsprosessen. Som standard er bare egenskaper serialisert.

Andre vanlige egenskaper inkluderer:

  • PropertyNameCaseInsensitive: Denne egenskapen aktiverer samsvar mellom store og små bokstaver for egenskapsnavn under deserialisering. Det kan være nyttig når JSON-dataene har egenskapsnavn med forskjellig foringsrør enn klassedefinisjonen.
  • AllowTrailingCommas: Denne egenskapen tillater etterfølgende komma i JSON-matriser og objekter, noe som kan være nyttig når du arbeider med JSON-data som kan ha etterfølgende komma.
  • IgnoreNullValues: Denne egenskapen angir om nullverdier skal ignoreres under serialisering. Det kan bidra til å redusere størrelsen på den serialiserte JSON ved å utelate egenskaper med nullverdier.
  • Koder: Med denne egenskapen kan du angi en egendefinert koder for å fjerne tegn i JSON-strenger. Det kan være nyttig når du arbeider med spesialtegn i egenskapsnavn eller verdier.

Ignorer egenskaper under serialisering

Klassen JsonSerializer inneholder alternativer for å ignorere egenskaper under serialisering. Dette er nyttig når du vil utelate bestemte egenskaper fra JSON-utdataene, for eksempel sensitiv informasjon eller egenskaper som ikke er relevante for serialisering.

Du kan ignorere egenskaper basert på følgende vilkår:

  • Individuelle egenskaper
  • Alle skrivebeskyttede egenskaper
  • Alle egenskaper for nullverdi
  • Alle standardverdiegenskaper

Ignorer individuelle egenskaper

Hvis du vil ignorere individuelle egenskaper, bruker du [JsonIgnore]-attributtet.

Eksemplet nedenfor viser en type som skal serialiseres. Den viser også JSON-utdataene:


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}

Du kan angi betinget utelukkelse ved å angi attributtets [JsonIgnore]Condition egenskap. Opplistingen JsonIgnoreCondition inneholder følgende alternativer:

  • Alltid – Egenskapen ignoreres alltid. Hvis ingen betingelse er angitt, brukes dette alternativet.
  • Aldri – Egenskapen er alltid serialisert og deserialisert, uavhengig av de globale innstillingene DefaultIgnoreCondition, IgnoreReadOnlyProperties og IgnoreReadOnlyFields.
  • WhenWritingDefault - Egenskapen ignoreres ved serialisering hvis det er en referansetype null, en nullverditype null eller en verditypestandard.
  • WhenWritingNull - Egenskapen ignoreres ved serialisering hvis det er en referansetype null, eller en nullverditype null.

Følgende eksempel illustrerer bruken av [JsonIgnore]-attributtets betingelsesegenskap:


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}

Ignorer alle skrivebeskyttede egenskaper

En egenskap er skrivebeskyttet hvis den inneholder en offentlig getter, men ikke en offentlig setter. Hvis du vil ignorere alle skrivebeskyttede egenskaper når du serialiserer, angir du JsonSerializerOptions.IgnoreReadOnlyProperties til true, som vist i følgende eksempel:


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

jsonString = JsonSerializer.Serialize(weatherForecast, options);

Eksemplet nedenfor viser en type som skal serialiseres. Den viser også JSON-utdataene:


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",
// }

Obs!

Dette alternativet gjelder bare for egenskaper. Hvis du vil ignorere skrivebeskyttede felt når du serialiserer felt, bruker du den JsonSerializerOptions.IgnoreReadOnlyFields globale innstillingen.

Ignorer alle egenskaper for nullverdi

Hvis du vil ignorere alle egenskapene med nullverdi, angir du DefaultIgnoreCondition egenskapen til WhenWritingNull, som vist i eksemplet nedenfor:


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}

Ignorer alle standardverdiegenskaper

Hvis du vil hindre serialisering av standardverdier i egenskaper for verditype, angir du DefaultIgnoreCondition egenskapen til WhenWritingDefault, som vist i følgende eksempel:


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"}

Innstillingen WhenWritingDefault forhindrer også serialisering av referansetype for nullverdi og egenskaper for verditype som kan nullstilles.

Inkluder felt under serialisering

Som standard serialiseres bare egenskaper, men du kan konfigurere serialisereren til å inkludere felt også. Bruk den JsonSerializerOptions.IncludeFields globale innstillingen eller attributtet [JsonInclude] til å inkludere felt når du serialiserer eller deserialiserer, som vist i følgende eksempel:


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"}

Hvis du vil ignorere skrivebeskyttede felt, bruker du den globale innstillingen JsonSerializerOptions.IgnoreReadOnlyFields.

Skrive JSON-filer

Å skrive JSON-filer er en vanlig oppgave når du arbeider med JSON-data. Klassen JsonSerializer inneholder metoder for å serialisere objekter til JSON-strenger, som deretter kan lagres i filer. Metoden File.WriteAllText kan brukes til å skrive JSON-strengen til en fil.

Følgende eksempel viser hvordan du serialiserer et objekt til JSON og lagrer det i en fil:


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.");
      }
}

Sammendrag

I denne enheten lærte du hvordan du tilpasser serialiseringsvirkemåte når du serialiserer C#-objekter ved hjelp av JsonSerializer.Serialize metoden. Du lærte hvordan du ignorerer egenskaper og felt under serialisering og hvordan du skriver JSON-data til filer. Denne kunnskapen er avgjørende for å arbeide med JSON-data i C#-programmer.