Anpassen von Eigenschaftsnamen und -werten mit System.Text.Json

Standardmäßig bleiben Eigenschaftsnamen und Wörterbuchschlüssel in der JSON-Ausgabe unverändert, einschließlich der Groß-/Kleinschreibung. Enumerationswerte werden als Zahlen dargestellt. Und Eigenschaften werden in der Reihenfolge serialisiert, in der sie definiert sind. Sie können diese Verhaltensweisen jedoch wie folgt anpassen:

• Geben Sie bestimmte serialisierte Eigenschaftennamen an.
• Verwenden Sie eine integrierte Benennungsrichtlinie, z. B. camelCase, snake_case oder Kebab-Fall, für Eigenschaftsnamen und Wörterbuchschlüssel.
• Verwenden Sie eine benutzerdefinierte Benennungsrichtlinie für Eigenschaftennamen und Wörterbuchschlüssel.
• Serialisieren Sie Enumerationswerte als Zeichenfolgen mit oder ohne Benennungsrichtlinie.
• Konfiguriere Sie die Reihenfolge serialisierter Eigenschaften.

Für andere Szenarien, die eine besondere Behandlung von JSON-Eigenschaftsnamen und -werten erfordern, können Sie benutzerdefinierte Konverter implementieren.

Anpassen einzelner Eigenschaftsnamen

Um den Namen einzelner Eigenschaften festzulegen, verwenden Sie das Attribut [JsonPropertyName].

Hier finden Sie einen zu serialisierenden Beispieltyp und die daraus resultierende JSON-Ausgabe:

public class WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyName
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String

    <JsonPropertyName("Wind")>
    Public Property WindSpeed As Integer

End Class

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

Der über dieses Attribut festgelegte Eigenschaftsname:

• Dies gilt in beide Richtungen, für Serialisierung und Deserialisierung.
• Es hat Vorrang vor Benennungsrichtlinien für Eigenschaften.
• Wirkt sich nicht auf den Abgleich von Parameternamen für parametrisierte Konstruktoren aus.

Verwenden Sie eine integrierte Benennungsrichtlinie

In der folgenden Tabelle sind die integrierten Benennungsrichtlinien und ihre Auswirkungen auf Eigenschaftennamen aufgeführt.

(Verfügbar in .NET 8 und höheren Versionen.)

Das folgende Beispiel zeigt, wie Sie camelCase für alle JSON-Eigenschaftsnamen verwenden, indem Sie JsonSerializerOptions.PropertyNamingPolicy für JsonNamingPolicy.CamelCase festlegen:

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

Dim serializeOptions As JsonSerializerOptions = New JsonSerializerOptions With {
    .PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions)

Hier finden Sie eine zu serialisierenden Beispielklasse und die JSON-Ausgabe:

public class WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyName
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String

    <JsonPropertyName("Wind")>
    Public Property WindSpeed As Integer

End Class

{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
  "Wind": 35
}

Die Benennungsrichtlinie:

• Gilt für Serialisierung und Deserialisierung.
• Wird von [JsonPropertyName]-Attributen außer Kraft gesetzt. Aus diesem Grund ist der JSON-Eigenschaftsname Wind im Beispiel nicht in Camel-Case-Schreibweise.

Verwenden einer benutzerdefinierten Benennungsrichtlinie für JSON-Eigenschaften

Um eine benutzerdefinierte Benennungsrichtlinie für JSON-Eigenschaften zu verwenden, erstellen Sie eine Klasse, die von JsonNamingPolicy abgeleitet ist, und setzen Sie die ConvertName-Methode außer Kraft, wie im folgenden Beispiel gezeigt:

using System.Text.Json;

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

Imports System.Text.Json

Namespace SystemTextJsonSamples

    Public Class UpperCaseNamingPolicy
        Inherits JsonNamingPolicy

        Public Overrides Function ConvertName(name As String) As String
            Return name.ToUpper()
        End Function

    End Class

End Namespace

Legen Sie dann die JsonSerializerOptions.PropertyNamingPolicy-Eigenschaft auf eine Instanz Ihre Benennungsrichtlinienklasse fest:

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

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

Hier finden Sie eine zu serialisierenden Beispielklasse und die JSON-Ausgabe:

public class WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyName
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String

    <JsonPropertyName("Wind")>
    Public Property WindSpeed As Integer

End Class

{
  "DATE": "2019-08-01T00:00:00-07:00",
  "TEMPERATURECELSIUS": 25,
  "SUMMARY": "Hot",
  "Wind": 35
}

Die Benennungsrichtlinie für JSON-Eigenschaften:

• Gilt für Serialisierung und Deserialisierung.
• Wird von [JsonPropertyName]-Attributen außer Kraft gesetzt. Aus diesem Grund ist der JSON-Eigenschaftsname Wind im Beispiel nicht in Großbuchstaben.

Verwenden einer Benennungsrichtlinie für Wörterbuchschlüssel

