Migreren van Newtonsoft.Json naar System.Text.Json

In dit artikel wordt beschreven hoe u migreert van Newtonsoft.Json naar System.Text.Json.

De System.Text.Json naamruimte biedt functionaliteit voor het serialiseren naar en deserialiseren van JavaScript Object Notation (JSON). De System.Text.Json bibliotheek is opgenomen in de runtime voor .NET Core 3.1 en latere versies. Installeer het System.Text.Json NuGet-pakket voor andere doelframeworks. Het pakket ondersteunt:

• .NET Standard 2.0 en latere versies
• .NET Framework 4.6.2 en latere versies
• .NET Core 2.0, 2.1 en 2.2

System.Text.Json is voornamelijk gericht op naleving van prestaties, beveiliging en standaarden. Het heeft enkele belangrijke verschillen in het standaardgedrag en is niet bedoeld om functiepariteit met Newtonsoft.Json te hebben. Voor sommige scenario's System.Text.Json heeft momenteel geen ingebouwde functionaliteit, maar er zijn aanbevolen tijdelijke oplossingen. Voor andere scenario's zijn tijdelijke oplossingen niet praktisch.

Het System.Text.Json team investeert in het toevoegen van de functies die het vaakst worden aangevraagd. Als uw toepassing afhankelijk is van een ontbrekende functie, kunt u een probleem indienen in de GitHub-opslagplaats dotnet/runtime om erachter te komen of ondersteuning voor uw scenario kan worden toegevoegd.

Het grootste deel van dit artikel gaat over het gebruik van de JsonSerializer API, maar bevat ook richtlijnen voor het gebruik van het JsonDocument (dat het documentobjectmodel of dom vertegenwoordigt) Utf8JsonReaderen Utf8JsonWriter typen.

In Visual Basic kunt u Utf8JsonReader niet gebruiken, wat betekent dat u ook geen aangepaste conversieprogramma's kunt schrijven. Voor de meeste tijdelijke oplossingen die hier worden weergegeven, moet u aangepaste conversieprogramma's schrijven. U kunt een aangepast conversieprogramma schrijven in C# en deze registreren in een Visual Basic-project. Zie Visual Basic-ondersteuning voor meer informatie.

Tabel met verschillen

De volgende tabel bevat Newtonsoft.Json functies en System.Text.Json equivalenten. De equivalenten vallen in de volgende categorieën:

• ✔️ Ondersteund door ingebouwde functionaliteit. Voor het verkrijgen van vergelijkbaar gedrag van System.Text.Json kan het gebruik van een kenmerk of globale optie nodig zijn.
• ⚠ϑ Niet ondersteund, maar tijdelijke oplossing is mogelijk. De tijdelijke oplossingen zijn aangepaste conversieprogramma's, die mogelijk geen volledige pariteit met Newtonsoft.Json functionaliteit bieden. Voor sommige hiervan wordt voorbeeldcode gegeven als voorbeelden. Als u van deze Newtonsoft.Json functies afhankelijk bent, zijn voor migratie wijzigingen in uw .NET-objectmodellen of andere codewijzigingen vereist.
• ❌ Niet ondersteund en tijdelijke oplossing is niet praktisch of mogelijk. Als u van deze Newtonsoft.Json functies afhankelijk bent, is migratie niet mogelijk zonder belangrijke wijzigingen.

Dit is geen volledige lijst met Newtonsoft.Json functies. De lijst bevat veel van de scenario's die zijn aangevraagd in GitHub-problemen of StackOverflow-berichten . Als u een tijdelijke oplossing implementeert voor een van de hier vermelde scenario's die momenteel geen voorbeeldcode hebben en als u uw oplossing wilt delen, selecteert u deze pagina in de sectie Feedback onder aan deze pagina. Dit maakt een probleem in de GitHub-opslagplaats van deze documentatie en vermeldt dit ook in de sectie Feedback op deze pagina.

Verschillen in standaardgedrag

System.Text.Json is standaard strikt en vermijdt elke schatting of interpretatie namens de beller, waarbij deterministisch gedrag wordt benadrukt. De bibliotheek is opzettelijk ontworpen op deze manier voor prestaties en beveiliging. Newtonsoft.Json is standaard flexibel. Dit fundamentele verschil in ontwerp ligt achter een groot aantal van de volgende specifieke verschillen in standaardgedrag.

Hoofdletterongevoelige deserialisatie

Tijdens de deserialisatie voert Newtonsoft.Json standaard een niet-hoofdlettergevoelige vergelijking van eigenschapsnamen uit. De System.Text.Json standaardwaarde is hoofdlettergevoelig, wat betere prestaties biedt, omdat er sprake is van een exacte overeenkomst. Zie Hoofdlettergevoelige eigenschapskoppeling voor informatie over het uitvoeren van niet-hoofdlettergevoelige overeenkomsten.

Als u System.Text.Json indirect gebruikmaakt van ASP.NET Core, hoeft u niets te doen om gedrag te krijgen, zoals Newtonsoft.Json. ASP.NET Core geeft de instellingen op voor eigenschappennamen van kameelbehuizing en hoofdlettergevoelige overeenkomsten wanneer deze wordt gebruikt System.Text.Json.

ASP.NET Core schakelt ook standaard het deserialiseren van gequoteerde getallen in.

Minimale escapetekens

