Come personalizzare nomi e valori delle proprietà con System.Text.Json

Per impostazione predefinita, i nomi delle proprietà e le chiavi del dizionario rimangono invariati nell'output JSON, incluso il case. I valori di enumerazione sono rappresentati come numeri e le proprietà vengono serializzate nell'ordine in cui sono definite. È tuttavia possibile personalizzare tale comportamento utilizzando uno dei seguenti metodi:

• Specifica di nomi specifici di proprietà serializzate e membri enumerazione.
• Uso di un criterio di denominazione predefinito, ad esempio camelCase, snake_case o kebab-case, per i nomi delle proprietà e le chiavi del dizionario.
• Uso di un criterio di denominazione personalizzato per i nomi delle proprietà e le chiavi del dizionario.
• Serializzazione dei valori di enumerazione come stringhe, con o senza criteri di denominazione.
• Configurazione dell'ordine delle proprietà serializzate.

Per altri scenari che richiedono una gestione speciale dei nomi e dei valori delle proprietà JSON, è possibile implementare convertitori personalizzati.

Personalizzare i nomi delle singole proprietà

Per impostare il nome delle singole proprietà, usare l'attributo [JsonPropertyName].

Di seguito è riportato un tipo di esempio per serializzare e ottenere il JSON risultante:

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
}

Il nome della proprietà impostato da questo attributo:

• Si applica in entrambe le direzioni, per la serializzazione e la deserializzazione.
• Ha la precedenza sui criteri di denominazione delle proprietà.
• Non influisce sulla corrispondenza dei nomi dei parametri per i costruttori con parametri.

Usare un criterio di denominazione predefinito

La tabella seguente illustra i criteri di denominazione predefiniti e il modo in cui influiscono sui nomi delle proprietà.

* Disponibile in .NET 8 e versioni successive.

L'esempio seguente illustra come usare il case camel per tutti i nomi di proprietà JSON impostando JsonSerializerOptions.PropertyNamingPolicy su 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)

Ecco una classe di esempio per serializzare e l'output 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
}

Il criterio di denominazione:

• Si applica alla serializzazione e deserializzazione.
• Viene sottoposto a override dagli attributi [JsonPropertyName]. Questo è il motivo per cui il nome della proprietà JSON Wind riportato nell'esempio non è case camel.

Usare un criterio di denominazione delle proprietà JSON personalizzato

Per usare un criterio di denominazione delle proprietà JSON personalizzato, creare una classe che deriva da JsonNamingPolicy ed eseguirne l'override del metodo ConvertName, come illustrato nell'esempio seguente:

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

Impostare quindi la proprietà JsonSerializerOptions.PropertyNamingPolicy su un'istanza della classe dei criteri di denominazione:

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)

Ecco una classe di esempio per serializzare e l'output 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
}

Il criterio di denominazione delle proprietà JSON:

• Si applica alla serializzazione e deserializzazione.
• Viene sottoposto a override dagli attributi [JsonPropertyName]. Questo è il motivo per cui il nome della proprietà JSON Wind riportato nell'esempio non è scritto in maiuscolo.

Usare un criterio di denominazione per le chiavi del dizionario

Se una proprietà di un oggetto da serializzare è di tipo Dictionary<string,TValue>, le chiavi string possono essere convertite usando criteri di denominazione, ad esempio camel case. A tale scopo, impostare JsonSerializerOptions.DictionaryKeyPolicy sui criteri di denominazione desiderati. L'esempio seguente usa il criterio di denominazione CamelCase:

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)

Serializzare un oggetto con un dizionario denominato TemperatureRanges con coppie chiave-valore "ColdMinTemp", 20 e "HotMinTemp", 40 produrrebbe un output JSON simile all'esempio seguente:

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

I criteri di denominazione per le chiavi del dizionario si applicano solo alla serializzazione. Se si deserializza un dizionario, le chiavi corrisponderanno al file JSON anche se si imposta JsonSerializerOptions.DictionaryKeyPolicy su un criterio di denominazione non predefinito.

Enumerazioni come stringhe

Le enumerazioni vengono serializzate come numeri per impostazione predefinita. Per serializzare i nomi delle enumerazioni come stringhe, usare il convertitoreJsonStringEnumConverter o JsonStringEnumConverter<TEnum>. Solo JsonStringEnumConverter<TEnum> è supportato dal runtime AOT nativo.

Si supponga, ad esempio, di dover serializzare la classe seguente che possiede un'enumerazione:

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

Se riepilogo è Hot, per impostazione predefinita il codice JSON serializzato ha il valore numerico 3:

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

Il codice di esempio seguente serializza i nomi delle enumerazioni anziché i valori numerici e converte i nomi in case camel:

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)

Il codice JSON risultante è simile al seguente esempio:

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

