Serialisieren und Deserialisieren (Mars Hallen und Unmarshalling) von JSON in .NETHow to serialize and deserialize (marshal and unmarshal) JSON in .NET

In diesem Artikel wird gezeigt, wie Sie den System.Text.Json-Namespace zum Serialisieren und Deserialisieren in und aus JavaScript Object Notation (JSON) verwenden.This article shows how to use the System.Text.Json namespace to serialize and deserialize to and from JavaScript Object Notation (JSON).

Die Anleitungen und der Beispielcode verwenden die Bibliothek direkt und nicht über ein Framework, wie z. b. ASP.net Core.The directions and sample code use the library directly, not through a framework such as ASP.NET Core.

Der größte Teil des serialisierungsbeispielcodes legt JsonSerializerOptions.WriteIndented fest, um die JSON-Datei zu true (mit einzügkeit und Leerraum für die Lesbarkeit des Menschen).Most of the serialization sample code sets JsonSerializerOptions.WriteIndented to true to "pretty-print" the JSON (with indentation and whitespace for human readability). Für die Verwendung in der Produktion akzeptieren Sie in der Regel den Standardwert false für diese Einstellung.For production use, you would typically accept the default value of false for this setting.

NamespacesNamespaces

Der System.Text.Json-Namespace enthält alle Einstiegspunkte und die Haupttypen.The System.Text.Json namespace contains all the entry points and the main types. Der System.Text.Json.Serialization-Namespace enthält Attribute und APIs für erweiterte Szenarien und Anpassungen, die für die Serialisierung und Deserialisierung spezifisch sind.The System.Text.Json.Serialization namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. Die in diesem Artikel gezeigten Codebeispiele erfordern using-Direktiven für einen oder beide Namespaces:The code examples shown in this article require using directives for one or both of these namespaces:

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

Attribute aus dem System.Runtime.Serialization-Namespace werden derzeit in System.Text.Jsonnicht unterstützt.Attributes from the System.Runtime.Serialization namespace aren't currently supported in System.Text.Json.

Schreiben von .NET-Objekten in JSON (Serialisieren)How to write .NET objects to JSON (serialize)

Um JSON in eine Zeichenfolge oder eine Datei zu schreiben, müssen Sie die JsonSerializer.Serialize-Methode aufzurufen.To write JSON to a string or to a file, call the JsonSerializer.Serialize method.

Im folgenden Beispiel wird JSON als Zeichenfolge erstellt:The following example creates JSON as a string:

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

Im folgenden Beispiel wird synchroner Code verwendet, um eine JSON-Datei zu erstellen:The following example uses synchronous code to create a JSON file:

jsonString = JsonSerializer.Serialize(weatherForecast);
File.WriteAllText(fileName, jsonString);

Im folgenden Beispiel wird asynchroner Code verwendet, um eine JSON-Datei zu erstellen:The following example uses asynchronous code to create a JSON file:

using (FileStream fs = File.Create(fileName))
{
    await JsonSerializer.SerializeAsync(fs, weatherForecast);
}

In den vorangehenden Beispielen wird der Typrückschluss für den serialisierten Typ verwendet.The preceding examples use type inference for the type being serialized. Eine Überladung von Serialize() nimmt einen generischen Typparameter an:An overload of Serialize() takes a generic type parameter:

jsonString = JsonSerializer.Serialize<WeatherForecastWithPOCOs>(weatherForecast);

Beispiel für die SerialisierungSerialization example

Im Folgenden finden Sie eine Beispiel-Klasse, die Auflistungen und eine geschachtelte Klasse enthält:Here's an example class that contains collections and a nested class:

public class WeatherForecastWithPOCOs
{
    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; }
}

Die JSON-Ausgabe der Serialisierung einer Instanz des vorangehenden Typs sieht wie im folgenden Beispiel aus.The JSON output from serializing an instance of the preceding type looks like the following example. Die JSON-Ausgabe wird standardmäßig minimiert:The JSON output is minified by default:

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

Im folgenden Beispiel wird derselbe JSON-Code dargestellt, der formatiert ist (d. h. mit Leerraum und Einzug):The following example shows the same JSON, formatted (that is, 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"
  ]
}

In UTF-8 serialisierenSerialize to UTF-8

Um zu UTF-8 zu serialisieren, müssen Sie die JsonSerializer.SerializeToUtf8Bytes-Methode aufzurufen:To serialize to UTF-8, call the JsonSerializer.SerializeToUtf8Bytes method:

byte[] jsonUtf8Bytes;
var options = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast, options);

Eine Serialize Überladung, die einen Utf8JsonWriter annimmt, ist ebenfalls verfügbar.A Serialize overload that takes a Utf8JsonWriter is also available.

Die Serialisierung in UTF-8 ist ungefähr 5-10 % schneller als die Verwendung der auf Zeichenfolgen basierten Methoden.Serializing to UTF-8 is about 5-10% faster than using the string-based methods. Der Unterschied liegt darin, dass die Bytes (als UTF-8) nicht in Zeichenfolgen (UTF-16) konvertiert werden müssen.The difference is because the bytes (as UTF-8) don't need to be converted to strings (UTF-16).

SerialisierungsverhaltenSerialization behavior

Folgende Typen werden unterstützt:Supported types include:

  • .Net-primitive, die JavaScript-primitiven zugeordnet sind, z. b. numerische Typen, Zeichen folgen und boolesche Werte..NET primitives that map to JavaScript primitives, such as numeric types, strings, and Boolean.
  • Benutzerdefinierte Plain Old CLR Objects (POCOS).User-defined Plain Old CLR Objects (POCOs).
  • Eindimensionales und verzweigte Arrays (ArrayName[][]).One-dimensional and jagged arrays (ArrayName[][]).
  • Dictionary<string,TValue>, wo TValue object, JsonElementoder poco ist.Dictionary<string,TValue> where TValue is object, JsonElement, or a POCO.
  • Sammlungen aus den folgenden Namespaces.Collections from the following namespaces.

Sie können benutzerdefinierte Konverter implementieren , um zusätzliche Typen zu verarbeiten oder Funktionen bereitzustellen, die von den integrierten Konvertern nicht unterstützt werden.You can implement custom converters to handle additional types or to provide functionality that isn't supported by the built-in converters.

Lesen von JSON in .NET-Objekte (Deserialisieren)How to read JSON into .NET objects (deserialize)

Um eine Zeichenfolge oder eine Datei zu deserialisieren, müssen Sie die JsonSerializer.Deserialize-Methode aufzurufen.To deserialize from a string or a file, call the JsonSerializer.Deserialize method.

Im folgenden Beispiel wird JSON aus einer Zeichenfolge gelesen und eine Instanz der WeatherForecast-Klasse erstellt, die zuvor für das serialisierungsbeispielgezeigt wurde:The following example reads JSON from a string and creates an instance of the WeatherForecast class shown earlier for the serialization example:

weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithPOCOs>(jsonString);

Wenn Sie aus einer Datei mithilfe von synchronem Code deserialisieren möchten, lesen Sie die Datei in eine Zeichenfolge, wie im folgenden Beispiel gezeigt:To deserialize from a file by using synchronous code, read the file into a string, as shown in the following example:

jsonString = File.ReadAllText(fileName);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString);

