복합 형식 지정

아티클
2025-04-03

.NET 복합 서식 지정 기능은 개체 목록과 복합 서식 문자열을 입력으로 사용합니다. 복합 서식 문자열은 형식 항목이라고 하는 인덱싱된 자리 표시자와 혼합된 고정 텍스트로 구성됩니다. 이러한 형식 항목은 목록의 개체에 해당합니다. 서식 지정 작업을 통해 원래의 고정 텍스트와 목록에 있는 개체의 문자열 표현이 결합된 형태의 결과 문자열을 얻을 수 있습니다.

중요합니다

복합 형식 문자열을 사용하는 대신 사용 중인 언어 및 해당 버전이 지원하는 경우 보간된 문자열 을 사용할 수 있습니다. 보간된 문자열에는 보간된 식이 포함됩니다. 보간된 각 식은 식의 값으로 확인되고 문자열이 할당될 때 결과 문자열에 포함됩니다. 자세한 내용은 문자열 보간(C# 참조) 및 보간된 문자열(Visual Basic 참조)을 참조하세요.

다음 메서드는 복합 서식 지정 기능을 지원합니다.

String.Format형식이 지정된 결과 문자열을 반환하는 입니다.
StringBuilder.AppendFormat 형식이 지정된 결과 문자열을 StringBuilder 객체에 추가합니다.
형식이 지정된 결과 문자열을 Console.WriteLine 콘솔에 표시하는 메서드의 일부 오버로드입니다.
특정 오버로드에서는 형식화된 결과 문자열을 스트림이나 파일에 쓰는 TextWriter.WriteLine 메서드를 사용합니다. 파생된 TextWriter클래스(예: StreamWriter 및 HtmlTextWriter)도 이 기능을 공유합니다.
Debug.WriteLine(String, Object[])- 추적 수신기에 형식이 지정된 메시지를 출력합니다.
Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[]), 및 Trace.TraceWarning(String, Object[]) 메서드는 추적 수신기에 형식이 지정된 메시지를 출력합니다.
TraceSource.TraceInformation(String, Object[]) 수신기를 추적하기 위해 정보 메서드를 작성하는 메서드입니다.

복합 형식 문자열

복합 서식 문자열 및 개체 목록은 복합 서식 지정 기능을 지원하는 메서드의 인수로 사용됩니다. 복합 서식 문자열은 하나 이상의 서식 항목과 섞인 고정 텍스트의 0개 이상의 실행으로 구성됩니다. 고정 텍스트는 선택한 문자열이며 각 서식 항목은 목록의 개체 또는 상자 구조체에 해당합니다. 각 개체의 문자열 표현은 해당 형식 항목을 대체합니다.

다음 코드 조각을 고려합니다.Format

string.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now);

String.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now)

고정 텍스트는 Name = 와 , hours = 입니다. 형식 항목은 {0}인덱스 0이 개체에 해당하고 name인덱스 1이 개체{1:hh}DateTime.Now에 해당합니다.

항목 구문 서식 지정

각 서식 항목의 형태와 구성 요소는 다음과 같습니다.

{index[,width][:formatString]}

일치하는 중괄호({ 및 })가 필요합니다.

인덱스 구성 요소

매개 변수 지정자라고도 하는 필수 index 구성 요소는 개체 목록에서 해당 항목을 식별하는 0부터 시작하는 숫자입니다. 즉, 매개 변수 지정자가 목록의 첫 번째 개체에 서식을 지정하는 서식 항목입니다 0 . 형식 항목에서 매개 변수 지정자 1는 목록 내 두 번째 개체부터 서식을 지정하며, 이후 항목에도 계속해서 적용됩니다. 다음 예제에서는 10보다 작은 소수를 나타내기 위해 0부터 3까지 번호가 매겨진 4개의 매개 변수 지정자를 포함합니다.

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 2, 3, 5, 7

여러 형식 항목은 동일한 매개 변수 지정자를 지정하여 개체 목록에서 동일한 요소를 참조할 수 있습니다. 예를 들어, 다음 예제와 같이 복합 형식 문자열 "0x{0:X} {0:E} {0:N}"을 지정하여 동일한 숫자 값을 16진수, 과학적, 숫자 형식으로 형식을 지정할 수 있습니다.

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

