Como ignorar propriedades com System.Text.Json

Ao serializar objetos C# para JSON (JavaScript Object Notation), por padrão, todas as propriedades públicas são serializadas. Se você não quiser que alguns deles apareçam no JSON resultante, você terá várias opções. Neste artigo, você aprenderá a ignorar propriedades com base em vários critérios:

Propriedades individuais
Propriedades baseadas em uma condição no nível do tipo
Todas as propriedades somente leitura
Todas as propriedades de valor nulo
Todas as propriedades de valor padrão

Ignorar propriedades individuais

Para ignorar propriedades individuais, use o atributo [JsonIgnore] .

O exemplo a seguir mostra um tipo para serializar. Ele também mostra a saída 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,
}

Você pode especificar a exclusão condicional definindo a propriedade do atributo Condition. A JsonIgnoreCondition enumeração fornece as seguintes opções:

Always - A propriedade é sempre ignorada. Se nenhum Condition for especificado, essa opção será presumida.
Never - A propriedade é sempre serializada e desserializada, independentemente das configurações globais de DefaultIgnoreCondition, IgnoreReadOnlyProperties e IgnoreReadOnlyFields.
WhenWritingDefault - A propriedade será ignorada na serialização se for um tipo nullde referência, um tipo nullde valor anulável ou um tipo defaultde valor.
WhenWritingNull - A propriedade será ignorada na serialização se for um tipo nullde referência ou um tipo nullde valor anulável.

O exemplo a seguir ilustra o uso da propriedade do atributo Condition:

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}

Ignorar propriedades com base em uma condição de nível de tipo

A partir do .NET 11, aplique [JsonIgnore(Condition = ...)] a uma classe, estrutura ou interface para definir a condição padrão de ignorar para suas propriedades e campos:

[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

O serializador aplica configurações de ignorar nesta ordem, da precedência mais alta à mais baixa:

Um nível de membro JsonIgnoreAttribute.
Um nível de tipo JsonIgnoreAttribute.
JsonSerializerOptions.DefaultIgnoreCondition.

No nível do tipo, Always é inválido. A serialização baseada em reflexão gera um InvalidOperationException, e a geração de código-fonte relata SYSLIB1226. Como Always é a condição padrão, especifique Condition quando aplicar [JsonIgnore] a um tipo.

Uma condição no nível do tipo WhenWritingNull não ignora membros de tipo de valor não anulável. A condição de nível de tipo ainda substitui o global DefaultIgnoreCondition, portanto, esses membros permanecem no JSON mesmo quando a condição global é WhenWritingDefault.

Ignorar todas as propriedades somente leitura

Uma propriedade é somente leitura se tiver um método get público, mas não um método set público. Para ignorar todas as propriedades somente de leitura ao serializar, defina JsonSerializerOptions.IgnoreReadOnlyProperties como true, conforme mostrado no exemplo a seguir:

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)

O exemplo a seguir mostra um tipo para serializar. Ele também mostra a saída 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",
}

Essa opção se aplica apenas às propriedades. Para ignorar campos somente leitura ao serializar campos, use a configuração JsonSerializerOptions.IgnoreReadOnlyFields global.

Observação

As propriedades do tipo de coleção somente leitura continuam sendo serializadas, mesmo se JsonSerializerOptions.IgnoreReadOnlyProperties estiver definido como true.

Ignorar todas as propriedades de valor nulo

Para ignorar todas as propriedades de valor nulo, defina a DefaultIgnoreCondition propriedade como WhenWritingNull, conforme mostrado no exemplo a seguir:

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}

Ignorar todas as propriedades com valor padrão

Para impedir a serialização de valores padrão em propriedades de tipo de valor, defina a DefaultIgnoreCondition propriedade como WhenWritingDefault, conforme mostrado no exemplo a seguir:

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

A configuração WhenWritingDefault também impede a serialização de propriedades de tipo de referência com valor nulo e de propriedades de tipo de valor anulável.

Consulte também

visão geral System.Text.Json
Como serializar e desserializar JSON

Comentários

Esta página foi útil?

Última atualização em 2026-09-29