Um mithilfe von asynchronem Code aus einer Datei zu deserialisieren, müssen Sie die DeserializeAsync-Methode abrufen:To deserialize from a file by using asynchronous code, call the DeserializeAsync method:

using (FileStream fs = File.OpenRead(fileName))
{
    weatherForecast = await JsonSerializer.DeserializeAsync<WeatherForecast>(fs);
}

Aus UTF-8 deserialisierenDeserialize from UTF-8

Um von UTF-8 zu deserialisieren, müssen Sie eine JsonSerializer.Deserialize Überladung aufrufen, die eine Utf8JsonReader oder eine ReadOnlySpan<byte>annimmt, wie in den folgenden Beispielen gezeigt.To deserialize from UTF-8, call a JsonSerializer.Deserialize overload that takes a Utf8JsonReader or a ReadOnlySpan<byte>, as shown in the following examples. In den Beispielen wird davon ausgegangen, dass sich JSON in einem Bytearray namens jsonUtf8Bytes befindet.The examples assume the JSON is in a byte array named jsonUtf8Bytes.

var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan);
var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader);

DeserialisierungsverhaltenDeserialization behavior

  • Standardmäßig wird die Groß-/Kleinschreibung bei der Übereinstimmung von Eigenschaften NamenBy default, property name matching is case-sensitive. Sie können die Groß-/Kleinschreibungnicht beachten.You can specify case-insensitivity.
  • Wenn der JSON-Wert einen Wert für eine schreibgeschützte Eigenschaft enthält, wird der Wert ignoriert, und es wird keine Ausnahme ausgelöst.If the JSON contains a value for a read-only property, the value is ignored and no exception is thrown.
  • Die Deserialisierung für Verweis Typen ohne Parameter losen Konstruktor wird nicht unterstützt.Deserialization to reference types without a parameterless constructor isn't supported.
  • Die Deserialisierung zu unveränderlichen Objekten oder schreibgeschützten Eigenschaften wird nicht unterstützt.Deserialization to immutable objects or read-only properties isn't supported.
  • Standardmäßig werden Enumerationen als Zahlen unterstützt.By default, enums are supported as numbers. Enumerationsnamen können als Zeichen folgen serialisiertwerden.You can serialize enum names as strings.
  • Felder werden nicht unterstützt.Fields aren't supported.
  • Standardmäßig lösen Kommentare oder nachfolgende Kommas in der JSON-Datei Ausnahmen aus.By default, comments or trailing commas in the JSON throw exceptions. Sie können Kommentare und nachfolgende Kommas zulassen.You can allow comments and trailing commas.
  • Der Standardwert für die Maximale Tiefe ist 64.The default maximum depth is 64.

Sie können benutzerdefinierte Konverter implementieren , um Funktionen bereitzustellen, die von den integrierten Konvertern nicht unterstützt werden.You can implement custom converters to provide functionality that isn't supported by the built-in converters.

Serialisieren in formatierten JSON-CodeSerialize to formatted JSON

Um die JSON-Ausgabe zu Recht drucken, legen Sie JsonSerializerOptions.WriteIndented auf truefest:To pretty-print the JSON output, set JsonSerializerOptions.WriteIndented to true:

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

Im Folgenden finden Sie eine Beispielklasse, die serialisiert werden soll, und die formatierte JSON-Ausgabe:Here's an example type to be serialized and pretty-printed JSON output:

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Anpassen von JSON-Namen und -WertenCustomize JSON names and values

Standardmäßig sind Eigenschaftsnamen und Wörterbuchschlüssel in der JSON-Ausgabe unverändert, einschließlich der Groß-/Kleinschreibung.By default, property names and dictionary keys are unchanged in the JSON output, including case. Enumerationswerte werden als Zahlen dargestellt.Enum values are represented as numbers. In diesem Abschnitt wird Folgendes beschrieben:This section explains how to:

Für andere Szenarien, die eine besondere Behandlung von JSON-Eigenschaftsnamen und-Werten erfordern, können Sie benutzerdefinierte Konverter implementieren.For other scenarios that require special handling of JSON property names and values, you can implement custom converters.

Anpassen einzelner EigenschaftsnamenCustomize individual property names

Um den Namen einzelner Eigenschaften festzulegen, verwenden Sie das [jsonpropertyname] -Attribut.To set the name of individual properties, use the [JsonPropertyName] attribute.

Hier ist ein Beispiel für die Serialisierung und die daraus resultierende JSON-Datei:Here's an example type to serialize and resulting JSON:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "Wind": 35
}

Der durch dieses Attribut festgelegte Eigenschaftsname:The property name set by this attribute:

  • Gilt in beide Richtungen, für die Serialisierung und DeserialisierungApplies in both directions, for serialization and deserialization.
  • Hat Vorrang vor Benennungsrichtlinien für EigenschaftenTakes precedence over property naming policies.

Camel-Case für alle JSON-Eigenschaftsnamen verwendenUse camel case for all JSON property names

Wenn Sie die Kamel-Schreibweise für alle JSON-Eigenschaftsnamen verwenden möchten, legen Sie JsonSerializerOptions.PropertyNamingPolicy auf JsonNamingPolicy.CamelCasefest, wie im folgenden Beispiel gezeigt:To use camel case for all JSON property names, set JsonSerializerOptions.PropertyNamingPolicy to JsonNamingPolicy.CamelCase, as shown in the following example:

var serializeOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);

Im Folgenden finden Sie eine Beispielklasse zum Serialisieren und die JSON-Ausgabe:Here's an example class to serialize and JSON output:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
  "Wind": 35
}

Die Camel-Case-Benennungsrichtlinie für Eigenschaften:The camel case property naming policy:

  • Gilt für die Serialisierung und Deserialisierung.Applies to serialization and deserialization.
  • Wird von [JsonPropertyName] Attributen überschrieben.Is overridden by [JsonPropertyName] attributes. Aus diesem Grund ist der Name der JSON-Eigenschaft Wind im Beispiel nicht Camel Case.This is why the JSON property name Wind in the example is not camel case.

Verwenden einer benutzerdefinierten Benennungsrichtlinie für JSON-EigenschaftenUse a custom JSON property naming policy

Um eine benutzerdefinierte JSON-Benennungs Richtlinie zu verwenden, erstellen Sie eine Klasse, die von JsonNamingPolicy abgeleitet ist, und überschreiben Sie die ConvertName-Methode, wie im folgenden Beispiel gezeigt:To use a custom JSON property naming policy, create a class that derives from JsonNamingPolicy and override the ConvertName method, as shown in the following example:

using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class UpperCaseNamingPolicy : JsonNamingPolicy
    {
        public override string ConvertName(string name) =>
            name.ToUpper();
    }
}

Legen Sie dann die JsonSerializerOptions.PropertyNamingPolicy-Eigenschaft auf eine Instanz Ihrer Benennungs Richtlinien Klasse fest:Then set the JsonSerializerOptions.PropertyNamingPolicy property to an instance of your naming policy class:

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

Im Folgenden finden Sie eine Beispielklasse zum Serialisieren und die JSON-Ausgabe:Here's an example class to serialize and JSON output:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "DATE": "2019-08-01T00:00:00-07:00",
  "TEMPERATURECELSIUS": 25,
  "SUMMARY": "Hot",
  "Wind": 35
}