Tijdens de serialisatie staat Newtonsoft.Json het relatief vrij toe dat tekens doorgelaten worden zonder dat ze ontsnappen. Dat wil gezegd, het vervangt ze niet door \uxxxx waar xxxx het codepunt van het teken is. Waar het hen ontgaat, gebeurt dit door een \ te versturen vóór het teken (bijvoorbeeld, " wordt \"). System.Text.Json ontsnapt standaard aan meer tekens om verdedigingsbeveiligingen op verschillende lagen te bieden tegen cross-site scripting (XSS) aanvallen of aanvallen waarbij informatie wordt onthuld, en doet dit door middel van een reeks van zes tekens. System.Text.Json ontsnapt standaard alle niet-ASCII-tekens, dus hoeft u niets te doen als u StringEscapeHandling.EscapeNonAscii in Newtonsoft.Json gebruikt. System.Text.Json escapen ook html-gevoelige tekens, standaard. Zie Tekencodering aanpassen voor informatie over het overschrijven van het standaardgedrag System.Text.Json.

Opmerkingen

Tijdens de deserialisatie negeert Newtonsoft.Json standaard de JSON-opmerkingen. De System.Text.Json standaardinstelling is uitzonderingen voor opmerkingen te genereren omdat de RFC 8259-specificatie deze niet bevat. Zie Opmerkingen en volgkomma's toestaan voor informatie over het toestaan van opmerkingen.

Afsluitkomma's

Tijdens de deserialisatie negeert Newtonsoft.Json standaard komma's aan het einde. Het negeert ook meerdere volgkomma's (bijvoorbeeld [{"Color":"Red"},{"Color":"Green"},,]). De System.Text.Json standaardinstelling is uitzonderingen voor volgkomma's te genereren omdat de RFC 8259-specificatie ze niet toestaat. Raadpleeg System.Text.Json voor informatie over hoe u kunt accepteren. Er is geen manier om meerdere volgkomma's toe te staan.

Voorrang van omzetterregistratie

De Newtonsoft.Json registratieprioriteit voor aangepaste conversieprogramma's is als volgt:

• Kenmerk op eigenschap
• Kenmerk op type
• Converters collectie

Deze volgorde betekent dat een aangepast conversieprogramma in de Converters verzameling wordt overschreven door een conversieprogramma dat is geregistreerd door een kenmerk toe te passen op het typeniveau. Beide registraties worden overschreven door een kenmerk op eigenschapsniveau.

De System.Text.Json registratieprioriteit voor aangepaste conversieprogramma's verschilt:

• Kenmerk op eigenschap
• Converters collectie
• Kenmerk op type

Het verschil hier is dat een aangepast conversieprogramma in de Converters verzameling een kenmerk op typeniveau overschrijft. De bedoeling achter deze volgorde van prioriteit is zodat wijzigingen tijdens runtime ontwerpkeuzes overschrijven. Er is geen manier om de prioriteit te wijzigen.

Zie Een aangepast conversieprogramma registreren voor meer informatie over de registratie van aangepaste conversieprogramma's.

Maximale diepte

De nieuwste versie van Newtonsoft.Json de app heeft standaard een maximale dieptelimiet van 64. System.Text.Json heeft ook een standaardlimiet van 64 en kan worden geconfigureerd door deze in te stellen JsonSerializerOptions.MaxDepth.

Als u System.Text.Json indirect gebruikmaakt van ASP.NET Core, is de standaardlimiet voor maximale diepte 32. De standaardwaarde is hetzelfde als voor modelbinding en wordt ingesteld in de JsonOptions-klasse.

JSON-tekenreeksen (eigenschapsnamen en tekenreekswaarden)

Tijdens de deserialisatie accepteert Newtonsoft.Json eigenschapsnamen tussen dubbele aanhalingstekens, enkele aanhalingstekens of zonder aanhalingstekens. Hiermee worden tekenreekswaarden tussen dubbele aanhalingstekens of enkele aanhalingstekens geaccepteerd. Accepteert bijvoorbeeld Newtonsoft.Json de volgende JSON:

{
  "name1": "value",
  'name2': "value",
  name3: 'value'
}

System.Text.Json accepteert alleen eigenschapsnamen en tekenreekswaarden tussen dubbele aanhalingstekens omdat deze indeling is vereist voor de RFC 8259-specificatie en is de enige indeling die als geldige JSON wordt beschouwd.

Een waarde tussen enkele aanhalingstekens resulteert in een JsonException met het volgende bericht:

''' is an invalid start of a value.

Niet-tekenreekswaarden voor tekenreekseigenschappen

Newtonsoft.Json accepteert niet-tekenreekswaarden, zoals een getal of de letterlijke waarden true en falsevoor deserialisatie op eigenschappen van het type tekenreeks. Hier volgt een voorbeeld van JSON dat Newtonsoft.Json deserializeert naar de volgende klasse:

{
  "String1": 1,
  "String2": true,
  "String3": false
}

public class ExampleClass
{
    public string String1 { get; set; }
    public string String2 { get; set; }
    public string String3 { get; set; }
}

System.Text.Json deserialiseert niet niet-tekenreekswaarden in tekenreekseigenschappen. Een niet-tekenreekswaarde die is ontvangen voor een tekenreeksveld resulteert in een JsonException met het volgende bericht:

The JSON value could not be converted to System.String.

Scenario's met behulp van JsonSerializer

Sommige van de volgende scenario's worden niet ondersteund door ingebouwde functionaliteit, maar tijdelijke oplossingen zijn mogelijk. De tijdelijke oplossingen zijn aangepaste conversieprogramma's, die mogelijk geen volledige pariteit met Newtonsoft.Json functionaliteit bieden. Voor sommige hiervan wordt voorbeeldcode gegeven als voorbeelden. Als u van deze Newtonsoft.Json functies afhankelijk bent, zijn voor migratie wijzigingen in uw .NET-objectmodellen of andere codewijzigingen vereist.

In sommige van de volgende scenario's zijn tijdelijke oplossingen niet praktisch of mogelijk. Als u van deze Newtonsoft.Json functies afhankelijk bent, is migratie niet mogelijk zonder belangrijke wijzigingen.

Getallen tussen aanhalingstekens toestaan of schrijven

Newtonsoft.Json kan getallen serialiseren of deserialiseren die worden vertegenwoordigd door JSON-tekenreeksen (omgeven door aanhalingstekens). Het kan bijvoorbeeld accepteren: {"DegreesCelsius":"23"} in plaats van {"DegreesCelsius":23}. Als u dit gedrag wilt inschakelenSystem.Text.Json, stel JsonSerializerOptions.NumberHandling in op WriteAsString of AllowReadingFromString, of gebruik het attribuut [JsonNumberHandling].

Als u System.Text.Json indirect gebruikmaakt van ASP.NET Core, hoeft u niets te doen om gedrag te krijgen, zoals Newtonsoft.Json. ASP.NET Core specificeert webstandaarden wanneer het System.Text.Json gebruikt, en webstandaarden staan getallen tussen aanhalingstekens toe.

Voor meer informatie, zie Getallen tussen aanhalingstekens toestaan of schrijven.

Geef de te gebruiken constructor op bij het deserialiseren

Newtonsoft.Json [JsonConstructor] Met het kenmerk kunt u opgeven welke constructor moet worden aangeroepen bij het deserialiseren van een POCO.

System.Text.Json heeft ook een kenmerk [JsonConstructor]. . Zie Onveranderbare typen en records voor meer informatie.

Een eigenschap voorwaardelijk negeren

Newtonsoft.Json heeft verschillende manieren om een eigenschap voorwaardelijk te negeren bij serialisatie of deserialisatie:

• DefaultContractResolver hiermee kunt u eigenschappen selecteren die u wilt opnemen of negeren, op basis van willekeurige criteria.
• Met de instellingen voor NullValueHandling en DefaultValueHandling op JsonSerializerSettings kunt u aangeven dat alle eigenschappen met een null-waarde of standaardwaarde moeten worden genegeerd.
• Met de NullValueHandling en DefaultValueHandling instellingen op het [JsonProperty] kenmerk kunt u afzonderlijke eigenschappen opgeven die moeten worden genegeerd wanneer deze zijn ingesteld op null of de standaardwaarde.

System.Text.Json biedt de volgende manieren om eigenschappen of velden te negeren tijdens het serialiseren:

• Het kenmerk [JsonIgnore] voor een eigenschap zorgt ervoor dat de eigenschap tijdens de serialisatie wordt weggelaten uit de JSON.
• Met de algemene optie IgnoreReadOnlyProperties kunt u alle alleen-lezeneigenschappen negeren.
• Als u velden opgeeft, kunt u met de JsonSerializerOptions.IgnoreReadOnlyFields algemene optie alle alleen-lezen velden negeren.
• Met de DefaultIgnoreCondition algemene optie kunt u alle eigenschappen van het waardetype met standaardwaarden negeren of alle eigenschappen van het verwijzingstype negeren die null-waarden hebben.

Bovendien kunt u in .NET 7 en latere versies het JSON-contract aanpassen om eigenschappen te negeren op basis van willekeurige criteria. Zie Aangepaste contracten voor meer informatie.

Openbare en niet-openbare velden

Newtonsoft.Json kan velden en eigenschappen serialiseren en deserialiseren.

Gebruik System.Text.Jsonde JsonSerializerOptions.IncludeFields algemene instelling of het kenmerk [JsonInclude] om openbare velden op te nemen bij het serialiseren of deserialisatie. Zie Velden opnemen voor een voorbeeld.

Objectverwijzingen en handlelussen behouden

Newtonsoft.Json Serialiseert standaard op waarde. Als een object bijvoorbeeld twee eigenschappen bevat die een verwijzing naar hetzelfde Person object bevatten, worden de waarden van de eigenschappen van dat Person object gedupliceerd in de JSON.

Newtonsoft.Json heeft een PreserveReferencesHandling instelling JsonSerializerSettings waarmee u naslaginformatie kunt serialiseren:

• Er wordt een id-metagegevens toegevoegd aan de JSON die voor het eerste Person object is gemaakt.
• De JSON die voor het tweede Person object is gemaakt, bevat een verwijzing naar die id in plaats van eigenschapswaarden.

Newtonsoft.Json heeft ook een ReferenceLoopHandling instelling waarmee u kringverwijzingen kunt negeren in plaats van een uitzondering te genereren.

Om verwijzingen te behouden en om te gaan met kringverwijzingen in System.Text.Json, stelt u JsonSerializerOptions.ReferenceHandler in op Preserve. De ReferenceHandler.Preserve instelling is gelijk aan PreserveReferencesHandling = PreserveReferencesHandling.All in Newtonsoft.Json.

De ReferenceHandler.IgnoreCycles optie heeft gedrag dat vergelijkbaar is met Newtonsoft.JsonReferenceLoopHandling.Ignore. Een verschil is dat de System.Text.Json implementatie referentielussen vervangt door het null JSON-token in plaats van de objectverwijzing te negeren. Zie Kringverwijzingen negeren voor meer informatie.

Net als de Newtonsoft.JsonReferenceResolver definieert de System.Text.Json.Serialization.ReferenceResolver klasse het gedrag van het behouden van verwijzingen op serialisatie en deserialisatie. Maak een afgeleide klasse om aangepast gedrag op te geven. Zie GuidReferenceResolver voor een voorbeeld.

Sommige gerelateerde Newtonsoft.Json functies worden niet ondersteund:

• JsonPropertyAttribute.IsReference
• JsonPropertyAttribute.ReferenceLoopHandling

Zie Verwijzingen behouden en kringverwijzingen verwerken voor meer informatie.

Woordenlijst met niet-tekenreekssleutel

Zowel Newtonsoft.Json als System.Text.Json ondersteuning voor verzamelingen van het type Dictionary<TKey, TValue>. Zie Ondersteunde sleuteltypenvoor meer informatie over ondersteunde sleuteltypen.

Typen zonder ingebouwde ondersteuning

System.Text.Json biedt geen ingebouwde ondersteuning voor de volgende typen:

• DataTable en aanverwante typen (voor meer informatie, zie Ondersteunde typen)
• ExpandoObject
• TimeZoneInfo
• BigInteger
• DBNull
• Type
• ValueTuple en de bijbehorende generieke typen

Aangepaste conversieprogramma's kunnen worden geïmplementeerd voor typen die geen ingebouwde ondersteuning hebben.

Polymorfische serialisatie

Newtonsoft.Json voert automatisch polymorfe serialisatie uit. Vanaf .NET 7 ondersteunt System.Text.Json polymorfe serialisatie via het JsonDerivedTypeAttribute kenmerk. Zie Eigenschappen van afgeleide klassen serialiseren voor meer informatie.

Polymorfische deserialisatie

Newtonsoft.Json heeft een TypeNameHandling instelling waarmee metagegevens van het type worden toegevoegd aan de JSON tijdens het serialiseren. Hierbij worden de metagegevens gebruikt tijdens het deserialisatieen van polymorfe deserialisatie. Vanaf .NET 7 System.Text.Json is afhankelijk van typediscriminatiegegevens om polymorfische deserialisatie uit te voeren. Deze metagegevens worden verzonden in de JSON en vervolgens gebruikt tijdens deserialisatie om te bepalen of het basistype of een afgeleid type moet worden gedeserialiseerd. Zie Eigenschappen van afgeleide klassen serialiseren voor meer informatie.

Als u polymorfische deserialisatie in oudere .NET-versies wilt ondersteunen, maakt u een conversieprogramma zoals het voorbeeld in Aangepaste conversieprogramma's schrijven.

Tekenreekswaarden deserialiseren

System.Text.Json ondersteunt standaard niet het deserialiseren van string-waardes voor enumeraties, terwijl Newtonsoft.Json dat wel doet. Met de volgende code wordt bijvoorbeeld een JsonException:

string json = "{ \"Text\": \"Hello\", \"Enum\": \"Two\" }";
var _ = JsonSerializer.Deserialize<MyObj>(json); // Throws exception.

class MyObj
{
    public string Text { get; set; } = "";
    public MyEnum Enum { get; set; }
}

enum MyEnum
{
    One,
    Two,
    Three
}

U kunt echter deserialisatie van tekenreeksenumwaarden inschakelen met behulp van het JsonStringEnumConverter conversieprogramma. Zie Enums als tekenreeksen voor meer informatie.

Deserialisatie van objecteigenschappen

Wanneer Newtonsoft.Json dit wordt gedeserialiseerd, Objectis het:

• Berekent het type primitieve waarden in de JSON-payload (anders dan null) en retourneert het opgeslagen string, long, double, boolean, of DateTime als een boxed object. Primitieve waarden zijn enkele JSON-waarden , zoals een JSON-getal, tekenreeks, true, falseof null.
• Retourneert een JObject of JArray voor complexe waarden in de JSON-nettolading. Complexe waarden zijn verzamelingen van JSON-sleutel-waardeparen binnen accolades ({}) of lijsten met waarden tussen haakjes ([]). De eigenschappen en waarden binnen de accolades of vierkante haken kunnen aanvullende eigenschappen of waarden hebben.
• Retourneert een null-verwijzing wanneer de payload het JSON-literal gebruikt.

System.Text.Json slaat een gebokst JsonElement op voor zowel primitieve als complexe waarden wanneer deserialiseren naar Object, bijvoorbeeld:

• Een object eigenschap.
• Een object woordenlijstwaarde.
• Een object matrixwaarde.
• Een root object.

System.Text.Json behandelt null op dezelfde manier als Newtonsoft.Json en retourneert een null-verwijzing wanneer de payload de JSON-literal null bevat.

Als u typedeductie voor object eigenschappen wilt implementeren, maakt u een conversieprogramma zoals in het voorbeeld in Aangepaste conversieprogramma's schrijven.

Null deserialiseren naar niet-nullbaar type

Newtonsoft.Json genereert geen uitzondering in het volgende scenario:

• NullValueHandling is ingesteld op Ignore, en
• Tijdens de deserialisatie bevat de JSON een null-waarde voor een niet-null-waardetype.

In hetzelfde scenario werpt System.Text.Json een uitzondering op. (De bijbehorende instelling voor null-verwerking is System.Text.JsonJsonSerializerOptions.IgnoreNullValues = true.)

Als u eigenaar bent van het doeltype, is de beste tijdelijke oplossing om de eigenschap in kwestie nullable te maken (bijvoorbeeld wijzigen int in int?).

Een andere tijdelijke oplossing is om een conversieprogramma te maken voor het type, zoals het volgende voorbeeld waarmee null-waarden voor DateTimeOffset typen worden verwerkt:

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

namespace SystemTextJsonSamples
{
    public class DateTimeOffsetNullHandlingConverter : JsonConverter<DateTimeOffset>
    {
        public override DateTimeOffset Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options) =>
            reader.TokenType == JsonTokenType.Null
                ? default
                : reader.GetDateTimeOffset();

        public override void Write(
            Utf8JsonWriter writer,
            DateTimeOffset dateTimeValue,
            JsonSerializerOptions options) =>
            writer.WriteStringValue(dateTimeValue);
    }
}

Registreer dit aangepaste conversieprogramma met behulp van een kenmerk in de eigenschap of door het conversieprogramma toe te voegen aan de Converters verzameling.

Opmerking: het voorgaande conversieprogramma verwerkt null-waarden anders dan Newtonsoft.Json voor POCO's die standaardwaarden opgeven. Stel dat de volgende code uw doelobject vertegenwoordigt:

public class WeatherForecastWithDefault
{
    public WeatherForecastWithDefault()
    {
        Date = DateTimeOffset.Parse("2001-01-01");
        Summary = "No summary";
    }
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}

Stel dat de volgende JSON wordt gedeserialiseerd met behulp van het voorgaande conversieprogramma:

{
  "Date": null,
  "TemperatureCelsius": 25,
  "Summary": null
}

Na deserialisatie heeft de Date eigenschap 1/1/0001 (default(DateTimeOffset)), dat wil zeggen, de waarde die is ingesteld in de constructor, wordt overschreven. Gezien dezelfde POCO en JSON zou Newtonsoft.Json deserialisatie de datum 1/1/2001 in de Date eigenschap achterlaten.

Deserialiseren naar onveranderbare klassen en structs

Newtonsoft.Json kan deserialiseren tot onveranderbare klassen en structs, omdat deze constructors met parameters kan gebruiken.

Gebruik in System.Text.Json de eigenschap [JsonConstructor] om het gebruik van een geparameteriseerde constructor te specificeren. Records in C# 9 zijn ook onveranderbaar en worden ondersteund als deserialisatiedoelen. Zie Onveranderbare typen en records voor meer informatie.

Vereiste eigenschappen

In Newtonsoft.Jsongeeft u op dat een eigenschap vereist is door het kenmerk in te Required stellen[JsonProperty]. Newtonsoft.Json genereert een uitzondering als er geen waarde wordt ontvangen in de JSON voor een eigenschap die als vereist is gemarkeerd.

Vanaf .NET 7 kunt u de C# required -modifier of het JsonRequiredAttribute kenmerk voor een vereiste eigenschap gebruiken. System.Text.Json genereert een uitzondering als de JSON-nettolading geen waarde voor de gemarkeerde eigenschap bevat. Zie Vereiste eigenschappen voor meer informatie.

Datumnotatie opgeven

Newtonsoft.Json biedt verschillende manieren om te bepalen hoe eigenschappen van DateTime en DateTimeOffset typen worden geserialiseerd en gedeserialiseerd:

• De DateTimeZoneHandling instelling kan worden gebruikt om alle DateTime waarden te serialiseren als UTC-datums.
• De DateFormatString instelling en DateTime conversieprogramma's kunnen worden gebruikt om de notatie van datumtekenreeksen aan te passen.

System.Text.Json ondersteunt ISO 8601-1:2019, inclusief het RFC 3339-profiel. Deze indeling wordt algemeen aangenomen, ondubbelzinnig en maakt rondreizen precies. Als u een ander formaat wilt gebruiken, maakt u een aangepaste converter. De volgende conversieprogramma's serialiseren en deserialiseren JSON die een Unix-epoch-indeling gebruikt met of zonder een tijdzoneverschil (waarden zoals /Date(1590863400000-0700)/ of /Date(1590863400000)/):

sealed class UnixEpochDateTimeOffsetConverter : System.Text.Json.Serialization.JsonConverter<DateTimeOffset>
{
    static readonly DateTimeOffset s_epoch = new(1970, 1, 1, 0, 0, 0, TimeSpan.Zero);
    static readonly Regex s_regex = new(
        "^/Date\\(([+-]*\\d+)([+-])(\\d{2})(\\d{2})\\)/$",
        RegexOptions.CultureInvariant);

    public override DateTimeOffset Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
    {
        string formatted = reader.GetString()!;
        Match match = s_regex.Match(formatted);

        if (
                !match.Success
                || !long.TryParse(match.Groups[1].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime)
                || !int.TryParse(match.Groups[3].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int hours)
                || !int.TryParse(match.Groups[4].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int minutes))
        {
            throw new System.Text.Json.JsonException();
        }

        int sign = match.Groups[2].Value[0] == '+' ? 1 : -1;
        TimeSpan utcOffset = new(hours * sign, minutes * sign, 0);

        return s_epoch.AddMilliseconds(unixTime).ToOffset(utcOffset);
    }

    public override void Write(
        Utf8JsonWriter writer,
        DateTimeOffset value,
        JsonSerializerOptions options)
    {
        long unixTime = value.ToUnixTimeMilliseconds();

        TimeSpan utcOffset = value.Offset;

        string formatted = string.Create(
            CultureInfo.InvariantCulture,
            $"/Date({unixTime}{(utcOffset >= TimeSpan.Zero ? "+" : "-")}{utcOffset:hhmm})/");

        writer.WriteStringValue(formatted);
    }
}

sealed class UnixEpochDateTimeConverter : System.Text.Json.Serialization.JsonConverter<DateTime>
{
    static readonly DateTime s_epoch = new(1970, 1, 1, 0, 0, 0);
    static readonly Regex s_regex = new(
        "^/Date\\(([+-]*\\d+)\\)/$",
        RegexOptions.CultureInvariant);

    public override DateTime Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
    {
        string formatted = reader.GetString()!;
        Match match = s_regex.Match(formatted);

        if (
            !match.Success
            || !long.TryParse(match.Groups[1].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime))
        {
            throw new System.Text.Json.JsonException();
        }

        return s_epoch.AddMilliseconds(unixTime);
    }

    public override void Write(
        Utf8JsonWriter writer,
        DateTime value,
        JsonSerializerOptions options)
    {
        long unixTime = (value - s_epoch).Ticks / TimeSpan.TicksPerMillisecond;

        string formatted = string.Create(CultureInfo.InvariantCulture, $"/Date({unixTime})/");
        writer.WriteStringValue(formatted);
    }
}

Zie de ondersteuning voor DateTime en DateTimeOffset in System.Text.Jsonvoor meer informatie.

Terugbelverzoeken

Newtonsoft.Json hiermee kunt u aangepaste code uitvoeren op verschillende punten in het serialisatie- of deserialisatieproces:

• OnDeserialiseren (bij het starten van deserialisatie van een object)
• OnDeserialized (wanneer u klaar bent met het deserialiseren van een object)
• OnSerializeren (bij het begin van het serialiseren van een object)
• OnSerialized (wanneer u klaar bent met het serialiseren van een object)

System.Text.Json geeft dezelfde meldingen weer tijdens serialisatie en deserialisatie. Als u deze wilt gebruiken, implementeert u een of meer van de volgende interfaces uit de System.Text.Json.Serialization naamruimte:

• IJsonOnDeserializing
• IJsonOnDeserialized
• IJsonOnSerializing
• IJsonOnSerialized

Hier volgt een voorbeeld dat controleert op een null-eigenschap en berichten schrijft aan het begin en einde van serialisatie en deserialisatie:

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

namespace Callbacks
{
    public class WeatherForecast : 
        IJsonOnDeserializing, IJsonOnDeserialized, 
        IJsonOnSerializing, IJsonOnSerialized
    {
        public DateTime Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }

        void IJsonOnDeserializing.OnDeserializing() => Console.WriteLine("\nBegin deserializing");
        void IJsonOnDeserialized.OnDeserialized()
        {
            Validate();
            Console.WriteLine("Finished deserializing");
        }
        void IJsonOnSerializing.OnSerializing()
        {
            Console.WriteLine("Begin serializing");
            Validate();
        }
        void IJsonOnSerialized.OnSerialized() => Console.WriteLine("Finished serializing");

        private void Validate()
        {
            if (Summary is null)
            {
                Console.WriteLine("The 'Summary' property is 'null'.");
            }
        }
    }

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

            string jsonString = JsonSerializer.Serialize(weatherForecast);
            Console.WriteLine(jsonString);

            weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString);
            Console.WriteLine($"Date={weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius={weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary={weatherForecast?.Summary}");
        }
    }
}
// output:
//Begin serializing
//The 'Summary' property is 'null'.
//Finished serializing
//{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":null}

//Begin deserializing
//The 'Summary' property is 'null'.
//Finished deserializing
//Date=8/1/2019 12:00:00 AM
//TemperatureCelsius = 25
//Summary=

De OnDeserializing code heeft geen toegang tot het nieuwe POCO-exemplaar. Als u het nieuwe POCO-exemplaar aan het begin van deserialisatie wilt bewerken, plaatst u die code in de POCO-constructor.

Niet-openbare eigenschappensetters en getters

Newtonsoft.Json kan privé en interne propertysetters en -getters gebruiken via het JsonProperty kenmerk.

System.Text.Jsonondersteunt persoonlijke en interne eigenschapssetters en getters via het kenmerk [JsonInclude]. Zie Niet-openbare eigenschapstoegangsors voor voorbeeldcode.

Bestaande objecten vullen

Met de JsonConvert.PopulateObject methode in Newtonsoft.Json deserialisatie wordt een JSON-document gedeserialiseerd naar een bestaand exemplaar van een klasse, in plaats van een nieuw exemplaar te maken. System.Text.Json maakt altijd een nieuw exemplaar van het doeltype met behulp van de standaard openbare parameterloze constructor. Aangepaste conversieprogramma's kunnen deserialiseren naar een bestaand exemplaar.

Eigenschappen opnieuw gebruiken in plaats van eigenschappen te vervangen

Vanaf .NET 8 ondersteunt System.Text.Json het hergebruik van geïnitialiseerde eigenschappen in plaats van ze te vervangen. Er zijn enkele verschillen in gedrag, waarover u kunt lezen in het API-voorstel.

Zie Geïnitialiseerde eigenschappen vullen voor meer informatie.

Eigenschappen zonder setters vullen

Vanaf .NET 8 ondersteunt System.Text.Json het invullen van eigenschappen, inclusief die zonder setter. Zie Geïnitialiseerde eigenschappen vullen voor meer informatie.

Naamgevingsbeleid voor slangencases

System.Text.Json bevat een ingebouwd naamgevingsbeleid voor snake case. Er zijn echter enkele gedragsverschillen met Newtonsoft.Json voor sommige invoer. In de volgende tabel ziet u enkele van deze verschillen bij het converteren van invoer met behulp van het JsonNamingPolicy.SnakeCaseLower beleid.

System.Runtime.Serialization-attributen

System.Runtime.Serialization kenmerken zoals DataContractAttribute, DataMemberAttributeen IgnoreDataMemberAttribute u kunt een gegevenscontract definiëren. Een gegevenscontract is een formele overeenkomst tussen een service en een klant die de gegevens die moeten worden uitgewisseld abstract beschrijft. Het gegevenscontract definieert nauwkeurig welke eigenschappen worden geserialiseerd voor uitwisseling.

System.Text.Json biedt geen ingebouwde ondersteuning voor deze kenmerken. Vanaf .NET 7 kunt u echter een aangepaste type resolver gebruiken om ondersteuning toe te voegen. Zie ZCS voor een voorbeeld. DataContractResolver.

Octale getallen

Newtonsoft.Json behandelt getallen met een voorloopnul als octale getallen. System.Text.Json staat geen voorloopnullen toe omdat de RFC 8259-specificatie ze niet toestaat.

Ontbrekende leden afhandelen

Als de JSON die wordt gedeserialiseerd eigenschappen bevat die ontbreken in het doeltype, Newtonsoft.Json kan worden geconfigureerd om uitzonderingen te genereren. System.Text.Json Standaard worden extra eigenschappen in de JSON genegeerd, behalve wanneer u het kenmerk [JsonExtensionData] gebruikt.

In .NET 8 en latere versies kunt u uw voorkeur instellen voor het overslaan of weigeren van niet-toegewezen JSON-eigenschappen met een van de volgende methoden:

• Pas het JsonUnmappedMemberHandlingAttribute kenmerk toe op het type waarop u deserialiseert.
• Als u uw voorkeur globaal wilt instellen, stelt u de JsonSerializerOptions.UnmappedMemberHandling eigenschap in. Of stel voor het genereren van de bron de JsonSourceGenerationOptionsAttribute.UnmappedMemberHandling eigenschap in en pas het kenmerk toe op uw JsonSerializerContext klasse.
• Pas de JsonTypeInfo.UnmappedMemberHandling eigenschap aan.

JsonObjectAttribute

Newtonsoft.Json heeft een kenmerk, JsonObjectAttributedat kan worden toegepast op het typeniveau om te bepalen welke leden worden geserialiseerd, hoe null waarden worden verwerkt en of alle leden vereist zijn. System.Text.Json heeft geen equivalent kenmerk dat kan worden toegepast op een type. Voor sommige gedragingen, zoals null het verwerken van waarden, kunt u hetzelfde gedrag configureren in het algemene JsonSerializerOptions of afzonderlijk voor elke eigenschap met behulp van JsonIgnoreAttribute.

Bekijk het volgende voorbeeld dat wordt gebruikt Newtonsoft.Json.JsonObjectAttribute om op te geven dat alle null eigenschappen moeten worden genegeerd:

[JsonObject(ItemNullValueHandling = NullValueHandling.Ignore)]
public class Person { ... }

In System.Text.Jsonkunt u het gedrag voor alle typen en eigenschappen instellen:

JsonSerializerOptions options = new()
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

string json = JsonSerializer.Serialize<Person>(person, options);

U kunt ook het gedrag voor elke eigenschap afzonderlijk instellen:

public class Person
{
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public string? Name { get; set; }

    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public int? Age { get; set; }
}

Bekijk vervolgens het volgende voorbeeld dat wordt gebruikt Newtonsoft.Json.JsonObjectAttribute om op te geven dat alle lideigenschappen aanwezig moeten zijn in de JSON:

[JsonObject(ItemRequired = Required.Always)]
public class Person { ... }

U kunt hetzelfde gedrag bereiken System.Text.Json door de C# required -modifier of de JsonRequiredAttributeaan elke eigenschap toe te voegen. Zie Vereiste eigenschappen voor meer informatie.

public class Person
{
    [JsonRequired]
    public string? Name { get; set; }

    public required int? Age { get; set; }
}

Bekijk ten slotte het volgende voorbeeld dat wordt gebruikt Newtonsoft.Json.JsonObjectAttribute om een titel op te geven voor het genereren van JSON-schema's:

[JsonObject(Title = "PersonTitle")]
public class Person { ... }

De Title eigenschap wordt gebruikt voor metagegevens van JSON-schema's en heeft geen direct equivalent in System.Text.Json. Vanaf .NET 9 kunt u JSON-schema's JsonSchemaExporter genereren en de schematitel aanpassen met behulp van de TransformSchemaNode gemachtigde. Zie Het gegenereerde schema transformeren voor een voorbeeld.

TraceWriter

Newtonsoft.Json stelt u in staat om fouten op te sporen door logs te bekijken die worden gegenereerd door serialisatie of deserialisatie met behulp van een TraceWriter. System.Text.Json maakt geen logboekregistratie.

JsonDocument en JsonElement vergeleken met JToken (zoals JObject, JArray)

System.Text.Json.JsonDocument biedt de mogelijkheid om een alleen-lezen Document Object Model (DOM) te parseren en bouwen op basis van bestaande JSON-nettoladingen. De DOM biedt willekeurige toegang tot gegevens in een JSON-nettolading. De JSON-elementen die de nettolading vormen, kunnen worden geopend via het JsonElement type. Het JsonElement type biedt API's voor het converteren van JSON-tekst naar algemene .NET-typen. JsonDocument maakt een RootElement eigenschap beschikbaar.

Vanaf .NET 6 kunt u een veranderlijke DOM parseren en bouwen op basis van bestaande JSON-nettoladingen met behulp van het JsonNode type en andere typen in de System.Text.Json.Nodes naamruimte. Zie Use JsonNodevoor meer informatie.

JsonDocument implementeert IDisposable

JsonDocument bouwt een in-memory weergave van de gegevens in een poolbuffer. Daarom, in tegenstelling tot JObject of JArray van Newtonsoft.Json, het JsonDocument type IDisposable implementeert en moet worden gebruikt binnen een gebruiksblok. Zie JsonDocument is IDisposable voor meer informatie.

JsonDocument heeft het kenmerk Alleen-lezen

De System.Text.Json DOM kan geen JSON-elementen toevoegen, verwijderen of wijzigen. Het is op deze manier ontworpen voor prestaties en om het aantal toewijzingen te verminderen bij het parseren van veelvoorkomende JSON-bestandsgroottes, dat wil zeggen, 1 MB.

JsonElement is een samenvoegstruct

JsonDocument geeft de RootElement eigenschap als een eigenschap van het type JsonElementweer, een samenvoegingsstructtype dat elk JSON-element omvat. Newtonsoft.Json maakt gebruik van toegewezen hiërarchische typen, zoals JObject, JArray, JTokenenzovoort. JsonElement is wat u kunt doorzoeken en opsommen en kunt u gebruiken JsonElement om JSON-elementen te materialiseren in .NET-typen.

Vanaf .NET 6 kunt u het type JsonNode en types in de System.Text.Json.Nodes naamruimte gebruiken die overeenkomen met JObject, JArray en JToken. Zie Use JsonNodevoor meer informatie.

Een JsonDocument en JsonElement doorzoeken op subelementen

Er wordt gezocht naar JSON-tokens met behulp van JObject of JArray vanuit Newtonsoft.Json, wat relatief snel gaat omdat dit opzoekingen in een bepaalde woordenlijst zijn. Ter vergelijking: zoekopdrachten JsonElement vereisen een sequentiële zoekopdracht van de eigenschappen en zijn daarom relatief traag (bijvoorbeeld bij gebruik TryGetProperty). System.Text.Json is ontworpen om de initiële parseringstijd te minimaliseren in plaats van opzoektijd. Zie Een JsonDocument en JsonElement doorzoeken voor subelementen voor meer informatie.

Utf8JsonReader versus JsonTextReader

System.Text.Json.Utf8JsonReader is een high-performance, met weinig toewijzing enkel-lezer voor UTF-8 gecodeerde JSON-tekst, gelezen uit een ReadOnlySpan<byte> of ReadOnlySequence<byte>. Het Utf8JsonReader is een type op laag niveau dat kan worden gebruikt om aangepaste parsers en ontserialisaties te bouwen.

Utf8JsonReader is een ref-struct

De JsonTextReader in Newtonsoft.Json is een klasse. Het Utf8JsonReader type verschilt doordat het een ref struct is. Voor meer informatie, zie beperkingen van ref struct voor Utf8JsonReader.

Null-waarden in nullable waardetypen lezen

Newtonsoft.Json biedt API's die Nullable<T> retourneren, zoals ReadAsBoolean, dat een NullTokenType voor u afhandelt door een bool? te retourneren. De ingebouwde System.Text.Json API's retourneren alleen niet-null-waardetypen. Zie Null-waarden lezen in optionele waarde typen voor meer informatie.

Meerdere doelen voor het lezen van JSON

Als u wilt blijven gebruiken Newtonsoft.Json voor bepaalde doelframeworks, kunt u meerdere doelen hebben en twee implementaties hebben. Dit is echter niet triviaal en zou enige #ifdefs en bronduplicatie vereisen. Een manier om zoveel mogelijk code te delen, is door een ref struct wrapper rond Utf8JsonReader en Newtonsoft.Json.JsonTextReader. Deze wrapper zou het openbare oppervlak samenvoegen terwijl de gedragsverschillen worden geïsoleerd. Hiermee kunt u de wijzigingen voornamelijk isoleren in de constructie van het type, samen met het doorgeven van het nieuwe type via een referentie. Dit is het patroon dat de bibliotheek Microsoft.Extensions.DependencyModel volgt:

• UnifiedJsonReader.JsonTextReader.cs
• UnifiedJsonReader.Utf8JsonReader.cs

Utf8JsonWriter versus JsonTextWriter

System.Text.Json.Utf8JsonWriter is een krachtige manier om UTF-8 gecodeerde JSON-tekst te schrijven van veelgebruikte .NET-typen, zoals String, Int32en DateTime. De schrijver is een type op laag niveau dat kan worden gebruikt voor het bouwen van aangepaste serializers.

Onbewerkte waarden schrijven

Newtonsoft.Json heeft een WriteRawValue methode waarmee onbewerkte JSON wordt geschreven waar een waarde wordt verwacht. System.Text.Json heeft een direct equivalent: Utf8JsonWriter.WriteRawValue. Zie Onbewerkte JSON schrijven voor meer informatie.

JSON-indeling aanpassen

Er zijn geen tijdelijke oplossingen waarmee u de JSON Utf8JsonWriter op deze manieren kunt aanpassen.

Tijdspanne, URI- of tekenwaarden schrijven

JsonTextWriter biedt WriteValue methoden voor tijdspan-, URI- en tekenwaarden . Utf8JsonWriter heeft geen equivalente methoden. Maak deze waarden in plaats daarvan op als tekenreeksen (bijvoorbeeld door aan te roepen ToString()) en aan te roepen WriteStringValue.

Meerdere doelen voor het schrijven van JSON

Als u wilt blijven gebruiken Newtonsoft.Json voor bepaalde doelframeworks, kunt u meerdere doelen hebben en twee implementaties hebben. Dit is echter niet triviaal en zou enige #ifdefs en bronduplicatie vereisen. Een manier om zoveel mogelijk code te delen, is door een wrapper rond Utf8JsonWriter en Newtonsoft.Json.JsonTextWriter. Deze wrapper zou het openbare oppervlak samenvoegen terwijl de gedragsverschillen worden geïsoleerd. Hiermee kunt u de wijzigingen voornamelijk beperken tot de constructie van het type. De bibliotheek Microsoft.Extensions.DependencyModel volgt:

• UnifiedJsonWriter.JsonTextWriter.cs
• UnifiedJsonWriter.Utf8JsonWriter.cs

TypeNameHandling.All wordt niet ondersteund

De beslissing om functionaliteit die equivalent is aan TypeNameHandling.All uit te sluiten van System.Text.Json was opzettelijk. Het toestaan van een JSON-nettolading om zijn eigen typegegevens op te geven, is een veelvoorkomende bron van beveiligingsproblemen in webtoepassingen. Met name door deze Newtonsoft.JsonTypeNameHandling.All configuratie kan de externe client een volledige uitvoerbare toepassing insluiten binnen de JSON-nettolading zelf, zodat tijdens de deserialisatie de webtoepassing wordt geëxtraheerd en de ingesloten code wordt uitgevoerd. Zie voor meer informatie vrijdag de 13e JSON-aanvallen PowerPoint en details van vrijdag de 13e JSON-aanvallen.

JSON-padquery's worden niet ondersteund

De JsonDocument DOM biedt geen ondersteuning voor het uitvoeren van query's met behulp van JSON-pad.

In een JsonNode DOM heeft elk JsonNode exemplaar een GetPath methode die een pad naar dat knooppunt retourneert. Er is echter geen ingebouwde API voor het afhandelen van query's op basis van JSON Path-queryreeksen.

Zie de dotnet/runtime #31068 GitHub-kwestie voor meer informatie.

Sommige limieten kunnen niet worden geconfigureerd

System.Text.Json stelt limieten in die niet kunnen worden gewijzigd voor sommige waarden, zoals de maximale tokengrootte in tekens (166 MB) en in basis 64 (125 MB). Zie JsonConstants voor meer informatie de broncode en GitHub probleem dotnet/runtime #39953.

NaN, Infinity, -Infinity

Newtonsoft parseert NaNtokens en Infinity-Infinity JSON-tekenreeksen. Met System.Text.Json, gebruik JsonNumberHandling.AllowNamedFloatingPointLiterals. Voor informatie over het gebruik van deze instelling, zie Getallen in quotes toestaan of plaatsen.

AI gebruiken voor migratie in de hele oplossing

U kunt AI-hulpprogramma's, zoals GitHub Copilot, gebruiken om u te helpen bij het migreren van Newtonsoft.Json uw oplossingscode naar System.Text.Json.

Hier volgt een voorbeeldprompt die u kunt gebruiken in Visual Studio Copilot Chat om een oplossing te migreren.

Convert all serialization code in this #solution from Newtonsoft.Json to System.Text.Json, using the recommended approach for my current .NET version.
- Update attributes and properties, including rules for skipping or renaming during serialization
- Ensure polymorphic serialization continues to work correctly
- Respect existing custom converters and project-level settings (for example, from the Utilities folder or appsettings.json)
- Update related unit tests and highlight any potential breaking changes
- Generate a migration summary

Bekijk de suggesties van Copilot voordat u ze toepast.

Zie de veelgestelde vragen over GitHub Copilot voor meer informatie over GitHub.

Aanvullende bronnen

• System.Text.Json overzicht
• JSON serialiseren en deserialiseren
• GitHub Copilot in Visual Studio
• GitHub Copilot in VS Code