How to use source generation in System.Text.Json

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

This article shows how to use the source generation features of System.Text.Json.

For information about how to use source generation in System.Text.Json, see the .NET 6 version of this article.

Use source generation defaults

To use source generation with all defaults (both modes, default options):

• Create a partial class that derives from JsonSerializerContext.
• Specify the type to serialize or deserialize by applying JsonSerializableAttribute to the context class.
• Call a JsonSerializer method that takes a JsonTypeInfo<T> instance. An alternative is to call a JsonSerializer method that takes a JsonSerializerContext instance.

By default, both source generation modes are used if you don't specify one. For information about how to specify the mode to use, see Specify source generation mode later in this article.

Here's the type that is used in the following examples:

public class WeatherForecast
{
    public DateTime Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

Here's the context class configured to do source generation for the preceding WeatherForecast class:

[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(WeatherForecast))]
internal partial class SourceGenerationContext : JsonSerializerContext
{
}

The types of WeatherForecast members don't need to be explicitly specified with [JsonSerializable] attributes. Members declared as object are an exception to this rule. The runtime type for a member declared as object needs to be specified. For example, suppose you have the following class:

public class WeatherForecast
{
    public object? Data { get; set; }
    public List<object>? DataList { get; set; }
}

And you know that at runtime it may have boolean and int objects:

WeatherForecast wf = new() { Data = true, DataList = new List<object> { true, 1 } };

Then boolean and int have to be declared as [JsonSerializable]:

[JsonSerializable(typeof(WeatherForecast))]
[JsonSerializable(typeof(bool))]
[JsonSerializable(typeof(int))]
public partial class WeatherForecastContext : JsonSerializerContext
{
}

To specify source generation for a collection, use [JsonSerializable] with the collection type. For example: [JsonSerializable(typeof(List<WeatherForecast))].

JsonSerializer methods that use source generation

The following examples call methods that serialize:

jsonString = JsonSerializer.Serialize(
    weatherForecast!, SourceGenerationContext.Default.WeatherForecast);

jsonString = JsonSerializer.Serialize(
    weatherForecast, typeof(WeatherForecast), SourceGenerationContext.Default);

The following examples call methods that deserialize:

weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
    jsonString, SourceGenerationContext.Default.WeatherForecast);

weatherForecast = JsonSerializer.Deserialize(
    jsonString, typeof(WeatherForecast), SourceGenerationContext.Default)
    as WeatherForecast;

In the preceding examples, the static Default property of the context type provides an instance of the context type with default options. The context instance provides a WeatherForecast property that returns a JsonTypeInfo<WeatherForecast> instance. You can specify a different name for this property by using the TypeInfoPropertyName property of the [JsonSerializable] attribute.

Complete program example

Here are the preceding examples in a complete program:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace BothModesNoOptions
{
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    [JsonSourceGenerationOptions(WriteIndented = true)]
    [JsonSerializable(typeof(WeatherForecast))]
    internal partial class SourceGenerationContext : JsonSerializerContext
    {
    }

    public class Program
    {
        public static void Main()
        {
            string jsonString =
 @"{
  ""Date"": ""2019-08-01T00:00:00"",
  ""TemperatureCelsius"": 25,
  ""Summary"": ""Hot""
}
";
            WeatherForecast? weatherForecast;

            weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
                jsonString, SourceGenerationContext.Default.WeatherForecast);
            Console.WriteLine($"Date={weatherForecast?.Date}");
            // output:
            //Date=8/1/2019 12:00:00 AM

            weatherForecast = JsonSerializer.Deserialize(
                jsonString, typeof(WeatherForecast), SourceGenerationContext.Default)
                as WeatherForecast;
            Console.WriteLine($"Date={weatherForecast?.Date}");
            // output:
            //Date=8/1/2019 12:00:00 AM

            jsonString = JsonSerializer.Serialize(
                weatherForecast!, SourceGenerationContext.Default.WeatherForecast);
            Console.WriteLine(jsonString);
            // output:
            //{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":"Hot"}

            jsonString = JsonSerializer.Serialize(
                weatherForecast, typeof(WeatherForecast), SourceGenerationContext.Default);
            Console.WriteLine(jsonString);
            // output:
            //{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":"Hot"}
        }
    }
}

Specify source generation mode