Wenn eine Eigenschaft eines zu serialisierenden Objekts vom Typ Dictionary<string,TValue> ist, können die string-Schlüssel mithilfe einer Benennungsrichtlinie konvertiert werden, z. B. camelCase. Legen Sie dazu JsonSerializerOptions.DictionaryKeyPolicy auf die gewünschte Benennungsrichtlinie fest. Im folgenden Beispiel wird die CamelCase-Benennungsrichtlinie verwendet:

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

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

Das Serialisieren eines Objekts mit einem Wörterbuch namens TemperatureRanges, das die Schlüssel-Wert-Paare "ColdMinTemp", 20 und "HotMinTemp", 40 enthält, würde zu einer JSON-Ausgabe wie im folgenden Beispiel führen:

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

Benennungsrichtlinien für Wörterbuchschlüssel gelten nur für die Serialisierung. Wenn Sie ein Wörterbuch deserialisieren, stimmen die Schlüssel auch dann mit der JSON-Datei überein, wenn Sie JsonSerializerOptions.DictionaryKeyPolicy für eine nicht standardmäßige Benennungsrichtlinie festlegen.

Enumerationen als Zeichenfolgen

Angenommen, Sie müssen die folgende Klasse serialisieren, die über eine Enumeration verfügt:

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
}

Public Class WeatherForecastWithEnum
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As Summary
End Class

Public Enum Summary
    Cold
    Cool
    Warm
    Hot
End Enum

Wenn die Zusammenfassung Hot ist, hat das serialisierte JSON standardmäßig den numerischen Wert 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:

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

options = New JsonSerializerOptions With {
    .WriteIndented = True
}
options.Converters.Add(New JsonStringEnumConverter(JsonNamingPolicy.CamelCase))
jsonString = JsonSerializer.Serialize(weatherForecast, options)

Das resultierende JSON sieht wie im folgenden Beispiel aus:

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

Der integrierte JsonStringEnumConverter kann auch Zeichenfolgenwerte deserialisieren. Es funktioniert mit oder ohne eine angegebene Benennungsrichtlinie. Das folgende Beispiel zeigt die Deserialisierung mit CamelCase:

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

options = New JsonSerializerOptions
options.Converters.Add(New JsonStringEnumConverter(JsonNamingPolicy.CamelCase))
weatherForecast = JsonSerializer.Deserialize(Of WeatherForecastWithEnum)(jsonString, options)

public class WeatherForecastWithPrecipEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Precipitation? Precipitation { get; set; }
}

[JsonConverter(typeof(JsonStringEnumConverter<Precipitation>))]
public enum Precipitation
{
    Drizzle, Rain, Sleet, Hail, Snow
}

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

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Precipitation": "Sleet"
}

Konfigurieren der Reihenfolge serialisierter Eigenschaften

Standardmäßig werden Eigenschaften in der Reihenfolge serialisiert, in der sie in ihrer Klasse definiert sind. Mit dem [JsonPropertyOrder]-Attribut können Sie die Reihenfolge der Eigenschaften in der JSON-Ausgabe der Serialisierung angeben. Der Standardwert der Order-Eigenschaft ist Null. Legen Sie Order auf eine positive Zahl fest, um eine Eigenschaft nach Eigenschaften mit dem Standardwert zu positionieren. Durch einen negativen Order-Wert wird eine Eigenschaft vor Eigenschaften mit dem Standardwert positioniert. Eigenschaften werden in aufsteigender Reihenfolge des Order-Werts ausgegeben. Ein Beispiel:

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

namespace PropertyOrder
{
    public class WeatherForecast
    {
        [JsonPropertyOrder(-5)]
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        [JsonPropertyOrder(-2)]
        public int TemperatureF { get; set; }
        [JsonPropertyOrder(5)]
        public string? Summary { get; set; }
        [JsonPropertyOrder(2)]
        public int WindSpeed { get; set; }
    }

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

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);
            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00",
//  "TemperatureF": 25,
//  "TemperatureC": 25,
//  "WindSpeed": 10,
//  "Summary": "Hot"
//}

Verwenden von Github Copilot zum Anpassen von Eigenschaftsnamen und -reihenfolgen

Sie können GitHub Copilot in Ihrer IDE verwenden, um Code zu generieren, um Namen und Reihenfolge serialisierter Eigenschaften anzupassen.

Wenn Sie Visual Studio 2022 Version 17.8 oder höher verwenden, können Sie das KI-gesteuerte GitHub Copilot in Visual Studio ausprobieren, um Code zu generieren, der System.Text.Json verwendet, um Eigenschaftsnamen und Reihenfolgen in der JSON-Ausgabe nach der Serialisierung anzupassen. Reichen Sie im Chat-Fenster von Copilot Ihre Frage als Eingabeaufforderung ein. Sehen Sie sich hierzu das folgende Beispiel an. Sie können Eingabeaufforderungen auch über den Inline-Chat im Editorfenster senden.

