Přizpůsobení názvů a hodnot vlastností pomocí System.Text.Json

Článek
10/24/2024

Ve výchozím nastavení se názvy vlastností a klíče slovníku ve výstupu JSON nemění, včetně případu. Hodnoty výčtu jsou reprezentovány jako čísla. Vlastnosti jsou serializovány v pořadí, v jakém jsou definovány. Toto chování ale můžete přizpůsobit takto:

Určuje konkrétní serializovanou vlastnost a názvy členů výčtu.
Použití předdefinovaných zásad pojmenování, jako jsou camelCase, snake_case nebo kebab-case, pro názvy vlastností a klíče slovníku.
Použití vlastních zásad pojmenování pro názvy vlastností a klíče slovníku.
Serializace hodnot výčtu jako řetězců s zásadami pojmenování nebo bez.
Konfigurace pořadí serializovaných vlastností

Poznámka:

Výchozí zásada pojmenování webu je velká a malá písmena.

Tip

Pomoc s AI můžete použít k přizpůsobení názvů a hodnot vlastností pomocí GitHub Copilotu.

V jiných scénářích, které vyžadují speciální zpracování názvů a hodnot vlastností JSON, můžete implementovat vlastní převaděče.

Přizpůsobení názvů jednotlivých vlastností

Pokud chcete nastavit název jednotlivých vlastností, použijte atribut [JsonPropertyName].

Tady je příklad typu serializace a výsledného formátu JSON:

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
}

Název vlastnosti nastavený tímto atributem:

Platí v obou směrech pro serializaci a deserializaci.
Má přednost před zásadami pojmenování vlastností.
Nemá vliv na porovnávání názvů parametrů pro parametrizované konstruktory.

Použití předdefinovaných zásad pojmenování

Následující tabulka ukazuje předdefinované zásady pojmenování a jejich vliv na názvy vlastností.

Zásady pojmenovávání	Popis	Původní název vlastnosti	Převedený název vlastnosti
CamelCase	První slovo začíná znakem malého písmena. Po sobě jdoucí slova začínají velkými písmeny.	`TempCelsius`	`tempCelsius`
KebabCaseLower*	Slova jsou oddělená pomlčkami. Všechny znaky jsou malými písmeny.	`TempCelsius`	`temp-celsius`
KebabCaseUpper*	Slova jsou oddělená pomlčkami. Všechny znaky jsou velké.	`TempCelsius`	`TEMP-CELSIUS`
SnakeCaseLower*	Slova jsou oddělená podtržítky. Všechny znaky jsou malými písmeny.	`TempCelsius`	`temp_celsius`
SnakeCaseUpper*	Slova jsou oddělená podtržítky. Všechny znaky jsou velké.	`TempCelsius`	`TEMP_CELSIUS`

* K dispozici v .NET 8 a novějších verzích.

Následující příklad ukazuje, jak použít camel case pro všechny názvy vlastností JSON nastavením JsonSerializerOptions.PropertyNamingPolicy na JsonNamingPolicy.CamelCase:

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)

Tady je příklad třídy pro serializaci a výstup JSON:

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
}

Zásady pojmenování:

Platí pro serializaci a deserializaci.
Přepíše se atributy [JsonPropertyName] . To je důvod, proč název Wind vlastnosti JSON v příkladu není camel case.

Poznámka:

Žádná z předdefinovaných zásad pojmenování nepodporuje písmena, která jsou náhradními páry. Další informace najdete v tématu dotnet/runtime problém 90352.

Použití vlastních zásad pojmenování vlastností JSON

Pokud chcete použít vlastní zásady pojmenování vlastností JSON, vytvořte třídu odvozenou od JsonNamingPolicy metody a přepište ConvertName ji, jak je znázorněno v následujícím příkladu:

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

Pak nastavte JsonSerializerOptions.PropertyNamingPolicy vlastnost na instanci vaší třídy zásad pojmenování:

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)

Tady je příklad třídy pro serializaci a výstup JSON:

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
}

Zásady pojmenování vlastností JSON:

