'da kaynak oluşturma nasıl kullanılır? System.Text.Json

Makale
11/10/2023

içindeki System.Text.Json kaynak oluşturma .NET 6 ve sonraki sürümlerde kullanılabilir. Bir uygulamada kullanıldığında, uygulamanın dil sürümü C# 9.0 veya üzeri olmalıdır. Bu makalede uygulamalarınızda kaynak oluşturma destekli serileştirmenin nasıl kullanılacağı gösterilmektedir.

Farklı kaynak oluşturma modları hakkında bilgi için bkz . Kaynak oluşturma modları.

Kaynak oluşturma varsayılanlarını kullanma

Tüm varsayılanlarla (her iki mod, varsayılan seçenekler) kaynak oluşturmayı kullanmak için:

öğesinden JsonSerializerContexttüretilen kısmi bir sınıf oluşturun.
Bağlam sınıfına uygulayarak JsonSerializableAttribute seri hale getirmek veya seri durumdan çıkarmak için türü belirtin.
JsonSerializer Şu yöntemlerden birini çağır:
- Örnek JsonTypeInfo<T> alır veya
- Örnek JsonSerializerContext alır veya
- Bir JsonSerializerOptions örneği alır ve özelliğini bağlam türünün özelliğine Default ayarladınız JsonSerializerOptions.TypeInfoResolver (yalnızca.NET 7 ve üzeri).

Varsayılan olarak, belirtmezseniz her iki kaynak oluşturma modu da kullanılır. Kullanılacak modu belirtme hakkında bilgi için bu makalenin devamında Kaynak oluşturma modunu belirtme bölümüne bakın.

Aşağıdaki örneklerde kullanılan tür aşağıda verilmiştir:

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

Önceki sınıf için kaynak oluşturmayı gerçekleştirmek üzere WeatherForecast yapılandırılan bağlam sınıfı aşağıdadır:

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

Üye türlerinin WeatherForecast özniteliklerle [JsonSerializable] açıkça belirtilmesi gerekmez. Olarak object bildirilen üyeler bu kuralın özel durumu. Olarak object bildirilen bir üye için çalışma zamanı türünün belirtilmesi gerekir. Örneğin, aşağıdaki sınıfa sahip olduğunuzu varsayalım:

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

Çalışma zamanında ve int nesnelerine sahip boolean olabileceğini biliyorsunuz:

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

Ardından boolean ve int olarak [JsonSerializable]bildirilmelidir:

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

Bir koleksiyon için kaynak oluşturmayı belirtmek için koleksiyon türüyle kullanın [JsonSerializable] . Örneğin: [JsonSerializable(typeof(List<WeatherForecast>))].

`JsonSerializer` kaynak oluşturma kullanan yöntemler

Aşağıdaki örneklerde, bağlam türünün statik Default özelliği varsayılan seçeneklerle bağlam türünün bir örneğini sağlar. Bağlam örneği, örnek WeatherForecast döndüren bir JsonTypeInfo<WeatherForecast> özellik sağlar. özniteliğinin özelliğini [JsonSerializable] kullanarak TypeInfoPropertyName bu özellik için farklı bir ad belirtebilirsiniz.

Serileştirme örnekleri

kullanarak JsonTypeInfo<T>:

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

kullanarak JsonSerializerContext:

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

kullanarak JsonSerializerOptions:

sourceGenOptions = new JsonSerializerOptions
{
    TypeInfoResolver = SourceGenerationContext.Default
};

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

Seri durumdan çıkarma örnekleri

kullanarak JsonTypeInfo<T>:

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

kullanarak JsonSerializerContext:

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

kullanarak JsonSerializerOptions:

var sourceGenOptions = new JsonSerializerOptions
{
    TypeInfoResolver = SourceGenerationContext.Default
};
weatherForecast = JsonSerializer.Deserialize(
    jsonString, typeof(WeatherForecast), sourceGenOptions)
    as WeatherForecast;

Tam program örneği