각 형식 항목은 목록의 모든 개체를 참조할 수 있습니다. 예를 들어 세 개의 개체가 있는 경우 같은 복합 서식 문자열 {1} {0} {2}을 지정하여 두 번째, 첫 번째 및 세 번째 개체의 서식을 지정할 수 있습니다. 형식 항목에서 참조되지 않는 개체는 무시됩니다. 매개 변수 지정자가 개체 목록의 범위를 벗어난 항목을 지정하는 경우 런타임에 A FormatException 가 throw됩니다.

너비 구성 요소

선택적 width 구성 요소는 기본 형식 필드 너비를 나타내는 부호 있는 정수입니다. 값 width 이 서식이 지정된 문자열 width 의 길이보다 작으면 무시되고 서식이 지정된 문자열의 길이가 필드 너비로 사용됩니다. width가 양수이면 필드의 서식이 지정된 데이터는 오른쪽 맞춤이고, width가 음수이면 왼쪽 맞춤입니다. 패딩이 필요한 경우 공백이 사용됩니다. 지정된 경우 width 쉼표가 필요합니다.

다음 예제에서는 두 개의 배열을 정의합니다. 하나는 직원의 이름을 포함하고 다른 하나는 2주 동안 근무한 시간을 포함합니다. 복합 형식 문자열은 20자 필드의 이름을 왼쪽으로 정렬하고 5자 필드에서 해당 시간을 오른쪽에 맞춥니다. "N1" 표준 형식 문자열은 소수 자릿수가 한 자리인 시간의 서식을 지정합니다.

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

문자열 구성 요소 서식 지정

선택적 formatString 구성 요소는 서식이 지정되는 개체의 형식에 적합한 형식 문자열입니다. 다음을 지정할 수 있습니다.

해당 개체가 숫자 값인 경우 표준 또는 사용자 지정 숫자 서식 문자열입니다.
해당 개체가 DateTime 개체인 경우 표준 또는 사용자 지정 날짜 및 시간 형식 문자열입니다.
해당 개체가 열거형 값인 경우, 열거형 형식 문자열입니다.

지정하지 않으면 formatString 숫자, 날짜 및 시간 또는 열거형 형식에 대한 일반("G") 형식 지정자가 사용됩니다. 지정된 경우 formatString 콜론이 필요합니다.

다음 표에서는 미리 정의된 형식 문자열 집합을 지원하는 .NET 클래스 라이브러리의 형식 또는 형식 범주를 나열하고 지원되는 형식 문자열을 나열하는 아티클에 대한 링크를 제공합니다. 문자열 서식 지정은 기존의 모든 형식에 대해 새 형식 문자열을 정의하고 애플리케이션 정의 형식에서 지원하는 형식 문자열 집합을 정의할 수 있게 해주는 확장 가능한 메커니즘입니다.

자세한 내용은 IFormattable 및 ICustomFormatter 인터페이스 문서를 참조하세요.

형식 또는 형식 범주	보십시오
날짜 및 시간 형식(DateTime, DateTimeOffset)	표준 날짜 및 시간 형식 문자열 사용자 지정 날짜 및 시간 형식 문자열
열거형 형식 (System.Enum에서 파생된 모든 형식)	열거형 형식 문자열
숫자 형식(BigInteger,,Byte, Decimal, Double, Int16 Int32, Int64 SByte, Single UInt16, ) UInt32 UInt64	표준 숫자 형식 문자열 사용자 지정 숫자 형식 문자열
Guid	Guid.ToString(String)
TimeSpan	표준 TimeSpan 서식 문자열 사용자 지정 TimeSpan 서식 문자열

중괄호 이스케이프

여는 중괄호와 닫는 중괄호는 형식 항목을 시작하고 끝내는 것으로 해석됩니다. 리터럴 여는 중괄호 또는 닫는 중괄호를 표시하려면 이스케이프 시퀀스를 사용해야 합니다. 한 개의 여는 중괄호() 또는 두 개의 닫는 중괄호({{{)를 표시하도록 고정 텍스트에 두 개의 여는 중괄호(}})를 지정하여 하나의 닫는 중괄호(})를 표시합니다.

.NET과 .NET Framework에서는 형식 항목을 포함한 이스케이프된 중괄호가 서로 다르게 구문 분석됩니다.

