.NET 개체를 JSON으로 쓰는 방법(직렬화)

아티클
12/21/2024

이 문서에서는 System.Text.Json 네임스페이스를 사용하여 JSON(JavaScript Object Notation)으로 직렬화하는 방법을 보여 줍니다. Newtonsoft.Json에서 기존 코드를 이식하는 경우 System.Text.Json으로 마이그레이션 방법을 참조하세요.

팁

GitHub Copilot을 사용하여 JSON으로 직렬화를 위해 AI 지원을 사용할 수 있습니다.

문자열 또는 파일에 JSON을 쓰려면 JsonSerializer.Serialize 메서드를 호출합니다.

Serialization 예제

다음은 JSON 파일을 문자열로 만드는 예제입니다.

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 출력은 기본적으로 축소 됩니다(공백, 들여쓰기 및 줄 바꿈 문자 제거).

다음은 동기 코드를 사용하여 JSON 파일을 만드는 예제입니다.

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)

다음은 비동기 코드를 사용하여 JSON 파일을 만드는 예지입니다.

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)

앞의 예제에서는 직렬화되는 형식에 형식 유추를 사용합니다. Serialize()의 오버로드는 제네릭 형식 매개 변수를 사용합니다.

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)

GitHub Copilot를 사용하여 직렬화 코드를 생성할 수도 있습니다. 자세한 내용은 이 문서의 GitHub Copilot 사용 섹션을 참조하세요.

Serialization 동작

기본적으로 모든 public 속성은 직렬화됩니다. 무시할 속성을 지정할 수 있습니다. 프라이빗 멤버을 포함할 수도 있습니다.
기본 인코더는 ASCII가 아닌 문자, ASCII 범위 내의 HTML 구분 문자 및 RFC 8259 JSON 사양에 따라 이스케이프되어야 하는 문자를 이스케이프합니다.
기본적으로 JSON은 축소됩니다. JSON을 보기 좋게 출력할 수 있습니다.
기본적으로 JSON 이름의 대/소문자는 .NET 이름과 일치합니다. JSON 이름 대/소문자를 사용자 지정할 수 있습니다.
기본적으로 순환 참조가 검색되고 예외가 throw됩니다. 참조를 보존하고 순환 참조를 처리할 수 있습니다.
기본적으로 필드는 무시됩니다. 필드를 포함할 수 있습니다.

ASP.NET Core 앱에서 System.Text.Json을 간접적으로 사용하는 경우 몇 가지 기본 동작이 다릅니다. 자세한 내용은 JsonSerializerOptions 웹 기본값을 참조하세요.

지원되는 형식은 다음과 같습니다.

숫자 형식, 문자열, 부울 등 JavaScript 기본 형식에 매핑되는 .NET 기본 형식
사용자 정의 POCO(Plain Old CLR Object)
1차원 및 가변 배열(T[][])
다음 네임스페이스의 컬렉션 및 사전.
자세한 내용은 지원되는 형식에서 System.Text.Json를 참조하세요.

추가 형식을 처리하거나 기본 변환기에서 지원하지 않는 기능을 제공하는 사용자 지정 변환기를 구현할 수 있습니다.

다음은 컬렉션 속성 및 사용자 정의 형식을 포함하는 클래스가 직렬화되는 방법을 보여 주는 예제입니다.

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

UTF-8로 직렬화

문자열 기반 방법을 사용하는 것보다 UTF-8 바이트 배열로 직렬화하는 것이 5~10% 더 빠릅니다. 그 이유는 바이트(UTF-8)를 문자열(UTF-16)로 변환할 필요가 없기 때문입니다.

UTF-8 바이트 배열로 직렬화하려면 JsonSerializer.SerializeToUtf8Bytes 메서드를 호출합니다.

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

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

Serialize를 사용하는 Utf8JsonWriter 오버로드도 사용할 수 있습니다.

형식이 지정된 JSON으로 직렬화

JSON 출력을 보기 좋게 출력하려면 JsonSerializerOptions.WriteIndented을 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)

.NET 9부터 들여쓰기 문자 및 크기를 사용하여 IndentCharacter 사용자 지정할 수도 있습니다 IndentSize.

팁

동일한 옵션으로 JsonSerializerOptions를 반복적으로 사용하는 경우 사용할 때마다 새 JsonSerializerOptions 인스턴스를 만들지 마세요. 모든 호출에 대해 동일한 인스턴스를 다시 사용하세요. 자세한 내용은 JsonSerializerOptions 인스턴스 다시 사용을 참조하세요.

GitHub Copilot을 사용하여 JSON으로 직렬화

IDE에서 GitHub Copilot를 사용하여 JSON으로 직렬화하는 데 System.Text.Json을(를) 사용하는 코드를 생성할 수 있습니다. 요구 사항에 맞는 개체 필드를 사용하도록 프롬프트를 사용자 지정할 수 있습니다.

다음 텍스트는 Copilot 채팅의 프롬프트 예를 보여줍니다.

Generate code to use System.Text.Json to serialize an object to a JSON string.
The object contains the following fields: FirstName (string), Lastname (string), Age (int).
Provide example output.

GitHub Copilot는 AI를 통해 구동되므로 예상치 못한 실수가 발생할 수 있습니다. 자세한 내용은 부조종사 FAQ참조하세요.

Visual Studio GitHub Copilot VS CodeGitHub Copilot를 대해 자세히 알아봅니다.

다음을 통해 공유