Platí pro serializaci a deserializaci.
Přepíše se atributy [JsonPropertyName] . Proto název vlastnosti Wind JSON v příkladu není velkými písmeny.

Použití zásad pojmenování pro klíče slovníku

Pokud je vlastnost objektu, který má být serializován, typ Dictionary<string,TValue>, string lze klíče převést pomocí zásad pojmenování, jako je camel case. Uděláte to tak, že nastavíte JsonSerializerOptions.DictionaryKeyPolicy požadovanou zásadu pojmenování. Následující příklad používá zásadu CamelCase pojmenování:

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)

Serializace objektu pomocí slovníku s názvem TemperatureRanges , který má páry "ColdMinTemp", 20 klíč-hodnota, a "HotMinTemp", 40 výsledkem by byl výstup JSON podobný následujícímu příkladu:

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

Zásady pojmenování pro klíče slovníku se vztahují pouze na serializaci. Pokud deserializujete slovník, klíče se shodují se souborem JSON, i když nastavíte JsonSerializerOptions.DictionaryKeyPolicy jiné než výchozí zásady pojmenování.

Výčty jako řetězce

Ve výchozím nastavení jsou výčty serializovány jako čísla. Chcete-li serializovat názvy výčtů jako řetězce, použijte JsonStringEnumConverter nebo JsonStringEnumConverter<TEnum> převaděč. Nativní modul runtime AOT podporuje pouze JsonStringEnumConverter<TEnum> .

Předpokládejme například, že potřebujete serializovat následující třídu, která má výčt:

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

Pokud je Hotsouhrn , serializovaný JSON má ve výchozím nastavení číselnou hodnotu 3:

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

Následující vzorový kód serializuje názvy výčtů místo číselných hodnot a převede názvy na camel case:

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)

Výsledný json vypadá jako v následujícím příkladu:

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

Předdefinované JsonStringEnumConverter můžou deserializovat i řetězcové hodnoty. Funguje s zadanou zásadou pojmenování nebo bez ní. Následující příklad ukazuje deserializaci pomocí 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)

JsonConverterAttribute

Můžete také určit převaděč, který se má použít, anotací výčtu pomocí JsonConverterAttribute. Následující příklad ukazuje, jak pomocí atributu JsonConverterAttribute určit JsonStringEnumConverter<TEnum> (dostupné v .NET 8 a novějších verzích). Předpokládejme například, že potřebujete serializovat následující třídu, která má výčt:

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
}

Následující vzorový kód serializuje názvy výčtů místo číselných hodnot:

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

Výsledný json vypadá takto:

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

Vlastní názvy členů výčtu

Počínaje rozhraním .NET 9 můžete přizpůsobit názvy jednotlivých členů výčtu pro typy, které jsou serializovány jako řetězce. Pokud chcete přizpůsobit název člena výčtu, označte ho atributem JsonStringEnumMemberName.

Předpokládejme například, že potřebujete serializovat následující třídu, která má výčt s vlastním názvem člena:

public class WeatherForecastWithEnumCustomName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public CloudCover? Sky { get; set; }
}

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum CloudCover
{
    Clear,
    [JsonStringEnumMemberName("Partly cloudy")]
    Partial,
    Overcast
}

Následující vzorový kód serializuje názvy výčtů místo číselných hodnot:

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

Výsledný json vypadá takto:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Sky": "Partly cloudy"
}

Generování zdroje

Chcete-li použít převaděč s generováním zdroje, viz serializace výčtových polí jako řetězce.

Konfigurace pořadí serializovaných vlastností

Ve výchozím nastavení jsou vlastnosti serializovány v pořadí, ve kterém jsou definovány ve své třídě. Atribut [JsonPropertyOrder] umožňuje zadat pořadí vlastností ve výstupu JSON ze serializace. Výchozí hodnota Order vlastnosti je nula. Nastavte Order na kladné číslo, aby se vlastnost umístila za vlastnostmi, které mají výchozí hodnotu. Záporná Order pozice vlastnosti před vlastnostmi, které mají výchozí hodnotu. Vlastnosti se zapisují v pořadí od nejnižší Order hodnoty po nejvyšší. Tady je příklad:

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

