Så här anpassar du egenskapsnamn och värden med System.Text.Json

Artikel
10/24/2024

Som standard ändras egenskapsnamn och ordlistenycklar i JSON-utdata, inklusive skiftläge. Uppräkningsvärden representeras som tal. Och egenskaperna serialiseras i den ordning de definieras. Du kan dock anpassa dessa beteenden genom att:

Ange specifika serialiserade egenskaper och uppräkningsmedlemsnamn.
Använda en inbyggd namngivningsprincip, till exempel camelCase, snake_case eller kebab-case, för egenskapsnamn och ordlistenycklar.
Använda en anpassad namngivningsprincip för egenskapsnamn och ordlistenycklar.
Serialisera uppräkningsvärden som strängar, med eller utan en namngivningsprincip.
Konfigurera ordningen på serialiserade egenskaper.

Kommentar

Webbplatsens standardnamngivningsprincip är kamelfall.

Dricks

Du kan använda AI-hjälp för att anpassa egenskapsnamn och värden med GitHub Copilot.

För andra scenarier som kräver särskild hantering av JSON-egenskapsnamn och -värden kan du implementera anpassade konverterare.

Anpassa enskilda egenskapsnamn

Om du vill ange namnet på enskilda egenskaper använder du attributet [JsonPropertyName].

Här är en exempeltyp för serialisering och resulterande 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
}

Egenskapsnamnet som anges av det här attributet:

Gäller i båda riktningarna för serialisering och deserialisering.
Har företräde framför namngivningsprinciper för egenskaper.
Påverkar inte matchning av parameternamn för parametriserade konstruktorer.

Använda en inbyggd namngivningsprincip

I följande tabell visas de inbyggda namngivningsprinciperna och hur de påverkar egenskapsnamn.

Namngivningsprincip	beskrivning	Ursprungligt egenskapsnamn	Namn på konverterad egenskap
CamelCase	Första ordet börjar med ett gemener. Efterföljande ord börjar med ett versaler.	`TempCelsius`	`tempCelsius`
KebabCaseLower*	Ord avgränsas med bindestreck. Alla tecken är gemener.	`TempCelsius`	`temp-celsius`
KebabCaseUpper*	Ord avgränsas med bindestreck. Alla tecken är versaler.	`TempCelsius`	`TEMP-CELSIUS`
SnakeCaseLower*	Ord avgränsas med understreck. Alla tecken är gemener.	`TempCelsius`	`temp_celsius`
SnakeCaseUpper*	Ord avgränsas med understreck. Alla tecken är versaler.	`TempCelsius`	`TEMP_CELSIUS`

* Tillgänglig i .NET 8 och senare versioner.

I följande exempel visas hur du använder kamelfall för alla JSON-egenskapsnamn genom att ange JsonSerializerOptions.PropertyNamingPolicy till 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)

Här är en exempelklass för serialisering och JSON-utdata:

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
}

Namngivningsprincipen:

Gäller för serialisering och deserialisering.
Åsidosättas av [JsonPropertyName] attribut. Det är därför JSON-egenskapsnamnet Wind i exemplet inte är kamelfall.

Kommentar

Ingen av de inbyggda namngivningsprinciperna stöder bokstäver som är surrogatpar. Mer information finns i dotnet/runtime issue 90352.

Använda en anpassad namngivningsprincip för JSON-egenskaper

Om du vill använda en anpassad namngivningsprincip för JSON-egenskaper skapar du en klass som härleds från JsonNamingPolicy och åsidosätter ConvertName metoden, som du ser i följande exempel:

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

Ange JsonSerializerOptions.PropertyNamingPolicy sedan egenskapen till en instans av din namngivningsprincipklass:

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)

Här är en exempelklass för serialisering och JSON-utdata:

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
}

Namngivningsprincipen för JSON-egenskap:

Gäller för serialisering och deserialisering.
Åsidosättas av [JsonPropertyName] attribut. Det är därför JSON-egenskapsnamnet Wind i exemplet inte är versaler.

Använda en namngivningsprincip för ordlistenycklar

Om en egenskap för ett objekt som ska serialiseras är av typen Dictionary<string,TValue>string kan nycklarna konverteras med hjälp av en namngivningsprincip, till exempel kamelfall. Det gör du genom att ange JsonSerializerOptions.DictionaryKeyPolicy önskad namngivningsprincip. I följande exempel används CamelCase namngivningsprincipen:

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)

Serialisering av ett objekt med en ordlista med namnet TemperatureRanges som har nyckel/värde-par "ColdMinTemp", 20 och "HotMinTemp", 40 skulle resultera i JSON-utdata som i följande exempel:

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

Namngivningsprinciper för ordlistenycklar gäller endast för serialisering. Om du deserialiserar en ordlista matchar nycklarna JSON-filen även om du anger JsonSerializerOptions.DictionaryKeyPolicy en namngivningsprincip som inte är standard.

Räkna upp som strängar

Som standard serialiseras uppräkningar som tal. Om du vill serialisera uppräkningsnamn som strängar använder du JsonStringEnumConverter konverteraren eller JsonStringEnumConverter<TEnum> . Endast JsonStringEnumConverter<TEnum> stöds av den interna AOT-körningen.

Anta till exempel att du behöver serialisera följande klass som har en uppräkning:

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

Om sammanfattningen är Hothar den serialiserade JSON som standard det numeriska värdet 3:

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

Följande exempelkod serialiserar uppräkningsnamnen i stället för de numeriska värdena och konverterar namnen till kamelfall:

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)

