Langue
Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Lors de la sérialisation d’objets C# en JavaScript Object Notation (JSON), par défaut, toutes les propriétés publiques sont sérialisées. Si vous ne souhaitez pas que certains d’entre eux apparaissent dans le JSON résultant, vous avez plusieurs options. Dans cet article, vous allez apprendre à ignorer les propriétés en fonction de différents critères :
- Propriétés individuelles
- Propriétés basées sur une condition de niveau type
- Toutes les propriétés en lecture seule
- Toutes les propriétés avec une valeur nulle
- Toutes les propriétés par défaut
Ignorer les propriétés individuelles
Pour ignorer les propriétés individuelles, utilisez l’attribut [JsonIgnore].
L’exemple suivant montre un type à sérialiser. Il affiche également la sortie JSON :
public class WeatherForecastWithIgnoreAttribute
{
public DateTimeOffset Date { get; set; }
public int TemperatureCelsius { get; set; }
[JsonIgnore]
public string? Summary { get; set; }
}
Public Class WeatherForecastWithIgnoreAttribute
Public Property [Date] As DateTimeOffset
Public Property TemperatureCelsius As Integer
<JsonIgnore>
Public Property Summary As String
End Class
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
}
Vous pouvez spécifier l’exclusion conditionnelle en définissant la propriété de l’attribut Condition L’énumération JsonIgnoreCondition fournit les options suivantes :
-
Always- La propriété est toujours ignorée. Si aucune valeur n’estConditionspécifiée, cette option est supposée. -
Never- La propriété est toujours sérialisée et désérialisée, quels que soient les paramètres globauxDefaultIgnoreCondition,IgnoreReadOnlyProperties, etIgnoreReadOnlyFields. -
WhenWritingDefault- La propriété est ignorée lors de la sérialisation s’il s’agit d’un type référencenull, d’un type valeur nullablenull, ou d’un type valeurdefault. -
WhenWritingNull- La propriété est ignorée lors de la sérialisation s’il s’agit d’un typenullréférence ou d’un typenullvaleur nullable.
L’exemple suivant illustre l’utilisation de la propriété de l’attribut [JsonIgnore] :
using System.Text.Json;
using System.Text.Json.Serialization;
namespace JsonIgnoreAttributeExample
{
public class Forecast
{
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public DateTime Date { get; set; }
[JsonIgnore(Condition = JsonIgnoreCondition.Never)]
public int TemperatureC { get; set; }
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? Summary { get; set; }
};
public class Program
{
public static void Run()
{
Forecast forecast = new()
{
Date = default,
Summary = null,
TemperatureC = default
};
JsonSerializerOptions options = new()
{
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
};
string forecastJson =
JsonSerializer.Serialize<Forecast>(forecast,options);
Console.WriteLine(forecastJson);
}
}
}
// Produces output like the following example:
//
//{"TemperatureC":0}
Imports System.Text.Json
Imports System.Text.Json.Serialization
Namespace JsonIgnoreAttributeExample
Public Class Forecast
<JsonIgnore(Condition:=JsonIgnoreCondition.WhenWritingDefault)>
Public Property [Date] As Date
<JsonIgnore(Condition:=JsonIgnoreCondition.Never)>
Public Property TemperatureC As Integer
<JsonIgnore(Condition:=JsonIgnoreCondition.WhenWritingNull)>
Public Property Summary As String
End Class
Public NotInheritable Class Program
Public Shared Sub Main()
Dim forecast1 As New Forecast() With {
.[Date] = CType(Nothing, Date),
.Summary = Nothing,
.TemperatureC = CType(Nothing, Integer)
}
Dim options As New JsonSerializerOptions() With {
.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
}
Dim forecastJson As String = JsonSerializer.Serialize(forecast1, options)
Console.WriteLine(forecastJson)
End Sub
End Class
End Namespace
' Produces output like the following example:
'
'{"TemperatureC":0}
Ignorer les propriétés en fonction d’une condition au niveau du type
À partir de .NET 11, appliquez [JsonIgnore(Condition = ...)] à une classe, une structure ou une interface pour définir la condition d’ignorance par défaut de ses propriétés et de ses champs :
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public class Forecast
{
public string? Summary { get; set; }
}
<JsonIgnore(Condition:=JsonIgnoreCondition.WhenWritingNull)>
Public Class Forecast
Public Property Summary As String
End Class
Le sérialiseur applique les paramètres d’ignorance dans cet ordre, de la priorité la plus élevée à la plus faible :
- Au niveau du membre JsonIgnoreAttribute.
- De niveau type JsonIgnoreAttribute.
- JsonSerializerOptions.DefaultIgnoreCondition.
Au niveau du type, Always n’est pas valide. La sérialisation basée sur la réflexion lève InvalidOperationException, et la génération de source signale SYSLIB1226. Étant donné que Always est la condition par défaut, spécifiez Condition lorsque vous appliquez [JsonIgnore] à un type.
Une condition au niveau du type WhenWritingNull n’ignore pas les membres de type valeur non nullable. La condition au niveau du type remplace toujours la condition globale DefaultIgnoreCondition, de sorte que ces membres restent dans le JSON même lorsque la condition globale est WhenWritingDefault.
Ignorer toutes les propriétés en lecture seule
Une propriété est en lecture seule si elle contient un getter public, mais pas un setter public. Pour ignorer toutes les propriétés en lecture seule lors de la sérialisation, définissez JsonSerializerOptions.IgnoreReadOnlyProperties sur true, comme indiqué dans l’exemple suivant :
var options = new JsonSerializerOptions
{
IgnoreReadOnlyProperties = true,
WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
.IgnoreReadOnlyProperties = True,
.WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)
L’exemple suivant montre un type à sérialiser. Il affiche également la sortie JSON :
public class WeatherForecastWithROProperty
{
public DateTimeOffset Date { get; set; }
public int TemperatureCelsius { get; set; }
public string? Summary { get; set; }
public int WindSpeedReadOnly { get; private set; } = 35;
}
Public Class WeatherForecastWithROProperty
Public Property [Date] As DateTimeOffset
Public Property TemperatureCelsius As Integer
Public Property Summary As String
Private _windSpeedReadOnly As Integer
Public Property WindSpeedReadOnly As Integer
Get
Return _windSpeedReadOnly
End Get
Private Set(Value As Integer)
_windSpeedReadOnly = Value
End Set
End Property
End Class
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "Hot",
}
Cette option s’applique uniquement aux propriétés. Pour ignorer les champs en lecture seule lors de la sérialisation des champs, utilisez le JsonSerializerOptions.IgnoreReadOnlyFields paramètre global.
Remarque
Les propriétés de type collection en lecture seule sont toujours sérialisées même si JsonSerializerOptions.IgnoreReadOnlyProperties est défini sur true.
Ignorer toutes les propriétés de valeur nulle
Pour ignorer toutes les propriétés à valeur null, définissez la propriété DefaultIgnoreCondition sur WhenWritingNull, comme indiqué dans l’exemple suivant :
using System.Text.Json;
using System.Text.Json.Serialization;
namespace IgnoreNullOnSerialize
{
public class Forecast
{
public DateTime Date { get; set; }
public int TemperatureC { get; set; }
public string? Summary { get; set; }
};
public class Program
{
public static void Run()
{
Forecast forecast = new()
{
Date = DateTime.Now,
Summary = null,
TemperatureC = default
};
JsonSerializerOptions options = new()
{
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
string forecastJson =
JsonSerializer.Serialize<Forecast>(forecast, options);
Console.WriteLine(forecastJson);
}
}
}
// Produces output like the following example:
//
//{"Date":"2020-10-30T10:11:40.2359135-07:00","TemperatureC":0}
Imports System.Text.Json
Namespace IgnoreNullOnSerialize
Public Class Forecast
Public Property [Date] As Date
Public Property TemperatureC As Integer
Public Property Summary As String
End Class
Public NotInheritable Class Program
Public Shared Sub Main()
Dim forecast1 As New Forecast() With
{
.[Date] = Date.Now,
.Summary = Nothing,
.TemperatureC = CType(Nothing, Integer)
}
Dim options As New JsonSerializerOptions
Dim forecastJson As String = JsonSerializer.Serialize(forecast1, options)
Console.WriteLine(forecastJson)
End Sub
End Class
End Namespace
' Produces output like the following example:
'
'{"Date":"2020-10-30T10:11:40.2359135-07:00","TemperatureC":0}
Ignorer toutes les propriétés par défaut
Pour empêcher la sérialisation des valeurs par défaut dans les propriétés de type valeur, définissez la propriété DefaultIgnoreCondition sur WhenWritingDefault, comme indiqué dans l’exemple suivant :
using System.Text.Json;
using System.Text.Json.Serialization;
namespace IgnoreValueDefaultOnSerialize
{
public class Forecast
{
public DateTime Date { get; set; }
public int TemperatureC { get; set; }
public string? Summary { get; set; }
};
public class Program
{
public static void Run()
{
Forecast forecast = new()
{
Date = DateTime.Now,
Summary = null,
TemperatureC = default
};
JsonSerializerOptions options = new()
{
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
};
string forecastJson =
JsonSerializer.Serialize<Forecast>(forecast, options);
Console.WriteLine(forecastJson);
}
}
}
// Produces output like the following example:
//
//{ "Date":"2020-10-21T15:40:06.8920138-07:00"}
Imports System.Text.Json
Imports System.Text.Json.Serialization
Namespace IgnoreValueDefaultOnSerialize
Public Class Forecast
Public Property [Date] As Date
Public Property TemperatureC As Integer
Public Property Summary As String
End Class
Public NotInheritable Class Program
Public Shared Sub Main()
Dim forecast1 As New Forecast() With
{.[Date] = Date.Now,
.Summary = Nothing,
.TemperatureC = CType(Nothing, Integer)
}
Dim options As New JsonSerializerOptions() With {
.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
}
Dim forecastJson As String = JsonSerializer.Serialize(forecast1, options)
Console.WriteLine(forecastJson)
End Sub
End Class
End Namespace
' Produces output like the following example:
'
'{ "Date":"2020-10-21T15:40:06.8920138-07:00"}
Le WhenWritingDefault paramètre empêche également la sérialisation du type référence null-valeur et des propriétés de type valeur nullable.
Voir aussi
- vue d’ensemble System.Text.Json
- Comment sérialiser et désérialiser le JSON