Tam bir programdaki önceki örnekler şunlardır:

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

            var sourceGenOptions = new JsonSerializerOptions
            {
                TypeInfoResolver = SourceGenerationContext.Default
            };
            weatherForecast = JsonSerializer.Deserialize(
                jsonString, typeof(WeatherForecast), sourceGenOptions)
                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"}

            sourceGenOptions = new JsonSerializerOptions
            {
                TypeInfoResolver = SourceGenerationContext.Default
            };

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

Kaynak oluşturma modunu belirtme

Birden çok tür içerebilen tüm bağlam için meta veri tabanlı mod veya serileştirme-iyileştirme modu belirtebilirsiniz. Ya da tek bir tür için modu belirtebilirsiniz. Her ikisini de yaparsanız, bir türün mod belirtimi kazanır.

Bağlamın tamamı için JsonSourceGenerationOptionsAttribute.GenerationMode özelliğini kullanın.
Tek bir tür için özelliğini kullanın JsonSerializableAttribute.GenerationMode .

Serileştirme-iyileştirme (hızlı yol) modu örneği

Tüm bağlam için:

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

Tek bir tür için:

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

Tam program örneği

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

Meta veri tabanlı mod örneği

Tüm bağlam için:

[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);

Tek bir tür için:

[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);

Tam program örneği

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":25,"Summary":"Hot"}
        }
    }
}

ASP.NET Core'da kaynak oluşturma desteği

Blazor uygulamalarında, kaynak oluşturma bağlamını HttpClientJsonExtensions.GetFromJsonAsync veya TypeInfo<TValue>alan ve HttpClientJsonExtensions.PostAsJsonAsync uzantı yöntemlerinin aşırı yüklemelerini kullanın.

.NET 8'den başlayarak, bir kaynak oluşturma bağlamını veya TypeInfo<TValue>kabul eden uzantı yöntemlerinin HttpClientJsonExtensions.GetFromJsonAsAsyncEnumerable aşırı yüklemelerini de kullanabilirsiniz.

Razor Pages, MVC, SignalR ve Web API uygulamalarında bağlamı JsonSerializerOptions.TypeInfoResolver belirtmek için özelliğini kullanın.

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

var serializerOptions = new JsonSerializerOptions
{
    TypeInfoResolver = MyJsonContext.Default
};

services.AddControllers().AddJsonOptions(
    static options =>
        options.JsonSerializerOptions.TypeInfoResolverChain.Add(MyJsonContext.Default));

Razor Pages, MVC, SignalR ve Web API uygulamalarında bağlamı JsonSerializerOptions.TypeInfoResolver belirtmek için özelliğini kullanın.

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

var serializerOptions = new JsonSerializerOptions
{
    TypeInfoResolver = MyJsonContext.Default
};

services.AddControllers().AddJsonOptions(
    static options =>
        options.JsonSerializerOptions = serializerOptions);

Razor Pages, MVC, SignalR ve Web API uygulamalarında, aşağıdaki örnekte gösterildiği gibi yöntemini JsonSerializerOptionskullanınAddContext:

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

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

Not

JsonSourceGenerationMode.Serializationveya hızlı yol serileştirme, zaman uyumsuz serileştirme için desteklenmez.

.NET 7 ve önceki sürümlerinde, bu sınırlama bir kabul Streameden zaman uyumlu aşırı yüklemeleri JsonSerializer.Serialize için de geçerlidir. .NET 8'den başlayarak, akış serileştirmesi meta veri tabanlı modeller gerektirse de, yüklerin önceden belirlenmiş arabellek boyutuna sığacak kadar küçük olduğu biliniyorsa hızlı yola geri döner. Daha fazla bilgi için bkz. https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-8/#json.

Yansıma varsayılanlarını devre dışı bırakma