Die Benennungsrichtlinie für JSON-Eigenschaften:The JSON property naming policy:

  • Gilt für die Serialisierung und Deserialisierung.Applies to serialization and deserialization.
  • Wird von [JsonPropertyName] Attributen überschrieben.Is overridden by [JsonPropertyName] attributes. Aus diesem Grund ist der JSON-Eigenschaftsname Wind im Beispiel nicht Großbuchstaben.This is why the JSON property name Wind in the example is not upper case.

Camel-Case WörterbuchschlüsselCamel case dictionary keys

Wenn eine Eigenschaft eines zu serialisierenden Objekts vom Typ Dictionary<string,TValue>ist, können die string Schlüssel in die Kamel-Schreibweise konvertiert werden.If a property of an object to be serialized is of type Dictionary<string,TValue>, the string keys can be converted to camel case. Legen Sie zu diesem Zweck DictionaryKeyPolicy auf JsonNamingPolicy.CamelCasefest, wie im folgenden Beispiel gezeigt:To do that, set DictionaryKeyPolicy to JsonNamingPolicy.CamelCase, as shown in the following example:

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

Das Serialisieren eines Objekts mit einem Wörterbuch mit dem Namen TemperatureRanges, das Schlüssel-Wert-Paare "ColdMinTemp", 20 und "HotMinTemp", 40 hat, führt zu einer JSON-Ausgabe wie im folgenden Beispiel:Serializing an object with a dictionary named TemperatureRanges that has key-value pairs "ColdMinTemp", 20 and "HotMinTemp", 40 would result in JSON output like the following example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "TemperatureRanges": {
    "coldMinTemp": 20,
    "hotMinTemp": 40
  }
}

Die Camel-Case-Benennungsrichtlinie für Wörterbuchschlüssel gilt nur für die Serialisierung.The camel case naming policy for dictionary keys applies to serialization only. Wenn Sie ein Wörterbuch deserialisieren, entsprechen die Schlüssel der JSON-Datei, auch wenn Sie JsonNamingPolicy.CamelCase für die DictionaryKeyPolicyangeben.If you deserialize a dictionary, the keys will match the JSON file even if you specify JsonNamingPolicy.CamelCase for the DictionaryKeyPolicy.

Enumerationen als ZeichenfolgenEnums as strings

Standardmäßig werden Enumerationen als Zahlen serialisiert.By default, enums are serialized as numbers. Verwenden Sie die JsonStringEnumConverter, um Enumerationsnamen als Zeichen folgen zu serialisieren.To serialize enum names as strings, use the JsonStringEnumConverter.

Nehmen Sie beispielsweise an, Sie müssen die folgende Klasse serialisieren, die über eine Enumeration verfügt:For example, suppose you need to serialize the following class that has an enum:

public class WeatherForecastWithEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Summary Summary { get; set; }
}

public enum Summary
{
    Cold, Cool, Warm, Hot
}

Wenn die Zusammenfassung Hotist, hat die serialisierte JSON standardmäßig den numerischen Wert 3:If the Summary is Hot, by default the serialized JSON has the numeric value 3:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": 3
}

Der folgende Beispielcode serialisiert die Enumerationsnamen anstelle der numerischen Werte und konvertiert die Namen in die Camel-Case-Schreibweise:The following sample code serializes the enum names instead of the numeric values, and converts the names to camel case:

options = new JsonSerializerOptions();
options.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));
options.WriteIndented = true;
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Der resultierende JSON-Code sieht wie im folgenden Beispiel aus:The resulting JSON looks like the following example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "hot"
}

Enumerationsnamen-Zeichenfolgen können ebenfalls deserialisiert werden, wie im folgenden Beispiel gezeigt:Enum string names can be deserialized as well, as shown in the following example:

options = new JsonSerializerOptions();
options.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithEnum>(jsonString, options);

Eigenschaften von der Serialisierung ausschließenExclude properties from serialization

Standardmäßig werden alle öffentlichen Eigenschaften serialisiert.By default, all public properties are serialized. Wenn Sie möchten, dass einige von ihnen nicht in der JSON-Ausgabe angezeigt werden, haben Sie mehrere Möglichkeiten.If you don't want some of them to appear in the JSON output, you have several options. In diesem Abschnitt wird erläutert, wie verschiedene Dinge ausgeschlossen werden können:This section explains how to exclude:

Einzelne Eigenschaften ausschließenExclude individual properties

Verwenden Sie das Attribut [jsonignore] , um einzelne Eigenschaften zu ignorieren.To ignore individual properties, use the [JsonIgnore] attribute.

Hier ist ein Beispiel für die Serialisierung und JSON-Ausgabe:Here's an example type to serialize and JSON output:

public class WeatherForecastWithIgnoreAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    [JsonIgnore]
    public string Summary { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
}

Alle schreibgeschützten Eigenschaften ausschließenExclude all read-only properties

Eine Eigenschaft ist schreibgeschützt, wenn Sie einen öffentlichen Getter, aber keinen öffentlichen Setter enthält.A property is read-only if it contains a public getter but not a public setter. Um alle schreibgeschützten Eigenschaften auszuschließen, legen Sie den JsonSerializerOptions.IgnoreReadOnlyProperties auf truefest, wie im folgenden Beispiel gezeigt:To exclude all read-only properties, set the JsonSerializerOptions.IgnoreReadOnlyProperties to true, as shown in the following example:

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

Hier ist ein Beispiel für die Serialisierung und JSON-Ausgabe:Here's an example type to serialize and JSON output:

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

Diese Option gilt nur für die Serialisierung.This option applies only to serialization. Während der Deserialisierung werden schreibgeschützte Eigenschaften standardmäßig ignoriert.During deserialization, read-only properties are ignored by default.

Alle Eigenschaften mit NULL-Wert ausschließenExclude all null value properties

Um alle NULL-Wert Eigenschaften auszuschließen, legen Sie die IgnoreNullValues-Eigenschaft auf truefest, wie im folgenden Beispiel gezeigt:To exclude all null value properties, set the IgnoreNullValues property to true, as shown in the following example:

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

Im folgenden finden Sie ein Beispiel Objekt für die Serialisierung und JSON-Ausgabe:Here's an example object to serialize and JSON output:

EigenschaftProperty WertValue
DatumDate 01.08.2019 00:00:00 -07:008/1/2019 12:00:00 AM -07:00
TemperatureCelsiusTemperatureCelsius 2525
ZusammenfassungSummary nullnull
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25
}

Diese Einstellung gilt für die Serialisierung und Deserialisierung.This setting applies to serialization and deserialization. Informationen zu den Auswirkungen auf die Deserialisierung finden Sie unter Ignorieren von NULL beim Deserialisieren.For information about its effect on deserialization, see Ignore null when deserializing.

Zeichencodierung anpassenCustomize character encoding

Standardmäßig schützt der Serialisierer alle Nicht-ASCII-Zeichen.By default, the serializer escapes all non-ASCII characters. Das heißt, Sie ersetzt Sie durch \uxxxx, wobei xxxx der Unicode-Code des Zeichens ist.That is, it replaces them with \uxxxx where xxxx is the Unicode code of the character. Wenn die Summary-Eigenschaft z. b. auf Cyrillic-"-Eigenschaft" festgelegt ist, wird das WeatherForecast Objekt wie in diesem Beispiel gezeigt serialisiert:For example, if the Summary property is set to Cyrillic жарко, the WeatherForecast object is serialized as shown in this example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "\u0436\u0430\u0440\u043A\u043E"
}

