.NET-objecten schrijven als JSON (serialiseren)

Artikel
09/07/2024

In dit artikel wordt beschreven hoe u de System.Text.Json naamruimte gebruikt om te serialiseren naar JavaScript Object Notation (JSON). Als u bestaande code Newtonsoft.Jsonovergezet hebt, raadpleegt u Migreren naar System.Text.Json.

Tip

U kunt AI-hulp gebruiken om te serialiseren naar JSON met GitHub Copilot.

Als u JSON naar een tekenreeks of een bestand wilt schrijven, roept u de JsonSerializer.Serialize methode aan.

Voorbeelden van serialisatie

In het volgende voorbeeld wordt JSON gemaakt als een tekenreeks:

using System.Text.Json;

namespace SerializeBasic
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim jsonString As String

De JSON-uitvoer wordt geminimificeerd (witruimte, inspringing en nieuwe regeltekens worden standaard verwijderd).

In het volgende voorbeeld wordt synchrone code gebruikt om een JSON-bestand te maken:

using System.Text.Json;

namespace SerializeToFile
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json"; 
            string jsonString = JsonSerializer.Serialize(weatherForecast);
            File.WriteAllText(fileName, jsonString);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(weatherForecast1)
File.WriteAllText(fileName, jsonString)

In het volgende voorbeeld wordt asynchrone code gebruikt om een JSON-bestand te maken:

using System.Text.Json;

namespace SerializeToFileAsync
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json";
            await using FileStream createStream = File.Create(fileName);
            await JsonSerializer.SerializeAsync(createStream, weatherForecast);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim createStream As FileStream = File.Create(fileName)
Await JsonSerializer.SerializeAsync(createStream, weatherForecast1)

In de voorgaande voorbeelden wordt typedeductie gebruikt voor het type dat wordt geserialiseerd. Een overbelasting van Serialize() een algemene typeparameter:

using System.Text.Json;

namespace SerializeWithGenericParameter
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize<WeatherForecast>(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(Of WeatherForecastWithPOCOs)(weatherForecast)

U kunt gitHub Copilot ook gebruiken om serialisatiecode voor u te genereren. Zie de sectie GitHub Copilot gebruiken in dit artikel voor instructies.

Serialisatiegedrag

Standaard worden alle openbare eigenschappen geserialiseerd. U kunt eigenschappen opgeven die moeten worden genegeerd. U kunt ook privéleden opnemen.
De standaardcoderingsprogramma escapet niet-ASCII-tekens, HTML-gevoelige tekens binnen het ASCII-bereik en tekens die moeten worden ontsnapt volgens de RFC 8259 JSON-specificatie.
Standaard wordt JSON minified. U kunt de JSON mooi afdrukken.
Standaard komen hoofdletters van JSON-namen overeen met de .NET-namen. U kunt de JSON-naambehuizing aanpassen.
Kringverwijzingen worden standaard gedetecteerd en uitzonderingen gegenereerd. U kunt verwijzingen behouden en kringverwijzingen verwerken.
Standaard worden velden genegeerd. U kunt velden opnemen.

Wanneer u indirect in een ASP.NET Core-app gebruikt System.Text.Json , zijn sommige standaardgedragen anders. Zie Webstandaarden voor JsonSerializerOptions voor meer informatie.

Ondersteunde typen zijn onder andere:

.NET-primitieven die zijn toegewezen aan JavaScript-primitieven, zoals numerieke typen, tekenreeksen en Booleaanse waarden.
Door de gebruiker gedefinieerde oude CLR-objecten (POCOs's).
Eendimensionale en onregelmatige matrices (T[][]).
Verzamelingen en woordenlijsten uit de volgende naamruimten:
Zie Ondersteunde verzamelingstypen in System.Text.Jsonvoor meer informatie.

U kunt aangepaste conversieprogramma's implementeren om aanvullende typen af te handelen of om functionaliteit te bieden die niet wordt ondersteund door de ingebouwde conversieprogramma's.

Hier volgt een voorbeeld van hoe een klasse met verzamelingseigenschappen en een door de gebruiker gedefinieerd type wordt geserialiseerd:

using System.Text.Json;

namespace SerializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot",
                SummaryField = "Hot",
                DatesAvailable = new List<DateTimeOffset>() 
                    { DateTime.Parse("2019-08-01"), DateTime.Parse("2019-08-02") },
                TemperatureRanges = new Dictionary<string, HighLowTemps>
                    {
                        ["Cold"] = new HighLowTemps { High = 20, Low = -10 },
                        ["Hot"] = new HighLowTemps { High = 60 , Low = 20 }
                    },
                SummaryWords = new[] { "Cool", "Windy", "Humid" }
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot",
//  "DatesAvailable": [
//    "2019-08-01T00:00:00-07:00",
//    "2019-08-02T00:00:00-07:00"
//  ],
//  "TemperatureRanges": {
//    "Cold": {
//      "High": 20,
//      "Low": -10
//    },
//    "Hot": {
//    "High": 60,
//      "Low": 20
//    }
//  },
//  "SummaryWords": [
//    "Cool",
//    "Windy",
//    "Humid"
//  ]
//}

Public Class WeatherForecastWithPOCOs
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String
    Public SummaryField As String
    Public Property DatesAvailable As IList(Of DateTimeOffset)
    Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
    Public Property SummaryWords As String()
End Class

Public Class HighLowTemps
    Public Property High As Integer
    Public Property Low As Integer
End Class

' serialization output formatted (pretty-printed with whitespace and indentation):
' {
'   "Date": "2019-08-01T00:00:00-07:00",
'   "TemperatureCelsius": 25,
'   "Summary": "Hot",
'   "DatesAvailable": [
'     "2019-08-01T00:00:00-07:00",
'     "2019-08-02T00:00:00-07:00"
'   ],
'   "TemperatureRanges": {
'     "Cold": {
'       "High": 20,
'       "Low": -10
'     },
'     "Hot": {
'       "High": 60,
'       "Low": 20
'     }
'   },
'   "SummaryWords": [
'     "Cool",
'     "Windy",
'     "Humid"
'   ]
' }

Serialiseren naar UTF-8

Het is 5-10% sneller om een UTF-8-bytematrix te serialiseren dan om de op tekenreeks gebaseerde methoden te gebruiken. Dat komt doordat de bytes (als UTF-8) niet hoeven te worden geconverteerd naar tekenreeksen (UTF-16).

Als u wilt serialiseren naar een UTF-8-bytematrix, roept u de JsonSerializer.SerializeToUtf8Bytes methode aan:

byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);

Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)