닷넷

중괄호는 서식 항목 주위에서 이스케이프할 수 있습니다. 예를 들어 여는 중괄호, 소수로 서식이 지정된 숫자 값 및 닫는 중괄호를 표시하기 위한 서식 항목을 {{{0:D}}}고려합니다. 형식 항목은 다음과 같은 방식으로 해석됩니다.

처음 두 개의 여는 중괄호({{)는 이스케이프되고 하나의 여는 중괄호를 생성합니다.
다음 세 문자({0:)는 형식 항목의 시작으로 해석됩니다.
다음 문자(D)는 10진수 표준 숫자 형식 지정자로 해석됩니다.
다음 중괄호(})는 형식 항목의 끝으로 해석됩니다.
마지막 두 개의 닫는 중괄호는 이스케이프되고 하나의 닫는 중괄호를 생성합니다.
표시되는 최종 결과는 리터럴 문자열 {6324}입니다.

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework

형식 항목의 중괄호는 만나는 순서대로 순차적으로 해석됩니다. 중첩된 중괄호 해석은 지원되지 않습니다.

이탈된 중괄호가 해석되는 방식은 예기치 않은 결과를 초래할 수 있습니다. 예를 들어 여는 중괄호, 소수로 서식이 지정된 숫자 값 및 닫는 중괄호를 표시하기 위한 서식 항목을 {{{0:D}}}고려합니다. 그러나 형식 항목은 다음과 같은 방식으로 해석됩니다.

처음 두 개의 여는 중괄호({{)는 이스케이프되고 하나의 여는 중괄호를 생성합니다.
다음 세 문자({0:)는 형식 항목의 시작으로 해석됩니다.
다음 문자(D)는 10진수 표준 숫자 형식 지정자로 해석되지만 다음 두 개의 이스케이프된 중괄호(}})는 단일 중괄호를 생성합니다. 결과 문자열(D})은 표준 숫자 형식 지정자가 아니므로 결과 문자열은 리터럴 문자열을 표시하는 것을 의미하는 사용자 지정 형식 문자열 D}로 해석됩니다.
마지막 중괄호(})는 형식 항목의 끝으로 해석됩니다.
표시되는 최종 결과는 리터럴 문자열 {D}입니다. 서식을 지정할 숫자 값이 표시되지 않습니다.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

이스케이프된 중괄호와 서식 항목을 잘못 해석하지 않도록 코드를 작성하는 방법 중 하나는 중괄호와 서식 항목을 각각 따로 포맷팅하는 것입니다. 즉, 첫 번째 형식 처리에서 리터럴 여는 중괄호를 표시합니다. 다음 작업에서 서식 항목의 결과를 표시하고, 최종 작업에서 리터럴한 닫는 중괄호를 표시합니다. 다음 예제에서는 이 방법을 보여 줍니다.

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}",
                                     "{", value, "}")
Console.WriteLine(output)

'The example displays the following output:
'      {6324}

처리 순서

복합 서식 지정 메서드 호출에 IFormatProvider이 아닌 값을 가진 null 인수가 포함된 경우, 런타임은 IFormatProvider.GetFormat 구현을 요청하기 위해 ICustomFormatter 메서드를 호출합니다. 메서드가 ICustomFormatter 구현을 반환할 수 있는 경우, 복합 서식 지정 메서드 호출 중에 캐시됩니다.

형식 항목에 해당하는 매개 변수 목록의 각 값은 다음과 같이 문자열로 변환됩니다.