Serialisieren von SprachzeichensätzenSerialize language character sets

Wenn Sie die Zeichensätze mindestens einer Sprache ohne Escapezeichen serialisieren möchten, müssen Sie beim Erstellen einer Instanz von System.Text.Encodings.Web.JavaScriptEncoderUnicode-Bereiche angeben, wie im folgenden Beispiel gezeigt:To serialize the character set(s) of one or more languages without escaping, specify Unicode range(s) when creating an instance of System.Text.Encodings.Web.JavaScriptEncoder, as shown in the following example:

using System;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;
options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.Create(UnicodeRanges.BasicLatin, UnicodeRanges.Cyrillic),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Mit diesem Code werden kyrillische und griechische Zeichen nicht geschützt.This code doesn't escape Cyrillic or Greek characters. Wenn die Summary-Eigenschaft auf Cyrillic--,-festgelegt ist, wird das WeatherForecast-Objekt wie in diesem Beispiel gezeigt serialisiert:If the Summary property is set to Cyrillic жарко, the WeatherForecast object is serialized as shown in this example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "жарко"
}

Verwenden Sie UnicodeRanges.All, um alle sprach Sätze ohne Escapezeichen zu serialisieren.To serialize all language sets without escaping, use UnicodeRanges.All.

Serialisieren bestimmter ZeichenSerialize specific characters

Alternativ können Sie einzelne Zeichen angeben, die Sie zulassen möchten, ohne dass sie geschützt werden.An alternative is to specify individual characters that you want to allow through without being escaped. Im folgenden Beispiel werden nur die ersten zwei Zeichen von "жарко" serialisiert:The following example serializes only the first two characters of жарко:

using System;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;
var encoderSettings = new TextEncoderSettings();
encoderSettings.AllowCharacters('\u0436', '\u0430');
encoderSettings.AllowRange(UnicodeRanges.BasicLatin);
options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.Create(encoderSettings),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Im Folgenden finden Sie ein Beispiel für die JSON-Ausgabe, die durch den vorangehenden Code generiert wird:Here's an example of JSON produced by the preceding code:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "жа\u0440\u043A\u043E"
}

Alle Zeichen serialisierenSerialize all characters

Um das Escapezeichen zu minimieren, können Sie JavaScriptEncoder.UnsafeRelaxedJsonEscapingverwenden, wie im folgenden Beispiel gezeigt:To minimize escaping you can use JavaScriptEncoder.UnsafeRelaxedJsonEscaping, as shown in the following example:

using System;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;
options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Achtung

Im Vergleich zum Standard-Encoder ist der UnsafeRelaxedJsonEscaping Encoder eher für das Zulassen von Zeichen ohne Escapezeichen zulässig:Compared to the default encoder, the UnsafeRelaxedJsonEscaping encoder is more permissive about allowing characters to pass through unescaped:

  • Es werden keine HTML-sensiblen Zeichen wie <, >, &und 'mit Escapezeichen versehen.It doesn't escape HTML-sensitive characters such as <, >, &, and '.
  • Er bietet keine zusätzlichen Schutzmaßnahmen vor XSS-oder Informations Offenlegungs Angriffen, wie z. b. solche, die sich aus dem Client und dem Server ergeben könnten, die auf dem CharSetnicht einverstanden sind.It doesn't offer any additional defense-in-depth protections against XSS or information disclosure attacks, such as those which might result from the client and server disagreeing on the charset.

Verwenden Sie den unsicheren Encoder nur dann, wenn bekannt ist, dass der Client die resultierende Nutzlast als UTF-8-codiertes JSON-Format interpretiert.Use the unsafe encoder only when it's known that the client will be interpreting the resulting payload as UTF-8 encoded JSON. Sie können Sie beispielsweise verwenden, wenn der Server den Antwortheader Content-Type: application/json; charset=utf-8sendet.For example, you can use it if the server is sending the response header Content-Type: application/json; charset=utf-8. Gestatten Sie niemals, dass die RohUnsafeRelaxedJsonEscaping Ausgabe in eine HTML-Seite oder ein <script> Element ausgegeben wird.Never allow the raw UnsafeRelaxedJsonEscaping output to be emitted into an HTML page or a <script> element.

Serialisieren von Eigenschaften abgeleiteter KlassenSerialize properties of derived classes

Die Serialisierung einer polymorphen Typhierarchie wird nicht unterstützt.Serialization of a polymorphic type hierarchy is not supported. Wenn eine Eigenschaft beispielsweise als eine Schnittstelle oder eine abstrakte Klasse definiert ist, werden nur die Eigenschaften, die für die Schnittstelle oder die abstrakte Klasse definiert sind, serialisiert, auch wenn der Lauf Zeittyp über zusätzliche Eigenschaften verfügt.For example, if a property is defined as an interface or an abstract class, only the properties defined on the interface or abstract class are serialized, even if the runtime type has additional properties. Die Ausnahmen für dieses Verhalten werden in diesem Abschnitt erläutert.The exceptions to this behavior are explained in this section.

Nehmen Sie beispielsweise an, Sie verfügen über eine WeatherForecast-Klasse und eine abgeleitete Klasse WeatherForecastDerived:For example, suppose you have a WeatherForecast class and a derived class WeatherForecastDerived:

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}
public class WeatherForecastDerived : WeatherForecast
{
    public int WindSpeed { get; set; }
}

Angenommen, das Typargument der Serialize Methode zum Zeitpunkt der Kompilierung ist WeatherForecast:And suppose the type argument of the Serialize method at compile time is WeatherForecast:

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

In diesem Szenario wird die WindSpeed-Eigenschaft nicht serialisiert, auch wenn das weatherForecast-Objekt tatsächlich ein WeatherForecastDerived-Objekt ist.In this scenario, the WindSpeed property is not serialized even if the weatherForecast object is actually a WeatherForecastDerived object. Es werden nur die Eigenschaften der Basisklasse serialisiert:Only the base class properties are serialized:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Dieses Verhalten soll dabei helfen, das versehentliche Verfügbarmachen von Daten in einem abgeleiteten, von der Laufzeit erstellten Typ zu verhindern.This behavior is intended to help prevent accidental exposure of data in a derived runtime-created type.

Verwenden Sie einen der folgenden Ansätze, um die Eigenschaften des abgeleiteten Typs im vorherigen Beispiel zu serialisieren:To serialize the properties of the derived type in the preceding example, use one of the following approaches:

  • Aufrufen einer Überladung von Serialize, mit der Sie den Typ zur Laufzeit angeben können:Call an overload of Serialize that lets you specify the type at runtime:

    options = new JsonSerializerOptions
    {
        WriteIndented = true
    };
    jsonString = JsonSerializer.Serialize(weatherForecast, weatherForecast.GetType(), options);
    
  • Deklarieren Sie das Objekt, das als objectserialisiert werden soll.Declare the object to be serialized as object.

    options = new JsonSerializerOptions
    {
        WriteIndented = true
    };
    jsonString = JsonSerializer.Serialize<object>(weatherForecast, options);
    