System.Text.Json Varsayılan olarak yansıma kullandığından, temel bir serileştirme yöntemini çağırmak, gerekli tüm yansıma API'lerini desteklemeyen Yerel AOT uygulamalarını bozabilir. Bu kesmelerin tanılanması zor olabilir çünkü bunlar öngörülemez olabilir ve uygulamalar genellikle yansımanın çalıştığı CoreCLR çalışma zamanı kullanılarak hata ayıklanır. Bunun yerine, yansıma tabanlı serileştirmeyi açıkça devre dışı bırakırsanız, kesmeleri tanılamak daha kolaydır. Yansıma tabanlı serileştirme kullanan kod, açıklayıcı bir ileti içeren bir InvalidOperationException öğesinin çalışma zamanında atılmasıyla sonuçlanır.

Uygulamanızda varsayılan yansımayı JsonSerializerIsReflectionEnabledByDefault devre dışı bırakmak için MSBuild özelliğini proje dosyanızda olarak false ayarlayın:

<PropertyGroup>
  <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
</PropertyGroup>

Bu özelliğin davranışı, CoreCLR veya Yerel AOT çalışma zamanından bağımsız olarak tutarlıdır.
Bu özelliği belirtmezseniz ve PublishTrimmed etkinleştirilirse, yansıma tabanlı serileştirme otomatik olarak devre dışı bırakılır.

özelliğini kullanarak JsonSerializer.IsReflectionEnabledByDefault yansımanın devre dışı bırakılıp bırakılmadığını program aracılığıyla deleyebilirsiniz. Aşağıdaki kod parçacığı, yansımanın etkinleştirilip etkinleştirilmediğine bağlı olarak seri hale getiricinizi nasıl yapılandırabileceğinizi gösterir:

static JsonSerializerOptions CreateDefaultOptions()
{
    return new()
    {
        TypeInfoResolver = JsonSerializer.IsReflectionEnabledByDefault
            ? new DefaultJsonTypeInfoResolver()
            : MyContext.Default
    };
}

özelliği bir bağlantı zamanı sabiti olarak ele alındığından, önceki yöntem Yerel AOT'de çalışan uygulamalarda yansıma tabanlı çözümleyicinin kökünü oluşturmaz.

Seçenekleri belirtme

.NET 8 ve sonraki sürümlerde, kullanarak JsonSerializerOptions ayarlayabileceğiniz çoğu seçenek özniteliği kullanılarak JsonSourceGenerationOptionsAttribute da ayarlanabilir. Öznitelik aracılığıyla seçenekleri ayarlamanın avantajı, yapılandırmanın derleme zamanında belirtilmesinin, oluşturulan MyContext.Default özelliğin tüm ilgili seçenekler kümesiyle önceden yapılandırılmasını sağlamasıdır.

Aşağıdaki kod, özniteliğini kullanarak JsonSourceGenerationOptionsAttribute seçeneklerin nasıl ayarlandığını gösterir.

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

serileştirme seçeneklerini belirtmek için kullanırken JsonSourceGenerationOptionsAttribute aşağıdaki serileştirme yöntemlerinden birini çağırın:

bir JsonSerializer.Serialize alan yöntemi TypeInfo<TValue>. Default.<TypeName> Bağlam sınıfınızın özelliğini geçirin:
```
jsonString = JsonSerializer.Serialize(
    weatherForecast, SerializationModeOptionsContext.Default.WeatherForecast);
```

Bağlam JsonSerializer.Serialize alan bir yöntem. Default Bağlam sınıfınızın statik özelliğini geçirin.

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

kendi örneğinizi Utf8JsonWritergeçirmenize olanak tanıyan bir yöntem çağırırsanız, yazıcının Indented ayarı seçeneği yerine JsonSourceGenerationOptionsAttribute.WriteIndented kabul edilir.

Örnek alan oluşturucuyu çağırarak bir JsonSerializerOptions bağlam örneği oluşturur ve kullanırsanız, tarafından JsonSourceGenerationOptionsAttributebelirtilen seçenekler yerine sağlanan örnek kullanılır.

Tam bir programdaki önceki örnekler şunlardır:

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

Kullanarak seçenekleri belirtme `JsonSerializerOptions`