서식을 지정할 값이 null면 빈 문자열 String.Empty 이 반환됩니다.
ICustomFormatter 구현을 사용할 수 있는 경우 런타임은 Format 메서드를 호출합니다. 런타임은 형식 항목의 formatString 값(또는 null 없는 경우)을 메서드에 전달합니다. 또한 런타임은 구현을 IFormatProvider 메서드에 전달합니다. 메서드 호출이 ICustomFormatter.Format 반환 null되면 실행이 다음 단계로 진행됩니다. 그렇지 않으면 호출 결과가 ICustomFormatter.Format 반환됩니다.
값이 인터페이스를 구현하는 IFormattable 경우 인터페이스의 ToString(String, IFormatProvider) 메서드가 호출됩니다. 형식 항목 formatString 에 값이 있으면 메서드에 값이 전달됩니다. 그렇지 않으면 null 전달됩니다. 인수는 IFormatProvider 다음과 같이 결정됩니다.
- 숫자 값의 경우 null IFormatProvider 이 아닌 인수가 있는 복합 서식 지정 메서드가 호출되면 런타임은 해당 NumberFormatInfo 메서드에서 개체를 IFormatProvider.GetFormat 요청합니다. 인수를 제공할 수 없거나, 인수 값이 null 이거나, 복합 서식 지정 메서드가 IFormatProvider 매개 변수를 갖고 있지 않은 경우, 현재 문화권의 NumberFormatInfo 개체가 사용됩니다.
- 날짜 및 시간 값의 경우 null IFormatProvider 이 아닌 인수가 있는 복합 서식 지정 메서드가 호출되면 런타임은 해당 DateTimeFormatInfo 메서드에서 개체를 IFormatProvider.GetFormat 요청합니다. 다음 상황에서는 현재 문화권 DateTimeFormatInfo 의 개체가 대신 사용됩니다.
  - 메서드가 IFormatProvider.GetFormat 개체를 제공할 DateTimeFormatInfo 수 없습니다.
  - 인수의 값은 .입니다 null.
  - 복합 서식 지정 메서드에는 매개 변수가 IFormatProvider 없습니다.
- 다른 형식의 개체의 경우 복합 서식 메서드를 인수로 IFormatProvider 호출하면 해당 값이 구현에 IFormattable.ToString 직접 전달됩니다. 그렇지 않으면 null 구현에 IFormattable.ToString 전달됩니다.
타입의 매개 변수가 없는 ToString 메서드가 호출되며, 이 메서드는 Object.ToString()를 재정의하거나 기본 클래스의 동작을 상속합니다. 이 경우 형식 항목의 구성 요소에서 지정한 formatString 형식 문자열(있는 경우)은 무시됩니다.

맞춤은 이전 단계가 수행된 후에 적용됩니다.

코드 예제

다음 예제에서는 복합 서식을 사용하여 만든 문자열 하나와 개체의 ToString 메서드를 사용하여 만든 문자열을 보여줍니다. 두 형식의 서식은 동일한 결과를 생성합니다.

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

Dim formatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim formatString2 As String = DateTime.Now.ToString("dddd MMMM")

현재 날짜가 5월의 목요일이라고 가정하면 이전 예제의 두 문자열 값은 Thursday May 미국 영어 문화권에 있습니다.

Console.WriteLine는 .와 동일한 기능을 노출합니다.String.Format 두 메서드 String.Format 의 유일한 차이점은 결과를 문자열로 반환하고 Console.WriteLine 결과를 개체와 Console 연결된 출력 스트림에 쓰는 것입니다. 다음 예제에서는 이 메서드를 Console.WriteLine 사용하여 값의 myNumber 형식을 통화 값으로 지정합니다.

int myNumber = 100;
Console.WriteLine($"{myNumber:C}");

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

다음 예제는 여러 개체 서식 지정과, 하나의 개체를 두 가지 방식으로 서식 지정하는 방법을 보여 줍니다.

string myName = "Fred";
Console.WriteLine(string.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now));

// Depending on the current time, the example displays output like the following:
//        Name = Fred, hours = 11, minutes = 30

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now))
'Depending on the current time, the example displays output Like the following:
'       Name = Fred, hours = 11, minutes = 30

다음 예제에서는 서식에 너비를 사용하는 방법을 보여 줍니다. 서식이 지정된 인수는 세로 막대 문자(|)사이에 배치되어 결과 맞춤을 강조 표시합니다.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);

// The example displays the following output on a system whose current
// culture is en-US:
//     First Name = |      Fred|
//     Last Name =  |     Opals|
//     Price =      |   $100.00|
//
//     First Name = |Fred      |
//     Last Name =  |Opals     |
//     Price =      |$100.00   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)

'The example displays the following output on a system whose current
'culture Is en-US:
'    First Name = |      Fred|
'    Last Name =  |     Opals|
'    Price =      |   $100.00|
'
'    First Name = |Fred      |
'    Last Name =  |Opals     |
'    Price =      |$100.00   |