Il valore predefinito JsonStringEnumConverter può deserializzare anche i valori stringa. Funziona con o senza un criterio di denominazione specificato. Nell'esempio seguente viene illustrata la deserializzazione usando 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

È anche possibile specificare il convertitore da usare annotando l'enumerazione con JsonConverterAttribute. Nell'esempio seguente viene illustrato come specificare JsonStringEnumConverter<TEnum> (disponibile in .NET 8 e versioni successive) usando l'attributo JsonConverterAttribute. Si supponga, ad esempio, di dover serializzare la classe seguente che possiede un'enumerazione:

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
}

Il codice seguente serializza i nomi delle enumerazioni anziché i valori numerici:

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

Il codice JSON risultante ha l'aspetto seguente:

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

Nomi di membri enumerazione personalizzati

A partire da .NET 9, è possibile personalizzare i nomi dei singoli membri enumerazione per i tipi serializzati come stringhe. Per personalizzare un nome di membro enum, annotarlo con l'attributo JsonStringEnumMemberName.

Si supponga, ad esempio, di dover serializzare la classe seguente con un'enumerazione con un nome di membro personalizzato:

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
}

Il codice seguente serializza i nomi delle enumerazioni anziché i valori numerici:

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

Il codice JSON risultante ha l'aspetto seguente:

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

Generazione di origine

Per usare il convertitore con la generazione di origine, consultare la sezione Serializzare i campi enumerazione come stringhe.

Configurare l'ordine delle proprietà serializzate

Per impostazione predefinita, le proprietà vengono serializzate nell'ordine in cui sono definite nella classe di appartenenza. L'attributo [JsonPropertyOrder] consente di specificare l'ordine delle proprietà nell'output JSON dalla serializzazione. Il valore predefinito della proprietà Order è zero. Impostare Order su un numero positivo per posizionare una proprietà dopo quelle con il valore predefinito. Una proprietà negativa Order posiziona una proprietà prima di quelle con il valore predefinito. Le proprietà vengono scritte in ordine dal valore Order più basso al più alto. Ecco un esempio:

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

Usare Github Copilot per personalizzare i nomi delle proprietà e l'ordine

È possibile usare GitHub Copilot nell'IDE per generare codice per personalizzare i nomi e l'ordine delle proprietà serializzate.

Se si usa Visual Studio 2022 versione 17.8 o successiva, è possibile provare GitHub Copilot basato sull'intelligenza artificiale in Visual Studio per generare codice che usa System.Text.Json per personalizzare i nomi delle proprietà e l'ordine nell'output JSON dalla serializzazione. Inviare la domanda e il codice da convertire come richiesta nella finestra di chat Copilot, come nell'esempio seguente. È anche possibile inviare richieste usando chat inline nella finestra dell'editor stessa.

L'esempio seguente illustra come usare Copilot per modificare il codice esistente per personalizzare i nomi delle proprietà e l'ordine durante la serializzazione in JSON.

1. Aggiungere il codice di esempio C# seguente a un file Example.cs di codice nell'editor. In Visual Studio è possibile usare un progetto di applicazione console C# per provare questo esempio.

   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 Il codice effettua quanto segue:

   • Crea un'istanza della Person classe e ne inizializza le proprietà con i valori .
   • Serializza l'oggetto person in una stringa JSON usando JsonSerializer.Serialize.
   • Stampa la stringa JSON seguente nella console:

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

2. In Copilot Chat immettere il prompt seguente per modificare il codice per personalizzare i nomi e l'ordine dell'output di serializzazione JSON.

   #Example.cs modificare il codice da usare System.Text.Json per personalizzare i nomi delle proprietà e l'ordine di output JSON dalla serializzazione. Impostare i nomi delle proprietà: FirstName su first_name, LastName su last_name. Impostare l'ordine su: Country, FirstName, LastName, Age. Fornire un output di serializzazione personalizzato.

   #Example.cs nel prompt fornisce un riferimento al file come contesto per Copilot. È possibile personalizzare il prompt per generare una stringa JSON con nomi di proprietà e valori adatti alle proprie esigenze. Per impostare l'intento e ottenere risposte migliori con un contesto definito, puoi utilizzare funzionalità di chat come comandi barra, riferimenti a file, metodi, classi o thread, per impostare la finalità e ottenere risposte migliori con il contesto con ambito.

   L'output seguente mostra un esempio di risposta Copilot Chat:

   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.
   

Quando Copilot restituisce un blocco di codice, la risposta include opzioni per copiare il codice, inserire il codice in un nuovo file o visualizzare in anteprima l'output del codice.

Vedi anche

• Panoramica di System.Text.Json
• Come serializzare e deserializzare dati JSON
• Centro protezione di GitHub Copilot
• GitHub Copilot in Visual Studio
• GitHub Copilot in VS Code