Přizpůsobení názvů a pořadí vlastností pomocí GitHub Copilotu

Pomocí GitHub Copilotu v integrovaném vývojovém prostředí (IDE) můžete vygenerovat kód pro přizpůsobení názvů a pořadí serializovaných vlastností.

Pokud používáte Visual Studio 2022 verze 17.8 nebo novější, můžete zkusit v sadě Visual Studio vygenerovat kód, který používá System.Text.Json k přizpůsobení názvů vlastností a pořadí ve výstupu JSON ze serializce. Odešlete otázku jako výzvu v okně chatu Copilot, jak je znázorněno v následujícím příkladu. Můžete také odesílat výzvy pomocí vloženého chatu v samotném okně editoru.

Poznámka:

GitHub Copilot využívá technologii AI, takže jsou možná překvapení a chyby. Nezapomeňte ověřit vygenerovaný kód nebo návrhy. Další informace o obecném použití GitHub Copilotu, dopadu produktu, lidského dohledu a ochrany osobních údajů najdete v nejčastějších dotazech ke Kopírování GitHubu.

Následující příklad ukazuje, jak pomocí Copilotu upravit existující kód pro přizpůsobení názvů vlastností a pořadí při serializaci do FORMÁTU JSON.

Do souboru Example.cs kódu v editoru přidejte následující ukázkový kód jazyka C#. V sadě Visual Studio můžete k vyzkoušení tohoto příkladu použít projekt konzolové aplikace jazyka C#.

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

Example.cs kód provede následující:

Vytvoří instanci Person třídy a inicializuje její vlastnosti hodnotami.
Serializuje person objekt do řetězce JSON pomocí JsonSerializer.Serialize.
Vytiskne do konzoly následující řetězec JSON:

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

V souboru Copilot Chat zadejte následující výzvu k úpravě kódu tak, aby přizpůsobil názvy a pořadí výstupu serializace JSON.

#Example.cs upravte kód tak, aby se přizpůsobily System.Text.Json názvy vlastností a pořadí výstupu JSON ze serializace. Nastavte názvy vlastností: Jméno na first_name, Příjmení na last_name. Nastavit pořadí na: Country, FirstName, LastName, Age. Zadejte přizpůsobený výstup serializace.

#Example.cs v příkazovém řádku poskytuje odkaz na soubor jako kontext pro Copilot. Můžete přizpůsobit výzvu k výstupu řetězce JSON s názvy vlastností a hodnotami, které vyhovují vašim požadavkům. Pokud chcete nastavit záměr a získat lepší odpovědi s vymezeným kontextem, můžete použít funkce chatu, jako jsou příkazy lomítka, odkazy na soubory, metody nebo třídy a vlákna.

Následující výstup ukazuje příklad odpovědi copilot chatu:

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.

Když Copilot vrátí blok kódu, odpověď obsahuje možnosti pro zkopírování kódu, vložení kódu do nového souboru nebo náhled výstupu kódu.

Poznámka:

Výsledky se můžou lišit od toho, co se zobrazuje v ukázkových odpovědích. Modely AI nejsou deterministické, což znamená, že při kladení stejné otázky můžou vrátit různé odpovědi. Důvodem může být další učení a přizpůsobení v průběhu času, jazykové variace, změny v kontextu, například historie chatu a další.

Sdílet prostřednictvím

Přizpůsobení názvů a hodnot vlastností pomocí System.Text.Json

Přizpůsobení názvů jednotlivých vlastností

Použití předdefinovaných zásad pojmenování

Použití vlastních zásad pojmenování vlastností JSON

Použití zásad pojmenování pro klíče slovníku

Výčty jako řetězce

JsonConverterAttribute

Vlastní názvy členů výčtu

Generování zdroje

Konfigurace pořadí serializovaných vlastností

Přizpůsobení názvů a pořadí vlastností pomocí GitHub Copilotu

Viz také

Další materiály