You can specify metadata collection mode or serialization optimization mode for an entire context, which may include multiple types. Or you can specify the mode for an individual type. If you do both, the mode specification for a type wins.

• For an entire context, use the JsonSourceGenerationOptionsAttribute.GenerationMode property.
• For an individual type, use the JsonSerializableAttribute.GenerationMode property.

Serialization optimization mode example

• For an entire context:

  [JsonSourceGenerationOptions(GenerationMode = JsonSourceGenerationMode.Serialization)]
  [JsonSerializable(typeof(WeatherForecast))]
  internal partial class SerializeOnlyContext : JsonSerializerContext
  {
  }
  

• For an individual type:

  [JsonSerializable(typeof(WeatherForecast), GenerationMode = JsonSourceGenerationMode.Serialization)]
  internal partial class SerializeOnlyWeatherForecastOnlyContext : JsonSerializerContext
  {
  }
  

• Complete program example

  using System.Text.Json;
  using System.Text.Json.Serialization;
  
  namespace SerializeOnlyNoOptions
  {
      public class WeatherForecast
      {
          public DateTime Date { get; set; }
          public int TemperatureCelsius { get; set; }
          public string? Summary { get; set; }
      }
  
      [JsonSourceGenerationOptions(GenerationMode = JsonSourceGenerationMode.Serialization)]
      [JsonSerializable(typeof(WeatherForecast))]
      internal partial class SerializeOnlyContext : JsonSerializerContext
      {
      }
      
      [JsonSerializable(typeof(WeatherForecast), GenerationMode = JsonSourceGenerationMode.Serialization)]
      internal partial class SerializeOnlyWeatherForecastOnlyContext : JsonSerializerContext
      {
      }
  
       public class Program
      {
          public static void Main()
          {
              string jsonString;
              WeatherForecast weatherForecast = new()
                  { Date = DateTime.Parse("2019-08-01"), TemperatureCelsius = 25, Summary = "Hot" };
  
              // Use context that selects Serialization mode only for WeatherForecast.
              jsonString = JsonSerializer.Serialize(weatherForecast,
                  SerializeOnlyWeatherForecastOnlyContext.Default.WeatherForecast);
              Console.WriteLine(jsonString);
              // output:
              //{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":"Hot"}
  
              // Use a context that selects Serialization mode.
              jsonString = JsonSerializer.Serialize(weatherForecast,
                  SerializeOnlyContext.Default.WeatherForecast);
              Console.WriteLine(jsonString);
              // output:
              //{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":"Hot"}
          }
      }
  }
  

Metadata collection mode example

• For an entire context:

  [JsonSourceGenerationOptions(GenerationMode = JsonSourceGenerationMode.Metadata)]
  [JsonSerializable(typeof(WeatherForecast))]
  internal partial class MetadataOnlyContext : JsonSerializerContext
  {
  }
  

  jsonString = JsonSerializer.Serialize(
      weatherForecast!, MetadataOnlyContext.Default.WeatherForecast);
  

  weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
      jsonString, MetadataOnlyContext.Default.WeatherForecast);
  

• For an individual type:

  [JsonSerializable(typeof(WeatherForecast), GenerationMode = JsonSourceGenerationMode.Metadata)]
  internal partial class MetadataOnlyWeatherForecastOnlyContext : JsonSerializerContext
  {
  }
  

  jsonString = JsonSerializer.Serialize(
      weatherForecast!,
      MetadataOnlyWeatherForecastOnlyContext.Default.WeatherForecast);
  

  weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
      jsonString, MetadataOnlyWeatherForecastOnlyContext.Default.WeatherForecast);
  