Im vorherigen Beispielszenario bewirken beide Ansätze, dass die WindSpeed-Eigenschaft in der JSON-Ausgabe enthalten ist:In the preceding example scenario, both approaches cause the WindSpeed property to be included in the JSON output:

{
  "WindSpeed": 35,
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Wichtig

Diese Ansätze bieten polymorphe Serialisierung nur für das Stamm Objekt, das serialisiert werden soll, und nicht für die Eigenschaften dieses Stamm Objekts.These approaches provide polymorphic serialization only for the root object to be serialized, not for properties of that root object.

Sie können die polymorphe Serialisierung für Objekte auf niedrigerer Ebene erhalten, wenn Sie Sie als Typ objectdefinieren.You can get polymorphic serialization for lower-level objects if you define them as type object. Angenommen, die WeatherForecast-Klasse verfügt über eine Eigenschaft mit dem Namen PreviousForecast, die als Typ WeatherForecast oder objectdefiniert werden kann:For example, suppose your WeatherForecast class has a property named PreviousForecast that can be defined as type WeatherForecast or object:

public class WeatherForecastWithPrevious
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public WeatherForecast PreviousForecast { get; set; }
}
public class WeatherForecastWithPreviousAsObject
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public object PreviousForecast { get; set; }
}

Wenn die PreviousForecast-Eigenschaft eine Instanz von WeatherForecastDerivedenthält:If the PreviousForecast property contains an instance of WeatherForecastDerived:

  • Die JSON-Ausgabe der Serialisierung WeatherForecastWithPrevious enthält keine WindSpeed.The JSON output from serializing WeatherForecastWithPrevious doesn't include WindSpeed.
  • Die JSON-Ausgabe der Serialisierung WeatherForecastWithPreviousAsObject enthält WindSpeed.The JSON output from serializing WeatherForecastWithPreviousAsObject includes WindSpeed.

Um WeatherForecastWithPreviousAsObjectzu serialisieren, ist es nicht erforderlich, Serialize<object> oder GetType aufzurufen, da das Stamm Objekt nicht das Objekt ist, das möglicherweise ein abgeleiteter Typ ist.To serialize WeatherForecastWithPreviousAsObject, it isn't necessary to call Serialize<object> or GetType because the root object isn't the one that may be of a derived type. Im folgenden Codebeispiel wird weder Serialize<object> noch GetTypeaufgerufen:The following code example doesn't call Serialize<object> or GetType:

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

Der vorangehende Code serialisiert WeatherForecastWithPreviousAsObjectordnungsgemäß:The preceding code correctly serializes WeatherForecastWithPreviousAsObject:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "PreviousForecast": {
    "WindSpeed": 35,
    "Date": "2019-08-01T00:00:00-07:00",
    "TemperatureCelsius": 25,
    "Summary": "Hot"
  }
}

Der gleiche Ansatz zum Definieren von Eigenschaften als object funktioniert mit Schnittstellen.The same approach of defining properties as object works with interfaces. Angenommen, Sie haben die folgende Schnittstelle und Implementierung, und Sie möchten eine Klasse mit Eigenschaften serialisieren, die Implementierungs Instanzen enthalten:Suppose you have the following interface and implementation, and you want to serialize a class with properties that contain implementation instances:

using System;

namespace SystemTextJsonSamples
{
    public interface IForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string Summary { get; set; }
    }

    public class Forecast : IForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string Summary { get; set; }
        public int WindSpeed { get; set; }
    }

    public class Forecasts
    {
        public IForecast Monday { get; set; }
        public object Tuesday { get; set; }
    }
}

Wenn Sie eine Instanz von Forecastsserialisieren, zeigt nur Tuesday die WindSpeed-Eigenschaft an, da Tuesday als objectdefiniert ist:When you serialize an instance of Forecasts, only Tuesday shows the WindSpeed property, because Tuesday is defined as object:

var forecasts = new Forecasts
{
    Monday = new Forecast
    {
        Date = DateTime.Parse("2020-01-06"),
        TemperatureCelsius = 10,
        Summary = "Cool",
        WindSpeed = 8
    },
    Tuesday = new Forecast
    {
        Date = DateTime.Parse("2020-01-07"),
        TemperatureCelsius = 11,
        Summary = "Rainy",
        WindSpeed = 10
    }
};

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

Das folgende Beispiel zeigt die JSON-Datei, die sich aus dem vorangehenden Code ergibt:The following example shows the JSON that results from the preceding code:

{
  "Monday": {
    "Date": "2020-01-06T00:00:00-08:00",
    "TemperatureCelsius": 10,
    "Summary": "Cool"
  },
  "Tuesday": {
    "Date": "2020-01-07T00:00:00-08:00",
    "TemperatureCelsius": 11,
    "Summary": "Rainy",
    "WindSpeed": 10
  }
}

Weitere Informationen zur polymorphen Serialisierungund Informationen zur Deserialisierungfinden Sie unter Migrieren von "newtonsoft. JSON" zu "System. Text. JSON".For more information about polymorphic serialization, and for information about deserialization, see How to migrate from Newtonsoft.Json to System.Text.Json.

Kommentare und nachfolgende Kommas zulassenAllow comments and trailing commas

Standardmäßig sind Kommentare und nachfolgende Kommas in JSON nicht zulässig.By default, comments and trailing commas are not allowed in JSON. Um Kommentare im JSON-Code zuzulassen, legen Sie die JsonSerializerOptions.ReadCommentHandling-Eigenschaft auf JsonCommentHandling.Skipfest.To allow comments in the JSON, set the JsonSerializerOptions.ReadCommentHandling property to JsonCommentHandling.Skip. Um nachfolgende Kommas zuzulassen, legen Sie die JsonSerializerOptions.AllowTrailingCommas-Eigenschaft auf truefest.And to allow trailing commas, set the JsonSerializerOptions.AllowTrailingCommas property to true. Im folgenden Beispiel wird gezeigt, wie Sie beides zulassen:The following example shows how to allow both:

var options = new JsonSerializerOptions
{
    ReadCommentHandling = JsonCommentHandling.Skip,
    AllowTrailingCommas = true,
};
var weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString, options);

Im Folgenden finden Sie ein Beispiel für JSON mit Kommentaren und einem nachfolgenden Komma:Here's example JSON with comments and a trailing comma:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25, // Fahrenheit 77
  "Summary": "Hot", /* Zharko */
}

Groß-/Kleinschreibung bei Eigenschaftsnamen ignorierenCase-insensitive property matching

Standardmäßig wird bei der Deserialisierung darauf geachtet, dass die Groß-/Kleinschreibung der Eigenschaftsnamen zwischen JSON und dem Zielobjekt übereinstimmt.By default, deserialization looks for case-sensitive property name matches between JSON and the target object properties. Um dieses Verhalten zu ändern, legen Sie JsonSerializerOptions.PropertyNameCaseInsensitive auf truefest:To change that behavior, set JsonSerializerOptions.PropertyNameCaseInsensitive to true:

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
};
var weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString, options);

Im Folgenden finden Sie eine Beispiel-JSON-Datei mit Camel-Case Namen.Here's example JSON with camel case property names. Sie kann in den folgenden Typ deserialisiert werden, der über Pascal-Case-Eigenschaftsnamen verfügt.It can be deserialized into the following type that has Pascal case property names.

