Skriva .NET-objekt som JSON (serialisera)

Artikel
10/18/2024

Den här artikeln visar hur du använder System.Text.Json namnområdet för att serialisera till JavaScript Object Notation (JSON). Om du porterar befintlig kod från Newtonsoft.Jsonläser du Så här migrerar du tillSystem.Text.Json .

Dricks

Du kan använda AI-hjälp för att serialisera till JSON med GitHub Copilot.

Om du vill skriva JSON till en sträng eller till en fil anropar du JsonSerializer.Serialize metoden.

Serialiseringsexempel

I följande exempel skapas JSON som en sträng:

using System.Text.Json;

namespace SerializeBasic
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim jsonString As String

JSON-utdata minimeras (blanksteg, indrag och nya radtecken tas bort) som standard.

I följande exempel används synkron kod för att skapa en JSON-fil:

using System.Text.Json;

namespace SerializeToFile
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json"; 
            string jsonString = JsonSerializer.Serialize(weatherForecast);
            File.WriteAllText(fileName, jsonString);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(weatherForecast1)
File.WriteAllText(fileName, jsonString)

I följande exempel används asynkron kod för att skapa en JSON-fil:

using System.Text.Json;

namespace SerializeToFileAsync
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json";
            await using FileStream createStream = File.Create(fileName);
            await JsonSerializer.SerializeAsync(createStream, weatherForecast);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim createStream As FileStream = File.Create(fileName)
Await JsonSerializer.SerializeAsync(createStream, weatherForecast1)

I föregående exempel används typinferens för den typ som serialiseras. En överlagring av Serialize() tar en allmän typparameter:

using System.Text.Json;

namespace SerializeWithGenericParameter
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize<WeatherForecast>(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(Of WeatherForecastWithPOCOs)(weatherForecast)

Du kan också använda GitHub Copilot för att generera serialiseringskod åt dig. Anvisningar finns i avsnittet Använda GitHub Copilot i den här artikeln.

Serialiseringsbeteende

Som standard serialiseras alla offentliga egenskaper. Du kan ange egenskaper som ska ignoreras. Du kan också inkludera privata medlemmar.
Standardkodaren undflyr icke-ASCII-tecken, HTML-känsliga tecken inom ASCII-intervallet och tecken som måste vara undantagna enligt RFC 8259 JSON-specifikationen.
Som standard minimeras JSON. Du kan skriva ut JSON-filen på ett snyggt sätt.
Som standard matchar höljet för JSON-namn .NET-namnen. Du kan anpassa JSON-namnhöljet.
Som standard identifieras cirkelreferenser och undantag genereras. Du kan bevara referenser och hantera cirkelreferenser.
Som standard ignoreras fälten . Du kan inkludera fält.

När du använder System.Text.Json indirekt i en ASP.NET Core-app skiljer sig vissa standardbeteenden åt. Mer information finns i Webbstandarder för JsonSerializerOptions.

Exempel på typer som stöds är:

.NET-primitiver som mappar till JavaScript-primitiver, till exempel numeriska typer, strängar och booleska.
Användardefinierade oformaterade gamla CLR-objekt (POCOs).
Endimensionella och ojämna matriser (T[][]).
Samlingar och ordlistor från följande namnområden:
Mer information finns i Samlingstyper som stöds i System.Text.Json.

Du kan implementera anpassade konverterare för att hantera ytterligare typer eller för att tillhandahålla funktioner som inte stöds av de inbyggda konverterarna.

Här är ett exempel som visar hur en klass som innehåller samlingsegenskaper och en användardefinierad typ serialiseras:

using System.Text.Json;

namespace SerializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot",
                SummaryField = "Hot",
                DatesAvailable = new List<DateTimeOffset>() 
                    { DateTime.Parse("2019-08-01"), DateTime.Parse("2019-08-02") },
                TemperatureRanges = new Dictionary<string, HighLowTemps>
                    {
                        ["Cold"] = new HighLowTemps { High = 20, Low = -10 },
                        ["Hot"] = new HighLowTemps { High = 60 , Low = 20 }
                    },
                SummaryWords = new[] { "Cool", "Windy", "Humid" }
            };

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

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot",
//  "DatesAvailable": [
//    "2019-08-01T00:00:00-07:00",
//    "2019-08-02T00:00:00-07:00"
//  ],
//  "TemperatureRanges": {
//    "Cold": {
//      "High": 20,
//      "Low": -10
//    },
//    "Hot": {
//    "High": 60,
//      "Low": 20
//    }
//  },
//  "SummaryWords": [
//    "Cool",
//    "Windy",
//    "Humid"
//  ]
//}

Public Class WeatherForecastWithPOCOs
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String
    Public SummaryField As String
    Public Property DatesAvailable As IList(Of DateTimeOffset)
    Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
    Public Property SummaryWords As String()