Den resulterande JSON:en ser ut som i följande exempel:

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

De inbyggda JsonStringEnumConverter kan även deserialisera strängvärden. Den fungerar med eller utan en angiven namngivningsprincip. I följande exempel visas deserialisering med hjälp av 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

Du kan också ange vilken konverterare som ska användas genom att kommentera uppräkningen med JsonConverterAttribute. I följande exempel visas hur du anger JsonStringEnumConverter<TEnum> (tillgängliga i .NET 8 och senare versioner) med hjälp JsonConverterAttribute av attributet . Anta till exempel att du behöver serialisera följande klass som har en uppräkning:

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
}

Följande exempelkod serialiserar uppräkningsnamnen i stället för de numeriska värdena:

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

Den resulterande JSON:en ser ut så här:

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

Anpassade uppräkningsmedlemsnamn

Från och med .NET 9 kan du anpassa namnen på enskilda uppräkningsmedlemmar för typer som serialiseras som strängar. Om du vill anpassa ett uppräkningsmedlemsnamn kommenterar du det med attributet JsonStringEnumMemberName.

Anta till exempel att du behöver serialisera följande klass som har en uppräkning med ett anpassat medlemsnamn:

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
}

Följande exempelkod serialiserar uppräkningsnamnen i stället för de numeriska värdena:

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

Den resulterande JSON:en ser ut så här:

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

Källgenerering

Information om hur du använder konverteraren med källgenerering finns i Serialisera uppräkningsfält som strängar.

Konfigurera ordningen för serialiserade egenskaper

Som standard serialiseras egenskaperna i den ordning de definieras i sin klass. Med [JsonPropertyOrder] attributet kan du ange ordningen på egenskaperna i JSON-utdata från serialiseringen. Standardvärdet för Order egenskapen är noll. Ange Order ett positivt tal för att placera en egenskap efter de som har standardvärdet. En negativ Order positionerar en egenskap före de som har standardvärdet. Egenskaperna skrivs i ordning från det lägsta Order värdet till det högsta. Här är ett exempel:

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

Använda Github Copilot för att anpassa egenskapsnamn och ordning

Du kan använda GitHub Copilot i din IDE för att generera kod för att anpassa namn och ordning på serialiserade egenskaper.

Om du använder Visual Studio 2022 version 17.8 eller senare kan du prova den AI-drivna GitHub Copilot i Visual Studio för att generera kod som använder System.Text.Json för att anpassa egenskapsnamn och ordning i JSON-utdata från serialisering. Skicka din fråga som en uppmaning i Chattfönstret för Copilot, som i följande exempel. Du kan också skicka frågor med hjälp av infogad chatt i själva redigeringsfönstret.

Kommentar

GitHub Copilot drivs av AI, så överraskningar och misstag är möjliga. Kontrollera eventuell genererad kod eller förslag. Mer information om allmän användning av GitHub Copilot, produktpåverkan, mänsklig tillsyn och sekretess finns i Vanliga frågor och svar om GitHub Copilot.

I följande exempel visas hur du använder Copilot för att ändra befintlig kod för att anpassa egenskapsnamn och ordning vid serialisering till JSON.

Lägg till följande C#-exempelkod i en kodfil Example.cs i redigeringsprogrammet. I Visual Studio kan du använda ett C#-konsolprogramprojekt för att prova det här exemplet.

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 koden gör följande:

Skapar en instans av Person klassen och initierar dess egenskaper med värden.
Serialiserar objektet person till en JSON-sträng med .JsonSerializer.Serialize
Skriver ut följande JSON-sträng till konsolen:

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

I Copilot Chat anger du följande uppmaning om att ändra koden för att anpassa namn och ordning på JSON-serialiseringsutdata.

#Example.cs ändra kod som ska användas System.Text.Json för att anpassa egenskapsnamn och ordning för JSON-utdata från serialisering. Ange egenskapsnamn: FirstName till first_name, LastName till last_name. Ange ordning till: Country, FirstName, LastName, Age. Ange anpassade serialiseringsutdata.

#Example.cs i prompten finns en filreferens som kontext till Copilot. Du kan anpassa uppmaningen för att mata ut en JSON-sträng med egenskapsnamn och värden som passar dina behov. Om du vill ange avsikt och få bättre svar med begränsad kontext kan du använda chattfunktioner som snedstreckskommandon, referenser till filer, metoder eller klasser och trådar.

Följande utdata visar ett exempel på Copilot Chat-svar:

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.

När Copilot returnerar ett kodblock innehåller svaret alternativ för att kopiera koden, infoga koden i en ny fil eller förhandsgranska kodutdata.

Kommentar

Dina resultat kan skilja sig från vad som visas i exempelsvaren. AI-modeller är icke-deterministiska, vilket innebär att de kan returnera olika svar när de får samma fråga. Detta kan bero på ytterligare inlärning och anpassning över tid, språkvariationer, ändringar i kontexten, till exempel din chatthistorik med mera.

Dela via

Så här anpassar du egenskapsnamn och värden med System.Text.Json

Anpassa enskilda egenskapsnamn

Använda en inbyggd namngivningsprincip

Använda en anpassad namngivningsprincip för JSON-egenskaper

Använda en namngivningsprincip för ordlistenycklar

Räkna upp som strängar

JsonConverterAttribute

Anpassade uppräkningsmedlemsnamn

Källgenerering

Konfigurera ordningen för serialiserade egenskaper

Använda Github Copilot för att anpassa egenskapsnamn och ordning

Se även

Ytterligare resurser