{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
}
public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}

Behandeln von JSON-ÜberlaufHandle overflow JSON

Während der Deserialisierung erhalten Sie möglicherweise Daten im JSON-Code, der nicht durch Eigenschaften des Zieltyps dargestellt wird.While deserializing, you might receive data in the JSON that is not represented by properties of the target type. Angenommen, Ihr Zieltyp lautet:For example, suppose your target type is this:

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

Der JSON-Code, der deserialisiert werden soll, lautet wie folgt:And the JSON to be deserialized is this:

{
  "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"
  ],
  "SummaryWords": [
    "Cool",
    "Windy",
    "Humid"
  ]
}

Wenn Sie den JSON-Code deserialisieren, der in den angezeigten Typ angezeigt wird, sind die Eigenschaften DatesAvailable und SummaryWords nicht mehr vorhanden und gehen verloren.If you deserialize the JSON shown into the type shown, the DatesAvailable and SummaryWords properties have nowhere to go and are lost. Um zusätzliche Daten wie diese Eigenschaften zu erfassen, wenden Sie das jsonextensiondata -Attribut auf eine Eigenschaft vom Typ Dictionary<string,object> oder Dictionary<string,JsonElement>an:To capture extra data such as these properties, apply the JsonExtensionData attribute to a property of type Dictionary<string,object> or Dictionary<string,JsonElement>:

public class WeatherForecastWithExtensionData
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonExtensionData]
    public Dictionary<string, object> ExtensionData { get; set; }
}

Wenn Sie den zuvor gezeigten JSON-Code in diesen Beispieltyp deserialisieren, werden die zusätzlichen Daten zu Schlüssel-Wert-Paaren der ExtensionData-Eigenschaft:When you deserialize the JSON shown earlier into this sample type, the extra data becomes key-value pairs of the ExtensionData property:

EigenschaftProperty WertValue HinweiseNotes
DatumDate 01.08.2019 00:00:00 -07:008/1/2019 12:00:00 AM -07:00
TemperatureCelsiusTemperatureCelsius 00 Unterscheidung nach Groß-/Kleinschreibung (temperatureCelsius im JSON-Code), sodass die-Eigenschaft nicht festgelegt ist.Case-sensitive mismatch (temperatureCelsius in the JSON), so the property isn't set.
ZusammenfassungSummary Hohe AuslastungHot
ExtensionDataExtensionData TemperatureCelsius: 25temperatureCelsius: 25 Da die Groß-/Kleinschreibung nicht entsprach, ist diese JSON-Eigenschaft ein zusätzliches und wird zu einem Schlüssel-Wert-Paar im Wörterbuch.Since the case didn't match, this JSON property is an extra and becomes a key-value pair in the dictionary.
Datesavailable:DatesAvailable:
01.08.2019 00:00:00 -07:008/1/2019 12:00:00 AM -07:00
8/2/2019 12:00:00 Uhr-07:008/2/2019 12:00:00 AM -07:00
Die zusätzliche Eigenschaft aus dem JSON-Code wird zu einem Schlüssel-Wert-Paar, wobei ein Array als Wertobjekt fungiert.Extra property from the JSON becomes a key-value pair, with an array as the value object.
Summarywords:SummaryWords:
TollCool
WindyWindy
FeuHumid
Die zusätzliche Eigenschaft aus dem JSON-Code wird zu einem Schlüssel-Wert-Paar, wobei ein Array als Wertobjekt fungiert.Extra property from the JSON becomes a key-value pair, with an array as the value object.

Wenn das Zielobjekt serialisiert wird, werden die Schlüssel-Wert-Paare der Erweiterungsdaten zu JSON-Eigenschaften, genauso wie sie im eingelesenen JSON-Code waren:When the target object is serialized, the extension data key value pairs become JSON properties just as they were in the incoming JSON:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 0,
  "Summary": "Hot",
  "temperatureCelsius": 25,
  "DatesAvailable": [
    "2019-08-01T00:00:00-07:00",
    "2019-08-02T00:00:00-07:00"
  ],
  "SummaryWords": [
    "Cool",
    "Windy",
    "Humid"
  ]
}

Beachten Sie, dass der ExtensionData-Eigenschaftsname nicht im JSON-Code angezeigt wird.Notice that the ExtensionData property name doesn't appear in the JSON. Durch dieses Verhalten kann der JSON-Code einen Roundtrip durchführen, ohne dass zusätzliche Daten verloren gehen, die andernfalls nicht deserialisiert werden.This behavior lets the JSON make a round trip without losing any extra data that otherwise wouldn't be deserialized.

NULL beim Deserialisieren ignorierenIgnore null when deserializing

Wenn eine Eigenschaft in JSON NULL ist, wird die entsprechende Eigenschaft im Zielobjekt standardmäßig auf NULL festgelegt.By default, if a property in JSON is null, the corresponding property in the target object is set to null. In einigen Szenarios hat die Zieleigenschaft möglicherweise einen Standardwert, und Sie möchten nicht, dass ein NULL-Wert den Standardwert überschreibt.In some scenarios, the target property might have a default value, and you don't want a null value to override the default.

Nehmen Sie beispielsweise an, der folgende Code stellt das Zielobjekt dar:For example, suppose the following code represents your target object:

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

Angenommen, der folgende JSON-Code wird deserialisiert:And suppose the following JSON is deserialized:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": null
}

Nach der Deserialisierung ist die Summary-Eigenschaft des WeatherForecastWithDefault-Objekts NULL.After deserialization, the Summary property of the WeatherForecastWithDefault object is null.

Um dieses Verhalten zu ändern, legen Sie JsonSerializerOptions.IgnoreNullValues auf truefest, wie im folgenden Beispiel gezeigt:To change this behavior, set JsonSerializerOptions.IgnoreNullValues to true, as shown in the following example:

var options = new JsonSerializerOptions
{
    IgnoreNullValues = true
};
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithDefault>(jsonString, options);

Bei dieser Option ist die Summary-Eigenschaft des WeatherForecastWithDefault Objekts der Standardwert "keine Zusammenfassung" nach der Deserialisierung.With this option, the Summary property of the WeatherForecastWithDefault object is the default value "No summary" after deserialization.

NULL-Werte in JSON werden nur ignoriert, wenn sie gültig sind.Null values in the JSON are ignored only if they are valid. NULL-Werte für Werttypen, die keine NULL-Werte zulassen, verursachen Ausnahmen.Null values for non-nullable value types cause exceptions.

Utf8JsonReader, Utf8JsonWriter und JsonDocumentUtf8JsonReader, Utf8JsonWriter, and JsonDocument

System.Text.Json.Utf8JsonReader ist eine leistungsstarke, niedrige und vorwärts gerichtete Funktion für UTF-8-codierten JSON-Text, der aus einem ReadOnlySpan<byte> oder ReadOnlySequence<byte>gelesen wird.System.Text.Json.Utf8JsonReader is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a ReadOnlySpan<byte> or ReadOnlySequence<byte>. Der Utf8JsonReader ist ein Typ auf niedriger Ebene, der zum Erstellen von benutzerdefinierten Parser und deserialisierern verwendet werden kann.The Utf8JsonReader is a low-level type that can be used to build custom parsers and deserializers. Die JsonSerializer.Deserialize-Methode verwendet Utf8JsonReader unter dem Cover.The JsonSerializer.Deserialize method uses Utf8JsonReader under the covers.