Er is ook een Serialize Utf8JsonWriter overbelasting beschikbaar.

Serialiseren naar opgemaakte JSON

Als u de JSON-uitvoer wilt afdrukken, stelt u het volgende in JsonSerializerOptions.WriteIndented true:

using System.Text.Json;

namespace SerializeWriteIndented
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot"
//}

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)

Vanaf .NET 9 kunt u ook het inspringteken en de grootte aanpassen met behulp van IndentCharacter en IndentSize.

Tip

Als u herhaaldelijk met dezelfde opties gebruikt JsonSerializerOptions , maakt u niet telkens een nieuw JsonSerializerOptions exemplaar wanneer u deze gebruikt. Gebruik dezelfde instantie voor elke aanroep opnieuw. Zie JsonSerializerOptions-exemplaren opnieuw gebruiken voor meer informatie.

GitHub Copilot gebruiken om te serialiseren naar JSON

U kunt GitHub Copilot in uw IDE gebruiken om code te genereren die wordt gebruikt System.Text.Json om naar JSON te serialiseren.

Als u Visual Studio 2022 versie 17.8 of hoger gebruikt, kunt u de AI-gestuurde GitHub Copilot in Visual Studio proberen om code te genereren die wordt gebruikt System.Text.Json om naar JSON te serialiseren. Dien uw vraag in als prompt in het Copilot-chatvenster, zoals in het volgende voorbeeld. U kunt ook prompts verzenden via inlinechat in het editorvenster zelf.

Notitie

GitHub Copilot wordt mogelijk gemaakt door AI, dus verrassingen en fouten zijn mogelijk. Zorg ervoor dat u alle gegenereerde code of suggesties controleert. Zie de veelgestelde vragen over GitHub Copilot voor meer informatie over het algemene gebruik van GitHub Copilot, productimpact, menselijk toezicht en privacy.

In de volgende tekst ziet u een voorbeeldprompt voor Copilot Chat:

Genereer code om System.Text.Json een object te serialiseren naar een JSON-tekenreeks. Het object bevat de volgende velden: Voornaam (tekenreeks), Achternaam (tekenreeks), Leeftijd (int). Geef voorbeelduitvoer op.

U kunt de prompt aanpassen om objectvelden te gebruiken die aan uw vereisten voldoen.

U kunt chatfuncties, zoals slash-opdrachten, verwijzingen naar bestanden, methoden of klassen en threads, gebruiken om intenties in te stellen en betere antwoorden te krijgen met contextbereik. Voor een bestaande klasse in een project dat is geopend in de IDE, kunt u GitHub Copilot vragen met /generate code to serialize #Classname in #Filename to JSON.

In de volgende uitvoer ziet u een voorbeeld van een Copilot Chat-antwoord:

Sure! Below is an example of how to use System.Text.Json to serialize an object with the specified fields to a JSON string in C#:

using System;
using System.Text.Json;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}

public class Program
{
    public static void Main()
    {
        var person = new Person
        {
            FirstName = "John",
            LastName = "Doe",
            Age = 30
        };

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

**Example Output**
{"FirstName":"John","LastName":"Doe","Age":30}

This code defines a `Person` class, creates an instance of it, and then serializes it to a JSON string using `JsonSerializer.Serialize`. The resulting JSON string is then printed to the console.

Wanneer Copilot een codeblok retourneert, bevat het antwoord opties voor het kopiëren van de code, het invoegen van de code in een nieuw bestand of het bekijken van de code-uitvoer.

Notitie

Uw resultaten kunnen afwijken van wat wordt weergegeven in de voorbeeldantwoorden. AI-modellen zijn niet-deterministisch, wat betekent dat ze verschillende antwoorden kunnen retourneren wanneer ze dezelfde vraag stellen. Dit kan worden veroorzaakt door extra leer- en aanpassing in de loop van de tijd, taalvariatie, wijzigingen in context, zoals uw chatgeschiedenis en meer.

Zie voor meer informatie:

Delen via