End Class

Public Class HighLowTemps
    Public Property High As Integer
    Public Property Low As Integer
End Class

' serialization output formatted (pretty-printed with whitespace and indentation):
' {
'   "Date": "2019-08-01T00:00:00-07:00",
'   "TemperatureCelsius": 25,
'   "Summary": "Hot",
'   "DatesAvailable": [
'     "2019-08-01T00:00:00-07:00",
'     "2019-08-02T00:00:00-07:00"
'   ],
'   "TemperatureRanges": {
'     "Cold": {
'       "High": 20,
'       "Low": -10
'     },
'     "Hot": {
'       "High": 60,
'       "Low": 20
'     }
'   },
'   "SummaryWords": [
'     "Cool",
'     "Windy",
'     "Humid"
'   ]
' }

Serialisera till UTF-8

Det går 5–10 % snabbare att serialisera till en UTF-8 byte-matris än att använda strängbaserade metoder. Det beror på att byte (som UTF-8) inte behöver konverteras till strängar (UTF-16).

Om du vill serialisera till en UTF-8 byte-matris anropar du JsonSerializer.SerializeToUtf8Bytes metoden:

byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);

Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)

En Serialize överlagring som tar en Utf8JsonWriter är också tillgänglig.

Serialisera till formaterad JSON

Om du vill skriva ut JSON-utdata på ett snyggt sätt anger du JsonSerializerOptions.WriteIndented till true:

using System.Text.Json;

namespace SerializeWriteIndented
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

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

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot"
//}

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)

Från och med .NET 9 kan du också anpassa indragstecknet och storleken med hjälp av IndentCharacter och IndentSize.

Dricks

Om du använder JsonSerializerOptions upprepade gånger med samma alternativ ska du inte skapa en ny JsonSerializerOptions instans varje gång du använder den. Återanvänd samma instans för varje anrop. Mer information finns i ÅteranvändA JsonSerializerOptions-instanser.

Använda GitHub Copilot för att serialisera till JSON

Du kan använda GitHub Copilot i din IDE för att generera kod som använder System.Text.Json för att serialisera till JSON.

Om du använder Visual Studio 2022 version 17.8 eller senare kan du prova den AI-drivna GitHub Copilot i Visual Studio för att generera kod som använder System.Text.Json för att serialisera till JSON. Skicka din fråga som en uppmaning i Chattfönstret för Copilot, som i följande exempel. Du kan också skicka frågor med hjälp av infogad chatt i själva redigeringsfönstret.

Kommentar

GitHub Copilot drivs av AI, så överraskningar och misstag är möjliga. Kontrollera eventuell genererad kod eller förslag. Mer information om allmän användning av GitHub Copilot, produktpåverkan, mänsklig tillsyn och sekretess finns i Vanliga frågor och svar om GitHub Copilot.

Följande text visar en exempelfråga för Copilot Chat:

Generera kod som ska användas System.Text.Json för att serialisera ett objekt till en JSON-sträng. Objektet innehåller följande fält: FirstName (sträng), Efternamn (sträng), Ålder (int). Ange exempelutdata.

Du kan anpassa prompten så att den använder objektfält som passar dina behov.

Du kan använda chattfunktioner, till exempel snedstreckskommandon, referenser till filer, metoder eller klasser och trådar, för att ange avsikt och få bättre svar med begränsad kontext. För en befintlig klass i ett projekt som är öppet i IDE kan du fråga GitHub Copilot med /generate code to serialize #Classname in #Filename to JSON.

Följande utdata visar ett exempel på Copilot Chat-svar:

Sure! Below is an example of how to use System.Text.Json to serialize an object with the specified fields to a JSON string in C#:

using System;
using System.Text.Json;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}

public class Program
{
    public static void Main()
    {
        var person = new Person
        {
            FirstName = "John",
            LastName = "Doe",
            Age = 30
        };

        string jsonString = JsonSerializer.Serialize(person);
        Console.WriteLine(jsonString);
    }
}

**Example Output**
{"FirstName":"John","LastName":"Doe","Age":30}

This code defines a `Person` class, creates an instance of it, and then serializes it to a JSON string using `JsonSerializer.Serialize`. The resulting JSON string is then printed to the console.

När Copilot returnerar ett kodblock innehåller svaret alternativ för att kopiera koden, infoga koden i en ny fil eller förhandsgranska kodutdata.

Kommentar

Dina resultat kan skilja sig från vad som visas i exempelsvaren. AI-modeller är icke-deterministiska, vilket innebär att de kan returnera olika svar när de får samma fråga. Detta kan bero på ytterligare inlärning och anpassning över tid, språkvariationer, ändringar i kontexten, till exempel din chatthistorik med mera.

Mer information finns i:

Dela via