System.Text.Json.Utf8JsonWriter ist eine hochleistungsfähige Methode zum Schreiben von UTF-8-codiertem JSON-Text aus gängigen .NET-Typen wie String, Int32und DateTime.System.Text.Json.Utf8JsonWriter is a high-performance way to write UTF-8 encoded JSON text from common .NET types like String, Int32, and DateTime. Der Writer ist ein Typ auf niedriger Ebene, der zum Erstellen von benutzerdefinierten Serialisierern verwendet werden kann.The writer is a low-level type that can be used to build custom serializers. Die JsonSerializer.Serialize-Methode verwendet Utf8JsonWriter unter dem Cover.The JsonSerializer.Serialize method uses Utf8JsonWriter under the covers.

System.Text.Json.JsonDocument bietet die Möglichkeit, mit Utf8JsonReaderein Schreib geschütztes Dokumentobjektmodell (DOM) zu erstellen.System.Text.Json.JsonDocument provides the ability to build a read-only Document Object Model (DOM) by using Utf8JsonReader. Das DOM bietet wahlfreien Zugriff auf Daten in einer JSON-Nutzlast.The DOM provides random access to data in a JSON payload. Auf die JSON-Elemente, aus denen sich die Nutzlast zusammensetzt, kann über den JsonElement Typ zugegriffen werden.The JSON elements that compose the payload can be accessed via the JsonElement type. Der JsonElement-Typ stellt Array-und Objekt Enumeratoren zusammen mit APIs bereit, um JSON-Text in allgemeine .NET-Typen zu konvertieren.The JsonElement type provides array and object enumerators along with APIs to convert JSON text to common .NET types. JsonDocument macht eine RootElement-Eigenschaft verfügbar.JsonDocument exposes a RootElement property.

In den folgenden Abschnitten wird gezeigt, wie diese Tools zum Lesen und Schreiben von JSON verwendet werden.The following sections show how to use these tools for reading and writing JSON.

Verwenden von JsonDocument für den Zugriff auf DatenUse JsonDocument for access to data

Im folgenden Beispiel wird gezeigt, wie Sie die JsonDocument-Klasse für den zufälligen Zugriff auf Daten in einer JSON-Zeichenfolge verwenden:The following example shows how to use the JsonDocument class for random access to data in a JSON string:

double sum = 0;
int count = 0;

using (JsonDocument document = JsonDocument.Parse(jsonString))
{
    JsonElement root = document.RootElement;
    JsonElement studentsElement = root.GetProperty("Students");
    foreach (JsonElement student in studentsElement.EnumerateArray())
    {
        if (student.TryGetProperty("Grade", out JsonElement gradeElement))
        {
            sum += gradeElement.GetDouble();
        }
        else
        {
            sum += 70;
        }
        count++;
    }
}

double average = sum / count;
Console.WriteLine($"Average grade : {average}");

Der vorangehende Code:The preceding code:

  • Geht davon aus, dass der zu analysierende JSON-Code eine Zeichenfolge namens jsonStringAssumes the JSON to analyze is in a string named jsonString.

  • Berechnet eine durchschnittliche Qualität für Objekte in einem Students Array mit einer Grade-Eigenschaft.Calculates an average grade for objects in a Students array that have a Grade property.

  • Weist eine Standardnote von 70 für Studenten zu, die keine Note habenAssigns a default grade of 70 for students who don't have a grade.

  • Zählt Schüler und Studenten durch Inkrementieren einer count Variablen bei jeder Iterationen.Counts students by incrementing a count variable with each iteration. Eine Alternative besteht darin, GetArrayLengthaufzurufen, wie im folgenden Beispiel gezeigt:An alternative is to call GetArrayLength, as shown in the following example:

    double sum = 0;
    int count = 0;
    
    using (JsonDocument document = JsonDocument.Parse(jsonString))
    {
        JsonElement root = document.RootElement;
        JsonElement studentsElement = root.GetProperty("Students");
    
        count = studentsElement.GetArrayLength();
    
        foreach (JsonElement student in studentsElement.EnumerateArray())
        {
            if (student.TryGetProperty("Grade", out JsonElement gradeElement))
            {
                sum += gradeElement.GetDouble();
            }
            else
            {
                sum += 70;
            }
        }
    }
    
    double average = sum / count;
    Console.WriteLine($"Average grade : {average}");
    

Im Folgenden finden Sie ein Beispiel für die JSON-Zeichenfolge, die von diesem Code verarbeitet wird:Here's an example of the JSON that this code processes:

{
  "Class Name": "Science",
  "Teacher\u0027s Name": "Jane",
  "Semester": "2019-01-01",
  "Students": [
    {
      "Name": "John",
      "Grade": 94.3
    },
    {
      "Name": "James",
      "Grade": 81.0
    },
    {
      "Name": "Julia",
      "Grade": 91.9
    },
    {
      "Name": "Jessica",
      "Grade": 72.4
    },
    {
      "Name": "Johnathan"
    }
  ],
  "Final": true
}

Verwenden von jsondocument zum Schreiben von JSONUse JsonDocument to write JSON

Im folgenden Beispiel wird gezeigt, wie JSON aus einem JsonDocumentgeschrieben wird:The following example shows how to write JSON from a JsonDocument:

string jsonString = File.ReadAllText(inputFileName);

var writerOptions = new JsonWriterOptions
{
    Indented = true
};

var documentOptions = new JsonDocumentOptions
{
    CommentHandling = JsonCommentHandling.Skip
};

using FileStream fs = File.Create(outputFileName);
using var writer = new Utf8JsonWriter(fs, options: writerOptions);
using JsonDocument document = JsonDocument.Parse(jsonString, documentOptions);

JsonElement root = document.RootElement;

if (root.ValueKind == JsonValueKind.Object)
{
    writer.WriteStartObject();
}
else
{
    return;
}

foreach (JsonProperty property in root.EnumerateObject())
{
    property.WriteTo(writer);
}

writer.WriteEndObject();

writer.Flush();

Der vorangehende Code:The preceding code:

  • Liest eine JSON-Datei, lädt die Daten in eine JsonDocumentund schreibt formatierte (hübsch gedruckte) JSON-Daten in eine Datei.Reads a JSON file, loads the data into a JsonDocument, and writes formatted (pretty-printed) JSON to a file.
  • Verwendet JsonDocumentOptions, um anzugeben, dass Kommentare in der JSON-Eingabe zulässig sind, aber ignoriert werden.Uses JsonDocumentOptions to specify that comments in the input JSON are allowed but ignored.
  • Wenn Sie fertig sind, ruft Flush für den Writer auf.When finished, calls Flush on the writer. Eine Alternative besteht darin, den Writer automatisch flushen zu lassen, wenn er verworfen wird.An alternative is to let the writer autoflush when it's disposed.

Im Folgenden finden Sie ein Beispiel für eine JSON-Eingabe, die durch den Beispielcode verarbeitet werden soll:Here's an example of JSON input to be processed by the example code:

{"Class Name": "Science","Teacher's Name": "Jane","Semester": "2019-01-01","Students": [{"Name": "John","Grade": 94.3},{"Name": "James","Grade": 81.0},{"Name": "Julia","Grade": 91.9},{"Name": "Jessica","Grade": 72.4},{"Name": "Johnathan"}],"Final": true}

Das Ergebnis ist die folgende formatierte JSON-Ausgabe:The result is the following pretty-printed JSON output:

{
  "Class Name": "Science",
  "Teacher\u0027s Name": "Jane",
  "Semester": "2019-01-01",
  "Students": [
    {
      "Name": "John",
      "Grade": 94.3
    },
    {
      "Name": "James",
      "Grade": 81.0
    },
    {
      "Name": "Julia",
      "Grade": 91.9
    },
    {
      "Name": "Jessica",
      "Grade": 72.4
    },
    {
      "Name": "Johnathan"
    }
  ],
  "Final": true
}

Utf8JsonWriter verwendenUse Utf8JsonWriter

Im folgenden Beispiel wird gezeigt, wie die Utf8JsonWriter-Klasse verwendet wird:The following example shows how to use the Utf8JsonWriter class:

var options = new JsonWriterOptions
{
    Indented = true
};

using (var stream = new MemoryStream())
{
    using (var writer = new Utf8JsonWriter(stream, options))
    {
        writer.WriteStartObject();
        writer.WriteString("date", DateTimeOffset.UtcNow);
        writer.WriteNumber("temp", 42);
        writer.WriteEndObject();
    }

    string json = Encoding.UTF8.GetString(stream.ToArray());
    Console.WriteLine(json);
}

Utf8JsonReader verwendenUse Utf8JsonReader

Im folgenden Beispiel wird gezeigt, wie die Utf8JsonReader-Klasse verwendet wird:The following example shows how to use the Utf8JsonReader class:

var options = new JsonReaderOptions
{
    AllowTrailingCommas = true,
    CommentHandling = JsonCommentHandling.Skip
};
Utf8JsonReader reader = new Utf8JsonReader(jsonUtf8Bytes, options);

while (reader.Read())
{
    Console.Write(reader.TokenType);

    switch (reader.TokenType)
    {
        case JsonTokenType.PropertyName:
        case JsonTokenType.String:
            {
                string text = reader.GetString();
                Console.Write(" ");
                Console.Write(text);
                break;
            }

        case JsonTokenType.Number:
            {
                int intValue = reader.GetInt32();
                Console.Write(" ");
                Console.Write(intValue);
                break;
            }

            // Other token types elided for brevity
    }
    Console.WriteLine();
}

Der vorangehende Code geht davon aus, dass es sich bei der jsonUtf8 Variable um ein Bytearray handelt, das gültige JSON-Codierung als UTF-8 enthältThe preceding code assumes that the jsonUtf8 variable is a byte array that contains valid JSON, encoded as UTF-8.

Filtern von Daten mithilfe von Utf8JsonReaderFilter data using Utf8JsonReader

Im folgenden Beispiel wird gezeigt, wie eine Datei synchron gelesen und nach einem Wert gesucht wird:The following example shows how to read a file synchronously and search for a value:

using System;
using System.IO;
using System.Text;
using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class Utf8ReaderFromFile
    {
        private static readonly byte[] s_nameUtf8 = Encoding.UTF8.GetBytes("name");
        private static ReadOnlySpan<byte> Utf8Bom => new byte[] { 0xEF, 0xBB, 0xBF };
        public static void Run()
        {
            // ReadAllBytes if the file encoding is UTF-8:
            string fileName = "UniversitiesUtf8.json";
            ReadOnlySpan<byte> jsonReadOnlySpan = File.ReadAllBytes(fileName);

            // Read past the UTF-8 BOM bytes if a BOM exists.
            if (jsonReadOnlySpan.StartsWith(Utf8Bom))
            {
                jsonReadOnlySpan = jsonReadOnlySpan.Slice(Utf8Bom.Length);
            }

            // Or read as UTF-16 and transcode to UTF-8 to convert to a ReadOnlySpan<byte>
            //string fileName = "Universities.json";
            //string jsonString = File.ReadAllText(fileName);
            //ReadOnlySpan<byte> jsonReadOnlySpan = Encoding.UTF8.GetBytes(jsonString);


            int count = 0;
            int total = 0;

            var reader = new Utf8JsonReader(jsonReadOnlySpan);

            while (reader.Read())
            {
                JsonTokenType tokenType = reader.TokenType;

                switch (tokenType)
                {
                    case JsonTokenType.StartObject:
                        total++;
                        break;
                    case JsonTokenType.PropertyName:
                        if (reader.ValueTextEquals(s_nameUtf8))
                        {
                            // Assume valid JSON, known schema
                            reader.Read();
                            if (reader.GetString().EndsWith("University"))
                            {
                                count++;
                            }
                        }
                        break;
                }
            }
            Console.WriteLine($"{count} out of {total} have names that end with 'University'");
        }
    }
}

Der vorangehende Code:The preceding code:

  • Geht davon aus, dass der JSON-Code ein Array von Objekten enthält und jedes Objekt eine "name"-Eigenschaft vom Typ "String" enthalten kann.Assumes the JSON contains an array of objects and each object may contain a "name" property of type string.

  • Zählt Objekte und "Name"-Eigenschaftswerte, die mit "University" enden.Counts objects and "name" property values that end with "University".

  • Geht davon aus, dass die Datei UTF-16-codiert ist, und transcodiert sie in UTF-8.Assumes the file is encoded as UTF-16 and transcodes it into UTF-8. Eine Datei, die als UTF-8 codiert ist, kann mithilfe des folgenden Codes direkt in eine ReadOnlySpan<byte>gelesen werden:A file encoded as UTF-8 can be read directly into a ReadOnlySpan<byte>, by using the following code:

    ReadOnlySpan<byte> jsonReadOnlySpan = File.ReadAllBytes(fileName);
    

    Wenn die Datei eine UTF-8-Byte Reihenfolge-Marke (BOM) enthält, entfernen Sie diese, bevor Sie die Bytes an den Utf8JsonReaderübergeben, da der Reader Text erwartet.If the file contains a UTF-8 byte order mark (BOM), remove it before passing the bytes to the Utf8JsonReader, since the reader expects text. Andernfalls wird die BOM als ungültige JSON betrachtet, und der Reader löst eine Ausnahme aus.Otherwise, the BOM is considered invalid JSON, and the reader throws an exception.

Im Folgenden finden Sie ein JSON-Beispiel, das der vorherige Code lesen kann.Here's a JSON sample that the preceding code can read. Die resultierende Zusammenfassungsmeldung lautet: "2 out of 4 have names that end with 'University'":The resulting summary message is "2 out of 4 have names that end with 'University'":

[
  {
    "web_pages": [ "https://contoso.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "contoso.edu" ],
    "name": "Contoso Community College"
  },
  {
    "web_pages": [ "http://fabrikam.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "fabrikam.edu" ],
    "name": "Fabrikam Community College"
  },
  {
    "web_pages": [ "http://www.contosouniversity.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "contosouniversity.edu" ],
    "name": "Contoso University"
  },
  {
    "web_pages": [ "http://www.fabrikamuniversity.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "fabrikamuniversity.edu" ],
    "name": "Fabrikam University"
  }
]

Zusätzliche RessourcenAdditional resources