Ignorieren von Eigenschaften mit System.Text.Json

Beim Serialisieren von C#-Objekten in JavaScript Object Notation (JSON) werden standardmäßig alle öffentlichen Eigenschaften serialisiert. Wenn einige davon nicht im resultierenden JSON angezeigt werden sollen, haben Sie mehrere Optionen. In diesem Artikel erfahren Sie, wie Sie Eigenschaften basierend auf verschiedenen Kriterien ignorieren:

Einzelne Eigenschaften
Eigenschaften basierend auf einer Bedingung auf Typebene
Alle schreibgeschützten Eigenschaften
Alle Nullwerteigenschaften
Alle Standardwerteigenschaften

Einzelne Eigenschaften ignorieren

Verwenden Sie das Attribut [JsonIgnore], um einzelne Eigenschaften zu ignorieren.

Das folgende Beispiel zeigt einen Typ, der serialisiert werden soll. Außerdem wird die JSON-Ausgabe angezeigt:

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

Sie können bedingten Ausschluss angeben, indem Sie die Eigenschaft des [JsonIgnore] -Attributs Condition festlegen. Das JsonIgnoreCondition Enum bietet die folgenden Optionen:

Always: Die Eigenschaft wird stets ignoriert. Wenn keine Condition Angabe erfolgt, wird diese Option angenommen.
Never - Die Eigenschaft wird immer serialisiert und deserialisiert, unabhängig von den globalen DefaultIgnoreCondition, IgnoreReadOnlyProperties und IgnoreReadOnlyFields Einstellungen.
WhenWritingDefault - Die Eigenschaft wird bei der Serialisierung ignoriert, wenn es sich um einen Verweistyp null, einen Nullwerttyp nulloder einen Werttyp defaulthandelt.
WhenWritingNull - Die Eigenschaft wird bei der Serialisierung ignoriert, wenn es sich um einen Verweistyp nulloder einen Nullwerttyp nullhandelt.

Das folgende Beispiel veranschaulicht die Verwendung der Eigenschaft des [JsonIgnore]-Attributs 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}

Eigenschaften basierend auf einer Bedingung auf Typebene ignorieren

Ab .NET 11 wenden Sie [JsonIgnore(Condition = ...)] auf eine Klasse, Struktur oder Schnittstelle an, um die standardmäßige Ignorierbedingung für deren Eigenschaften und Felder festzulegen:

[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

Der Serialisierer wendet die Einstellungen zum Ignorieren in der folgenden Reihenfolge an, von der höchsten bis zur niedrigsten Priorität:

Eine Mitgliedsebene JsonIgnoreAttribute.
Eine Typebene JsonIgnoreAttribute.
JsonSerializerOptions.DefaultIgnoreCondition.

Auf Typebene Always ist ungültig. Die reflexionsbasierte Serialisierung löst ein InvalidOperationException aus, und die Quellgenerierung meldet SYSLIB1226. Da Always die Standardbedingung ist, geben Sie Condition an, wenn Sie [JsonIgnore] auf einen Typ anwenden.

Eine Bedingung auf Typebene WhenWritingNull ignoriert keine nicht NULL-fähigen Mitglieder von Werttypen. Die Bedingung auf Typebene überschreibt weiterhin die globale DefaultIgnoreConditionBedingung, sodass diese Member auch dann im JSON-Code verbleiben, wenn die globale Bedingung lautet WhenWritingDefault.

Alle schreibgeschützten Eigenschaften ignorieren

Eine Eigenschaft ist schreibgeschützt, wenn sie über einen öffentlichen Getter, aber nicht über einen öffentlichen Setter verfügt. Um alle schreibgeschützten Eigenschaften bei der Serialisierung zu ignorieren, legen Sie, wie im folgenden Beispiel gezeigt, JsonSerializerOptions.IgnoreReadOnlyProperties auf true fest:

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)

Das folgende Beispiel zeigt einen Typ, der serialisiert werden soll. Außerdem wird die JSON-Ausgabe angezeigt:

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

Diese Option gilt nur für Eigenschaften. Um schreibgeschützte Felder beim Serialisieren von Feldern zu ignorieren, verwenden Sie die globale Einstellung JsonSerializerOptions.IgnoreReadOnlyFields.

Hinweis

Schreibgeschützte Eigenschaften des Auflistungstyps werden weiterhin serialisiert, auch wenn JsonSerializerOptions.IgnoreReadOnlyProperties auf true festgelegt ist.

Alle Nullwerteigenschaften ignorieren

Wenn Sie alle Eigenschaften mit dem Wert null ignorieren möchten, legen Sie die Eigenschaft DefaultIgnoreCondition wie im folgenden Beispiel gezeigt auf WhenWritingNull fest:

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}

Alle Standardwerteigenschaften ignorieren

Um die Serialisierung von Standardwerten in Werttypeigenschaften zu verhindern, legen Sie die DefaultIgnoreCondition Eigenschaft auf WhenWritingDefault, wie im folgenden Beispiel gezeigt:

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

Die Einstellung WhenWritingDefault verhindert auch die Serialisierung von Eigenschaften von Referenztypen mit Nullwert und von Eigenschaften nullbarer Werttypen.

Siehe auch

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-09-29