Im folgenden Beispiel wird gezeigt, wie Sie mit Copilot vorhandenen Code ändern, um Eigenschaftsnamen und -reihenfolge beim Serialisieren zu JSON anzupassen.

1. Fügen Sie im Editor den folgenden C#-Beispielcode zu einer Codedatei Example.cs hinzu. In Visual Studio können Sie ein C#-Konsolenanwendungsprojekt verwenden, um dieses Beispiel zu testen.

   using System.Text.Json;
   
   public class Person
   {
       public string? FirstName { get; set; }
       public string? LastName { get; set; }
       public int Age { get; set; }
       public string? Country { get; set; }
   }
   
   public class Program
   {
       public static void Main()
       {
           var person = new Person
           {
               FirstName = "John",
               LastName = "Doe",
               Age = 30,
               Country = "USA"
           };
   
           string jsonString = JsonSerializer.Serialize(person);
           Console.WriteLine(jsonString);
       }
   }
   

   Der Example.cs-Code führt Folgendes aus:

   • Erstellt eine Instanz der Person-Klasse und initialisiert seine Eigenschaften mit Werten.
   • Serialisiert das person-Objekt mit einer JSON-Zeichenfolge unter Verwendung von JsonSerializer.Serialize
   • Druckt die folgende JSON-Zeichenfolge in der Konsole:

   {"FirstName":"John","LastName":"Doe","Age":30,"Country":"USA"}
   

2. Geben Sie in Copilot Chat die folgende Eingabeaufforderung ein, um den Code so zu ändern, dass Namen und Reihenfolge der JSON-Serialisierungsausgabe angepasst werden.

   #Example.cs Ändern Sie Code zur Verwendung von System.Text.Json um Anpassen von Eigenschaftsnamen und der Reihenfolge der JSON-Ausgabe aus der Serialisierung. Festlegen von Eigenschaftsnamen: FirstName zu first_name, LastName zu last_name. Festlegen der Reihenfolge auf: Country, FirstName, LastName, Age. Bereitstellen einer angepassten Serialisierungsausgabe.

   #Example.cs in der Eingabeaufforderung stellt eine -Dateireferenz als Kontext für Copilot bereit. Sie können die Eingabeaufforderung so anpassen, dass sie eine JSON-Zeichenfolge mit Eigenschaftsnamen und -werten ausgibt, die Ihren Anforderungen entsprechen. Um eine Absicht festzulegen und bessere Antworten mit bereichsbezogenem Kontext zu erhalten, können Sie Chat-Funktionen wie Slash-Befehle, Verweise auf Dateien, Methoden oder Klassen sowie Threads verwenden.

   Die folgende Ausgabe zeigt ein Beispiel für eine Copilot Chat-Antwort:

   To customize the property names and order of the JSON output using System.Text.Json, you can use the JsonPropertyName attribute to rename properties and the JsonPropertyOrder attribute to set the order. Here's how you can modify your code:
   
   using System.Text.Json;
   using System.Text.Json.Serialization;
   
   public class Person
   {
       [JsonPropertyName("first_name")]
       [JsonPropertyOrder(2)]
       public string? FirstName { get; set; }
   
       [JsonPropertyName("last_name")]
       [JsonPropertyOrder(3)]
       public string? LastName { get; set; }
   
       [JsonPropertyOrder(4)]
       public int Age { get; set; }
   
       [JsonPropertyOrder(1)]
       public string? Country { get; set; }
   }
   
   public class Program
   {
       public static void Main()
       {
           var person = new Person
           {
               FirstName = "John",
               LastName = "Doe",
               Age = 30,
               Country = "USA"
           };
   
           string jsonString = JsonSerializer.Serialize(person, new JsonSerializerOptions { WriteIndented = true });
           Console.WriteLine(jsonString);
       }
   }
   
   **Explanation:**
   
   1. Renaming Properties: The JsonPropertyName attribute is used to rename FirstName to first_name and LastName to last_name.
   2. Ordering Properties: The JsonPropertyOrder attribute is used to set the order of the properties in the JSON output. The order is set as:
      • Country (Order 1)
      • FirstName (Order 2)
      • LastName (Order 3)
      • Age (Order 4)
   3. Indented JSON: The JsonSerializerOptions with WriteIndented = true is used to make the JSON output more readable.
   
   **Customized Serialization Output:**
   {
     "Country": "USA",
     "first_name": "John",
     "last_name": "Doe",
     "Age": 30
   }
   
   This ensures that the JSON output has the customized property names and the specified order.
   

Wenn Copilot einen Codeblock zurückgibt, dann werden in der Antwort Optionen zum Kopieren des Codes, zum Einfügen des Codes in eine neue Datei oder zum Anzeigen einer Vorschau des Codes aufgelistet.

Siehe auch

• System.Text.Json – Übersicht
• Vorgehensweise: Serialisieren und Deserialisieren von JSON-Daten
• GitHub Copilot Trust Center
• GitHub Copilot in Visual Studio
• GitHub Copilot in VS Code