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

Som standard förblir egenskapsnamn och ordlistnycklar oförändrade 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 namn för serialiserade egenskaper och enum-medlemmar.
• Genom att använda en inbyggd namngivningspolicy så som camelCase, snake_case eller kebab-case för egenskapsnamn och uppslagsord.
• 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.

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.

* 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 camel case.

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

Ställ sedan in JsonSerializerOptions.PropertyNamingPolicy-egenskapen till en instans av din klass för namngivningspolicy.

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 skrivet med versaler.

Använd en namnpolicy för ordboksnycklar

Om en egenskap för ett objekt som ska serialiseras är av typen Dictionary<string,TValue>, kan string-nycklarna konverteras med hjälp av en namngivningsprincip, till exempel camelCase. Det gör du genom att ange JsonSerializerOptions.DictionaryKeyPolicy till ö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 standardinställning serialiseras uppräkningar som tal. För att serialisera uppräkningsnamn som strängar, använd JsonStringEnumConverter eller JsonStringEnumConverter<TEnum> konverterare. Endast JsonStringEnumConverter<TEnum> stöds av Native AOT-runtime.

Anta till exempel att du behöver serialisera följande klass som har en 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
}

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 kodexempel serialiserar uppräkningsnamnen snarare än de numeriska värdena och konverterar namnen till camelCase.

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 av det JsonConverterAttribute-attributet. Anta till exempel att du behöver serialisera följande klass som har en enum:

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 enum-medlemsnamn

Från och med .NET 9 kan du anpassa namnen på enskilda enummedlemmar för typer som serialiseras som strängar. För att anpassa ett uppräkningsmedlemsnamn markerar du det med attributet JsonStringEnumMemberName.

Tänk dig till exempel att du behöver serialisera följande klass, som har en enum-typ med ett anpassat elementnamn.

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 AI för att anpassa hur egenskapsnamn serialiseras

Du kan använda AI-verktyg, till exempel GitHub Copilot, för att tillämpa mönster för ändringar i hur koden serialiseras.

Anta att klassdeklarationen har egenskaper som följer PascalCasingoch att JSON-standarden för projektet är snake_casing. Du kan använda AI för att lägga till de nödvändiga attributen [JsonPropertyName] i varje egenskap i klassen. Du kan använda Copilot för att göra dessa ändringar med en chattfråga som den här:

Update #ClassName:
when the property name contains more than one word,
change the serialized property name to use underscores between words.
Use built-in serialization attributes.

Här är en mer fullständig version av exemplet som innehåller en enkel klass.

Take this C# class:
public class WeatherForecast
{
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public int TemperatureF { get; set; }
    public string? Summary { get; set; }
    public int WindSpeed { get; set; }
}
When the property name contains more than one word,
change the serialized property name to use underscores between words.
Use built-in serialization attributes.

Granska Copilots förslag innan du tillämpar dem.

Mer information om GitHub Copilot finns i Vanliga frågor och svar om GitHub.

Se även

• System.Text.Json överblick
• Serialisera och deserialisera JSON
• GitHub Copilot i Visual Studio
• GitHub Copilot i VS Code