bazı seçenekleri JsonSerializerOptions kullanılarak JsonSourceGenerationOptionsAttributeayarlanamaz. kullanarak JsonSerializerOptionsseçenekleri belirtmek için:

JsonSerializerOptions örneği oluşturun.
sınıfından türetilen JsonSerializerContextbir örneği oluşturun ve örneği oluşturucuya geçirin JsonSerializerOptions .
Bir bağlam örneği veya almak için serileştirme veya TypeInfo<TValue>seri durumdan çıkarma yöntemlerini JsonSerializer çağırın.

Aşağıda örnek bir bağlam sınıfı, ardından serileştirme ve seri durumdan çıkarma örnek kodu verilmiştir:

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

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

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

Tam bir programdaki önceki örnekler şunlardır:

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(
                    JsonSerializerOptions.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(
                    JsonSerializerOptions.Web));
            Console.WriteLine(jsonString);
            // output:
            //{ "date":"2019-08-01T00:00:00","temperatureCelsius":25,"summary":"Hot"}
        }
    }
}

Kaynak oluşturucuları birleştirme

Kaynak tarafından oluşturulan birden çok bağlamdaki sözleşmeleri tek JsonSerializerOptions bir örnekte birleştirebilirsiniz. JsonSerializerOptions.TypeInfoResolver yöntemi kullanılarak JsonTypeInfoResolver.Combine(IJsonTypeInfoResolver[]) birleştirilmiş birden çok bağlamı zincirleme özelliğini kullanın.

var options = new JsonSerializerOptions
{
    TypeInfoResolver = JsonTypeInfoResolver.Combine(ContextA.Default, ContextB.Default, ContextC.Default);
};

.NET 8'den başlayarak, daha sonra başka bir bağlam eklemek veya eklemek istiyorsanız, özelliğini kullanarak JsonSerializerOptions.TypeInfoResolverChain bunu yapabilirsiniz. Zincirin sırası önemlidir: JsonSerializerOptions çözümleyicilerin her birini belirtilen sırayla sorgular ve null olmayan ilk sonucu döndürür.

options.TypeInfoResolverChain.Add(ContextD.Default); // Append to the end of the list.
options.TypeInfoResolverChain.Insert(0, ContextE.Default); // Insert at the beginning of the list.

Özelliğinde TypeInfoResolverChain yapılan tüm değişiklikler tarafından yansıtılır TypeInfoResolver ve tam tersi de geçerlidir.

Sabit listesi alanlarını dize olarak seri hale getirme

Sabit listeleri varsayılan olarak sayı olarak serileştirilir. Kaynak oluşturma kullanılırken belirli bir sabit listesi alanlarını dize olarak seri hale getirmek için, dönüştürücü ile JsonStringEnumConverter<TEnum> buna ek açıklama ekleyin. Veya tüm sabit listeleri için bir paket ilkesi ayarlamak için özniteliğini JsonSourceGenerationOptionsAttribute kullanın.

`JsonStringEnumConverter<T>` dönüştürücü

Numaralandırma adlarını kaynak oluşturma kullanarak dize olarak seri hale getirmek için dönüştürücüsü JsonStringEnumConverter<TEnum> kullanın. (Genel olmayan JsonStringEnumConverter tür Yerel AOT çalışma zamanı tarafından desteklenmez.)

Özniteliğini kullanarak dönüştürücü ile JsonStringEnumConverter<TEnum> numaralandırma türüne ek açıklama ekleyin JsonConverterAttribute :

public class WeatherForecastWithPrecipEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Precipitation? Precipitation { get; set; }
}

[JsonConverter(typeof(JsonStringEnumConverter<Precipitation>))]
public enum Precipitation
{
    Drizzle, Rain, Sleet, Hail, Snow
}

Bir JsonSerializerContext sınıf oluşturun ve özniteliğiyle bu sınıfa JsonSerializableAttribute ek açıklama ekleyin:

[JsonSerializable(typeof(WeatherForecastWithPrecipEnum))]
public partial class Context1 : JsonSerializerContext { }