• Complete program example

  using System.Text.Json;
  using System.Text.Json.Serialization;
  
  namespace MetadataOnlyNoOptions
  {
      public class WeatherForecast
      {
          public DateTime Date { get; set; }
          public int TemperatureCelsius { get; set; }
          public string? Summary { get; set; }
      }
  
      [JsonSerializable(typeof(WeatherForecast), GenerationMode = JsonSourceGenerationMode.Metadata)]
      internal partial class MetadataOnlyWeatherForecastOnlyContext : JsonSerializerContext
      {
      }
  
      [JsonSourceGenerationOptions(GenerationMode = JsonSourceGenerationMode.Metadata)]
      [JsonSerializable(typeof(WeatherForecast))]
      internal partial class MetadataOnlyContext : JsonSerializerContext
      {
      }
  
      public class Program
      {
          public static void Main()
          {
              string jsonString =
   @"{
    ""Date"": ""2019-08-01T00:00:00"",
    ""TemperatureCelsius"": 25,
    ""Summary"": ""Hot""
  }
  ";
              WeatherForecast? weatherForecast;
  
              // Deserialize with context that selects metadata mode only for WeatherForecast only.
              weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
                  jsonString, MetadataOnlyWeatherForecastOnlyContext.Default.WeatherForecast);
              Console.WriteLine($"Date={weatherForecast?.Date}");
              // output:
              //Date=8/1/2019 12:00:00 AM
  
              // Serialize with context that selects metadata mode only for WeatherForecast only.
              jsonString = JsonSerializer.Serialize(
                  weatherForecast!,
                  MetadataOnlyWeatherForecastOnlyContext.Default.WeatherForecast);
              Console.WriteLine(jsonString);
              // output:
              //{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":"Hot"}
  
              // Deserialize with context that selects metadata mode only.
              weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
                  jsonString, MetadataOnlyContext.Default.WeatherForecast);
              Console.WriteLine($"Date={weatherForecast?.Date}");
              // output:
              //Date=8/1/2019 12:00:00 AM
  
              // Serialize with context that selects metadata mode only.
              jsonString = JsonSerializer.Serialize(
                  weatherForecast!, MetadataOnlyContext.Default.WeatherForecast);
              Console.WriteLine(jsonString);
              // output:
              //{"Date":"2019-08-01T00:00:00","TemperatureCelsius":0,"Summary":"Hot"}
          }
      }
  }
  

Specify options for serialization optimization mode

Use JsonSourceGenerationOptionsAttribute to specify options that are supported by serialization optimization mode. You can use these options without causing a fallback to JsonSerializer code. For example, WriteIndented and CamelCase are supported:

[JsonSourceGenerationOptions(
    WriteIndented = true,
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    GenerationMode = JsonSourceGenerationMode.Serialization)]
[JsonSerializable(typeof(WeatherForecast))]
internal partial class SerializationModeOptionsContext : JsonSerializerContext
{
}

When using JsonSourceGenerationOptionsAttribute to specify serialization options, call one of the following serialization methods:

• A JsonSerializer.Serialize method that takes a TypeInfo<TValue>. Pass it the Default.<TypeName> property of your context class:

  jsonString = JsonSerializer.Serialize(
      weatherForecast, SerializationModeOptionsContext.Default.WeatherForecast);
  

• A JsonSerializer.Serialize method that takes a context. Pass it the Default static property of your context class.

  jsonString = JsonSerializer.Serialize(
      weatherForecast, typeof(WeatherForecast), SerializationModeOptionsContext.Default);
  

If you call a method that lets you pass in your own instance of Utf8JsonWriter, the writer's Indented setting is honored instead of the JsonSourceGenerationOptionsAttribute.WriteIndented option.

If you create and use a context instance by calling the constructor that takes a JsonSerializerOptions instance, the supplied instance will be used instead of the options specified by JsonSourceGenerationOptionsAttribute.

Here are the preceding examples in a complete program:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace SerializeOnlyWithOptions
{
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    [JsonSourceGenerationOptions(
        WriteIndented = true,
        PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
        GenerationMode = JsonSourceGenerationMode.Serialization)]
    [JsonSerializable(typeof(WeatherForecast))]
    internal partial class SerializationModeOptionsContext : JsonSerializerContext
    {
    }
    public class Program
    {
        public static void Main()
        {
            string jsonString;
            WeatherForecast weatherForecast = new()
                { Date = DateTime.Parse("2019-08-01"), TemperatureCelsius = 25, Summary = "Hot" };

            // Serialize using TypeInfo<TValue> provided by the context
            // and options specified by [JsonSourceGenerationOptions].
            jsonString = JsonSerializer.Serialize(
                weatherForecast, SerializationModeOptionsContext.Default.WeatherForecast);
            Console.WriteLine(jsonString);
            // output:
            //{
            //  "date": "2019-08-01T00:00:00",
            //  "temperatureCelsius": 0,
            //  "summary": "Hot"
            //}

            // Serialize using Default context
            // and options specified by [JsonSourceGenerationOptions].
            jsonString = JsonSerializer.Serialize(
                weatherForecast, typeof(WeatherForecast), SerializationModeOptionsContext.Default);
            Console.WriteLine(jsonString);
            // output:
            //{
            //  "date": "2019-08-01T00:00:00",
            //  "temperatureCelsius": 0,
            //  "summary": "Hot"
            //}
        }
    }
}

