.NET-objecten schrijven als JSON (serialiseren)

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:

  • System.Collections
  • System.Collections.Generic
  • System.Collections.Immutable
  • System.Collections.Concurrent
  • System.Collections.Specialized
  • System.Collections.ObjectModel

  Zie Ondersteunde typen 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 SerializeUtf8JsonWriter overbelasting beschikbaar.

Serialiseren naar opgemaakte JSON

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

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. U kunt de prompt aanpassen om objectvelden te gebruiken die aan uw vereisten voldoen.

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

Generate code to use System.Text.Json to serialize an object to a JSON string.
The object contains the following fields: FirstName (string), Lastname (string), Age (int).
Provide example output.

GitHub Copilot wordt mogelijk gemaakt door AI, dus verrassingen en fouten zijn mogelijk. Zie Veelgestelde vragen over Copilotvoor meer informatie.

Meer informatie over GitHub Copilot in Visual Studio en GitHub Copilot in VS Code.