Aşağıdaki kod, sayısal değerler yerine sabit listesi adlarını serileştirir:

var weatherForecast = new WeatherForecastWithPrecipEnum
{
    Date = DateTime.Parse("2019-08-01"),
    TemperatureCelsius = 25,
    Precipitation = Precipitation.Sleet
};

var options = new JsonSerializerOptions
{
    WriteIndented = true,
    TypeInfoResolver = Context1.Default,
};
string? jsonString = JsonSerializer.Serialize(weatherForecast, options);

Elde edilen JSON aşağıdaki örneğe benzer:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Precipitation": "Sleet"
}

Paket ilkesi

türünü kullanmak JsonStringEnumConverter<TEnum> yerine, kullanarak sabit listelerini dize JsonSourceGenerationOptionsAttributeolarak serileştirmek için bir paket ilkesi uygulayabilirsiniz. Bir JsonSerializerContext sınıf oluşturun ve ve JsonSourceGenerationOptionsAttribute öznitelikleriyle bu sınıfa JsonSerializableAttribute açıklama ekleyin:

[JsonSourceGenerationOptions(UseStringEnumConverter = true)]
[JsonSerializable(typeof(WeatherForecast2WithPrecipEnum))]
public partial class Context2 : JsonSerializerContext { }

Sabit listesi'nin şu değere JsonConverterAttributesahip olduğuna dikkat edin:

public class WeatherForecast2WithPrecipEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Precipitation2? Precipitation { get; set; }
}

public enum Precipitation2
{
    Drizzle, Rain, Sleet, Hail, Snow
}

Özel sabit listesi üye adları

.NET 9'dan başlayarak, JsonStringEnumMemberName özniteliğini kullanarak numaralandırma üyesi adlarını özelleştirebilirsiniz. Daha fazla bilgi için bkz . Özel sabit listesi üye adları.

Aracılığıyla paylaş

'da kaynak oluşturma nasıl kullanılır? System.Text.Json

Kaynak oluşturma varsayılanlarını kullanma

`JsonSerializer` kaynak oluşturma kullanan yöntemler

Serileştirme örnekleri

Seri durumdan çıkarma örnekleri

Tam program örneği

Kaynak oluşturma modunu belirtme

Serileştirme-iyileştirme (hızlı yol) modu örneği

Meta veri tabanlı mod örneği

ASP.NET Core'da kaynak oluşturma desteği

Yansıma varsayılanlarını devre dışı bırakma

Seçenekleri belirtme

Kullanarak seçenekleri belirtme `JsonSerializerOptions`

Kaynak oluşturucuları birleştirme

Sabit listesi alanlarını dize olarak seri hale getirme

`JsonStringEnumConverter<T>` dönüştürücü

Paket ilkesi

Özel sabit listesi üye adları

Ayrıca bkz.

Ek kaynaklar

Aracılığıyla paylaş

'da kaynak oluşturma nasıl kullanılır? System.Text.Json

Kaynak oluşturma varsayılanlarını kullanma

JsonSerializer kaynak oluşturma kullanan yöntemler

Serileştirme örnekleri

Seri durumdan çıkarma örnekleri

Tam program örneği

Kaynak oluşturma modunu belirtme

Serileştirme-iyileştirme (hızlı yol) modu örneği

Meta veri tabanlı mod örneği

ASP.NET Core'da kaynak oluşturma desteği

Yansıma varsayılanlarını devre dışı bırakma

Seçenekleri belirtme

Kullanarak seçenekleri belirtme JsonSerializerOptions

Kaynak oluşturucuları birleştirme

Sabit listesi alanlarını dize olarak seri hale getirme

JsonStringEnumConverter<T> dönüştürücü

Paket ilkesi

Özel sabit listesi üye adları

Ayrıca bkz.

Ek kaynaklar

`JsonSerializer` kaynak oluşturma kullanan yöntemler

Kullanarak seçenekleri belirtme `JsonSerializerOptions`

`JsonStringEnumConverter<T>` dönüştürücü