Specify options by using JsonSerializerOptions

Some options of JsonSerializerOptions aren't supported by serialization optimization mode. Such options cause a fallback to the non-source-generated JsonSerializer code. For more information, see Serialization optimization.

To specify options by using JsonSerializerOptions:

• Create an instance of JsonSerializerOptions.
• Create an instance of your class that derives from JsonSerializerContext, and pass the JsonSerializerOptions instance to the constructor.
• Call serialization or deserialization methods of JsonSerializer that take a context instance or TypeInfo<TValue>.

Here's an example context class followed by serialization and deserialization example code:

[JsonSerializable(typeof(WeatherForecast))]
internal partial class OptionsExampleContext : JsonSerializerContext
{
}

jsonString = JsonSerializer.Serialize(
    weatherForecast,
    typeof(WeatherForecast),
    new OptionsExampleContext(
        new JsonSerializerOptions(JsonSerializerDefaults.Web)));

weatherForecast = JsonSerializer.Deserialize(
    jsonString, 
    typeof(WeatherForecast), 
    new OptionsExampleContext(
        new JsonSerializerOptions(JsonSerializerDefaults.Web)))
        as WeatherForecast;

Here are the preceding examples in a complete program:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace JsonSerializerOptionsExample
{
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    [JsonSerializable(typeof(WeatherForecast))]
    internal partial class OptionsExampleContext : JsonSerializerContext
    {
    }

    public class Program
    {
        public static void Main()
        {
            string jsonString =
 @"{
  ""date"": ""2019-08-01T00:00:00"",
  ""temperatureCelsius"": 25,
  ""summary"": ""Hot""
}
";
            WeatherForecast? weatherForecast;

            weatherForecast = JsonSerializer.Deserialize(
                jsonString, 
                typeof(WeatherForecast), 
                new OptionsExampleContext(
                    new JsonSerializerOptions(JsonSerializerDefaults.Web)))
                    as WeatherForecast;
            Console.WriteLine($"Date={weatherForecast?.Date}");
            // output:
            //Date=8/1/2019 12:00:00 AM

            jsonString = JsonSerializer.Serialize(
                weatherForecast,
                typeof(WeatherForecast),
                new OptionsExampleContext(
                    new JsonSerializerOptions(JsonSerializerDefaults.Web)));
            Console.WriteLine(jsonString);
            // output:
            //{ "date":"2019-08-01T00:00:00","temperatureCelsius":25,"summary":"Hot"}
        }
    }
}

Source generation support in ASP.NET Core

• In Blazor apps:

  Use overloads of HttpClientJsonExtensions.GetFromJsonAsync and HttpClientJsonExtensions.PostAsJsonAsync extension methods that take a source generation context or TypeInfo<TValue>.

• In Razor Pages, MVC, SignalR, and Web API apps:

  Use the AddContext method of JsonSerializerOptions, as shown in the following example:

  [JsonSerializable(typeof(WeatherForecast[]))]
  internal partial class MyJsonContext : JsonSerializerContext { }
  

  services.AddControllers().AddJsonOptions(options => options.JsonSerializerOptions.AddContext<MyJsonContext>());
  

See also

• Try the new System.Text.Json source generator
• JSON serialization and deserialization in .NET - overview
• How to use the library
• Instantiate JsonSerializerOptions instances
• Enable case-insensitive matching
• Customize property names and values
• Ignore properties
• Allow invalid JSON
• Handle overflow JSON or use JsonElement or JsonNode
• Preserve references and handle circular references
• Deserialize to immutable types and non-public accessors
• Polymorphic serialization
• Migrate from Newtonsoft.Json to System.Text.Json
• Customize character encoding
• Use DOM, Utf8JsonReader, and Utf8JsonWriter
• Write custom converters for JSON serialization
• DateTime and DateTimeOffset support
• Supported collection types in System.Text.Json
• System.Text.Json API reference
• System.Text.Json.Serialization API reference