Personalización de los nombres y valores de propiedades con System.Text.Json

  • Artículo
  • 2 minutos para leer

De forma predeterminada, los nombres de propiedad y las claves de diccionario no se modifican en la salida JSON, ni siquiera el uso de mayúsculas y minúsculas. Los valores de enumeración se representan como números. En este artículo, aprenderá a:

Nota

Los valores predeterminados web son mayúsculas y minúsculas Camel.

En el caso de otros escenarios que requieran un tratamiento especial de los nombres y valores de propiedades JSON, puede implementar convertidores personalizados.

Personalizar nombres de propiedades individuales

Para establecer el nombre de propiedades individuales, use el atributo [JsonPropertyName].

Aquí se muestra un tipo de ejemplo que se serializa y el JSON resultante:

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

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

Nombre de propiedad establecido por este atributo:

  • Se aplica en ambas direcciones, para la serialización y la deserialización.
  • Tiene prioridad sobre las directivas de nomenclatura de propiedades.

Uso de mayúsculas y minúsculas combinadas Camel en todos los nombres de propiedad JSON

Para usar palabras con mayúsculas y minúsculas combinadas Camel en todos los nombres de propiedad JSON, establezca JsonSerializerOptions.PropertyNamingPolicy en JsonNamingPolicy.CamelCase, tal y como se muestra en el ejemplo siguiente:

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

Aquí se muestra una clase de ejemplo que se serializa y la salida JSON:

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

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

La directiva de nomenclatura de propiedades en mayúsculas y minúsculas combinadas Camel:

  • Se aplica a la serialización y deserialización.
  • Se invalida con atributos [JsonPropertyName]. Este es el motivo por el que el nombre de la propiedad JSON Wind del ejemplo no usa mayúsculas y minúsculas combinadas Camel.

Uso de una directiva de nomenclatura de propiedades JSON personalizada

Para usar una directiva de nomenclatura de propiedades JSON personalizada, cree una clase que derive de JsonNamingPolicy e invalide el método ConvertName, tal y como se muestra en el ejemplo siguiente:

using System.Text.Json;

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

Establezca luego la propiedad JsonSerializerOptions.PropertyNamingPolicy en una instancia de la clase de directiva de nomenclatura:

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

Aquí se muestra una clase de ejemplo que se serializa y la salida JSON:

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

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

La directiva de nomenclatura de propiedades JSON personalizada:

  • Se aplica a la serialización y la deserialización.
  • Se invalida con atributos [JsonPropertyName]. Este es el motivo por el que el nombre de la propiedad JSON Wind del ejemplo no usa mayúsculas.

Claves de diccionario en mayúsculas y minúsculas combinadas Camel

Si una propiedad de un objeto que se va a serializar es de tipo Dictionary<string,TValue>, se pueden convertir las claves string en mayúsculas y minúsculas combinadas Camel. Para ello, establezca DictionaryKeyPolicy en JsonNamingPolicy.CamelCase, tal y como se muestra en el ejemplo siguiente:

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

La serialización de un objeto con un diccionario denominado TemperatureRanges que tenga pares clave-valor "ColdMinTemp", 20 y "HotMinTemp", 40 se traduciría en una salida JSON similar a la del ejemplo siguiente:

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

La directiva de nomenclatura en mayúsculas y minúsculas combinadas Camel para las claves de diccionario se aplica solo a la serialización. Si se deserializa un diccionario, las claves coincidirán con el archivo JSON aunque se especifique JsonNamingPolicy.CamelCase para DictionaryKeyPolicy.

Enumeraciones como cadenas

De forma predeterminada, las enumeraciones se serializan como números. Para serializar nombres de enumeración como cadenas, use JsonStringEnumConverter.

Por ejemplo, supongamos que hay que serializar la siguiente clase que tiene una enumeración:

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
}

Si el resumen es Hot, el JSON serializado tiene el valor numérico 3 de forma predeterminada:

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

En el código de ejemplo siguiente se serializan los nombres de enumeración en lugar de los valores numéricos y los nombres se convierten en mayúsculas y minúsculas combinadas Camel:

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

El JSON resultante tendrá un aspecto similar al siguiente:

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

Los nombres de cadena de enumeración también se pueden deserializar, tal y como se muestra en el ejemplo siguiente:

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

Vea también