The Comprehensive Guide to Custom DateTime String Formats in C#
C# offers several ways to turn a DateTime into a string. Custom format specifiers give full control over the output, and each one is explained with examples.
On this page
When working with C#, we can convert a DateTime object to a string. The default string format will be outputted if we don’t specify any formatting options. However, C# lets you customise how the DateTime object should be outputted using custom format specifiers.
How do I format DateTime objects?
You can format a DateTime object in a few ways. We’ll first go through some of these methods before going through how to use custom format strings to format DateTime objects.
Using DateTime.ToString()
This is probably the most common way of formatting a DateTime as a string in C#. It allows you to optionally pass the format to use as a string parameter. For example:
using System;class MainClass { public static void Main (string[] args) { DateTime today = DateTime.Today; Console.WriteLine(today.ToString("yyyy-MM-dd")); }}You can read more information here.
Using string.Format()
You can also specify how a string should be formatted using string.Format() by passing in the DateTime object as one of the objects to be inserted. For example:
using System;class MainClass { public static void Main (string[] args) { var today = DateTime.Today; Console.WriteLine(string.Format("{0:yyyy-MM-dd}", today)); }}You can read more here.
Using String Interpolation
I prefer this method of formatting DateTime objects. It looks neat and is compact. Here’s an example:
using System;class MainClass { public static void Main (string[] args) { var today = DateTime.Today; Console.WriteLine($"{today:yyyy-MM-dd}"); }}You can read more about string interpolation here.
Custom DateTime Format Strings
We can format a DateTime using a custom format string. A format string is simply a string in C# where sequences of characters (called format specifiers) in the string dictate what portions of the DateTime should be outputted and how they should be formatted. These format specifiers can be combined to output multiple portions of a DateTime object (as well as other objects in .NET) in a single string. This gives you granular control over how DateTime objects should be outputted.
Below is a table of all the string sequences used in custom format strings for DateTime objects:
| Format Specifier | DateTime Segment | Description |
|---|---|---|
"g" or "gg" |
Era | Outputs the era ("B.C." or "A.D."). Note: Only use "g" for the era when it is used with other format specifiers in the same string (adding "''" will work) otherwise it is interpreted as a standard date and time format specifier. |
"y" |
Year | The year from 0 to 99 (excluding the century) without any leading zeros Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "3" for 0903-03-25T08:02:08.6170000 - "20" for 2020-06-07T13:45:32.0050000 |
"yy" |
Year | The year from 00 to 99 (excluding the century) with a leading zero where necessary so that the year is always two characters. Examples: - "03" for 0903-03-25T08:02:08.6170000 - "20" for 2020-06-07T13:45:32.0050000 |
"yyy" |
Year | The year, with a minimum of three digits. Examples: - "903" for 0903-03-25T08:02:08.6170000 - "2020" for 2020-06-07T13:45:32.0050000 |
"yyyy" |
Year | The year as a four-digit number. Examples: - "0903" for 1903-03-25T08:02:08.6170000 - "2020" for 2020-06-07T13:45:32.0050000 |
"yyyyy" |
Year | The year as a five-digit number. Examples: - "00903" for 1903-03-25T08:02:08.6170000 - "02020" for 2020-06-07T13:45:32.0050000 |
"M" |
Month | The month of the year (from 1 to 12) without any leading zeros. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "3" for 1903-03-25T08:02:08.6170000 - "6" for 2020-06-07T13:45:32.0050000 |
"MM" |
Month | The month of the year (from 01 to 12) with a leading zero. Examples: - "03" for 1903-03-25T08:02:08.6170000 - "06" for 2020-06-07T13:45:32.0050000 |
"MMM" |
Month | The abbreviated name of the month. This differs based on language and region. Examples: - "Mar" for 1903-03-25T08:02:08.6170000 (en-US) - "Jun" for 2020-06-07T13:45:32.0050000 (en-US) |
"MMMM" |
Month | The full name of the month. This differs based on language and region. Examples: - "March" for 1903-03-25T08:02:08.6170000 (en-US) - "June" for 2020-06-07T13:45:32.0050000 (en-US) |
"d" |
Day | The day of the month (from 1 to 31) without any leading zeros. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "25" for 1903-03-25T08:02:08.6170000 - "7" for 2020-06-07T13:45:32.0050000 |
"dd" |
Day | The day of the month (from 1 to 31) with a leading zero where necessary so that the date is always two characters. Examples: - "25" for 1903-03-25T08:02:08.6170000 - "07" for 2020-06-07T13:45:32.0050000 |
"ddd" |
Day | The abbreviated name of the day of the week. Examples: Mon, Tues |
"dddd" |
Day | The full name of the day of the week. Examples: Monday, Tuesday |
"t" |
AM/PM | The first character of the AM/PM designator. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "A" for 0903-03-25T08:02:08.6170000 - "P" for 2020-06-07T13:45:32.0050000 |
"tt" |
AM/PM | The AM/PM designator. Examples: - "AM" for 0903-03-25T08:02:08.6170000 - "PM" for 2020-06-07T13:45:32.0050000 |
"h" |
Hour | The hour, using a 12-hour clock (from 1 to 12) without a leading zero. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: 11 for 11:00:00AM, 1 for 1:00:00PM |
"hh" |
Hour | The hour, using a 12-hour clock (from 01 to 12) with a leading zero. Examples: 11 for 11:00:00AM, 01 for 1:00:00PM |
"H" |
Hour | The hour, using a 24-hour clock (from 0 to 23) without a leading zero. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: 9 for 9:00:00AM, 11 for 11:00:00AM, 13 for 1:00:00PM |
"HH" |
Hour | The hour, using a 24-hour clock (from 00 to 23) with a leading zero. Examples: 09 for 9:00:00AM, 11 for 11:00:00AM, 13 for 1:00:00PM |
"m" |
Minute | The minute, from 0 to 59, without a leading zero. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: 8 for 9:08:00AM, 20 for 1:20:00PM |
"mm" |
Minute | The minute, from 00 to 59, with a leading zero. Examples: 08 for 9:08:00AM, 20 for 1:20:00PM |
"s" |
Second | The second, from 0 to 59, without a leading zero. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: 3 for 9:08:03AM, 45 for 1:20:45PM |
"ss" |
Second | The second, from 00 to 59, with a leading zero. Examples: 03 for 9:08:03AM, 45 for 1:20:45PM |
"f" |
Fraction of Second | The tenths of a second, from 0 to 9 Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "6" for 1903-03-25T08:02:08.6170000 - "0" for 2020-06-07T13:45:32.0050000 |
"ff" |
Fraction of Second | The hundredths of a second, from 00 to 99 Examples: - "61" for 0903-03-25T08:02:08.6170000 - "00" for 2020-06-07T13:45:32.0050000 |
"fff" |
Fraction of Second | The milliseconds, from 000 to 999 Examples: - "617" for 0903-03-25T08:02:08.6170000 - "000" for 2020-06-07T13:45:32.0005000 |
"ffff" |
Fraction of Second | The ten thousandths of a second, from 0000 to 9999 Examples: - "6170" for 0903-03-25T08:02:08.6170000 - "0000" for 2020-06-07T13:45:32.0000500 |
"fffff" |
Fraction of Second | The hundred thousandths of a second, from 00000 to 99999 Examples: - "61700" for 0903-03-25T08:02:08.6170000 - "00000" for 2020-06-07T13:45:32.0000050 |
"ffffff" |
Fraction of Second | The millionths of a second, from 000000 to 999999 Examples: - "617000" for 0903-03-25T08:02:08.6170000 - "000000" for 2020-06-07T13:45:32.0000005 |
"fffffff" |
Fraction of Second | The ten millionths of a second, from 0000000 to 9999999 Examples: - "6170000" for 0903-03-25T08:02:08.6170000 - "0000000" for 2020-06-07T13:45:32.0000000 |
"F" |
Fraction of Second | The tenths of a second, from 0 to 9. Only outputted if the value is non-zero otherwise an empty is outputted. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "6" for 1903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0050000 |
"FF" |
Fraction of Second | The hundredths of a second, from 00 to 99. Only outputted if the value is non-zero otherwise an empty is outputted. Examples: - "61" for 0903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0050000 |
"FFF" |
Fraction of Second | The milliseconds, from 000 to 999. Only outputted if the value is non-zero otherwise an empty is outputted. Examples: - "617" for 0903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0005000 |
"FFFF" |
Fraction of Second | The ten thousandths of a second, from 0000 to 9999. Only outputted if the value is non-zero otherwise an empty is outputted. Examples: - "6170" for 0903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0000500 |
"FFFFF" |
Fraction of Second | The hundred thousandths of a second, from 00000 to 99999. Only outputted if the value is non-zero otherwise an empty is outputted. Examples: - "61700" for 0903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0000050 |
"FFFFFF" |
Fraction of Second | The millionths of a second, from 000000 to 999999. Only outputted if the value is non-zero otherwise an empty is outputted. Examples: - "617000" for 0903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0000005 |
"FFFFFFF" |
Fraction of Second | The ten millionths of a second, from 0000000 to 9999999. Only outputted if the value is non-zero otherwise an empty is outputted. Examples: - "6170000" for 0903-03-25T08:02:08.6170000 - "" for 2020-06-07T13:45:32.0000000 |
"K" |
Time zone | This depends on the Kind of DateTime object. Kinds: - Unspecified: "" - Utc: "Z" - Local: "+02:00" Note: This will only work when used with other format specifiers in the same string (adding "''" will work). |
"z" |
Time zone | Hours offset from UTC, with no leading zeros Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "+2" for 0903-03-25T08:02:08+02:00 - "-7" for 2020-06-07T13:45:32-07:00 |
"zz" |
Time zone | Hours offset from UTC, with a leading zero for single-digit values Examples: - "+02" for 0903-03-25T08:02:08+02:00 - "-07" for 2020-06-07T13:45:32-07:00 |
"zzz" |
Time zone | Hours and minutes offset from UTC Examples: - "+02:00" for 0903-03-25T08:02:08+02:00 - "-07:00" for 2020-06-07T13:45:32-07:00 |
"/" |
Misc | The date separator. This is determined based on the region and language. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - "/" for 0903-03-25T08:02:08+02:00 (en-US) - "-" for 2020-06-07T13:45:32-07:00 (ar-DZ) |
":" |
Misc | The time separator. This is determined based on the region and language. Note: This will only work when used with other format specifiers in the same string (adding "''" will work). Examples: - ":" for 0903-03-25T08:02:08+02:00 (en-US) - "." for 2020-06-07T13:45:32-07:00 (it-IT) |
"'<STRING>'" |
Misc | Literal string delimiter. This can be used to escape a string. |
"\<CHAR>" |
Misc | Escape character. This can be used to escape a single character in a format specifier |
Here’s a code snippet demonstrating all the formats described above:
using System;class MainClass { public static void Main(string[] args) { var today = DateTime.Now; Console.WriteLine($"Using date and time: {today.ToString(@"yyyy-MM-dd\THH:mm:ss.fffffffK")}"); Console.WriteLine(); // Individual Format Specifiers Console.WriteLine("Individual Format Specifiers"); Console.WriteLine($"1. {today.ToString("gg")}"); Console.WriteLine($"2. {today.ToString("''y")}"); Console.WriteLine($"3. {today.ToString("yy")}"); Console.WriteLine($"4. {today.ToString("yyy")}"); Console.WriteLine($"5. {today.ToString("yyyy")}"); Console.WriteLine($"6. {today.ToString("yyyyy")}"); Console.WriteLine($"7. {today.ToString("''M")}"); Console.WriteLine($"8. {today.ToString("MM")}"); Console.WriteLine($"9. {today.ToString("MMM")}"); Console.WriteLine($"10. {today.ToString("MMMM")}"); Console.WriteLine($"11. {today.ToString("''d")}"); Console.WriteLine($"12. {today.ToString("dd")}"); Console.WriteLine($"13. {today.ToString("ddd")}"); Console.WriteLine($"14. {today.ToString("dddd")}"); Console.WriteLine($"15. {today.ToString("''t")}"); Console.WriteLine($"16. {today.ToString("tt")}"); Console.WriteLine($"17. {today.ToString("''h")}"); Console.WriteLine($"18. {today.ToString("hh")}"); Console.WriteLine($"19. {today.ToString("''H")}"); Console.WriteLine($"20. {today.ToString("HH")}"); Console.WriteLine($"21. {today.ToString("''m")}"); Console.WriteLine($"22. {today.ToString("mm")}"); Console.WriteLine($"23. {today.ToString("''s")}"); Console.WriteLine($"24. {today.ToString("ss")}"); Console.WriteLine($"25. {today.ToString("''f")}"); Console.WriteLine($"26. {today.ToString("ff")}"); Console.WriteLine($"27. {today.ToString("fff")}"); Console.WriteLine($"28. {today.ToString("ffff")}"); Console.WriteLine($"29. {today.ToString("fffff")}"); Console.WriteLine($"30. {today.ToString("ffffff")}"); Console.WriteLine($"31. {today.ToString("fffffff")}"); Console.WriteLine($"32. {today.ToString("''F")}"); Console.WriteLine($"33. {today.ToString("FF")}"); Console.WriteLine($"34. {today.ToString("FFF")}"); Console.WriteLine($"35. {today.ToString("FFFF")}"); Console.WriteLine($"36. {today.ToString("FFFFF")}"); Console.WriteLine($"37. {today.ToString("FFFFFF")}"); Console.WriteLine($"38. {today.ToString("FFFFFFF")}"); Console.WriteLine($"39. {today.ToString("''K")}"); Console.WriteLine($"40. {today.ToString("''z")}"); Console.WriteLine($"41. {today.ToString("zz")}"); Console.WriteLine($"42. {today.ToString("zzz")}"); Console.WriteLine($"43. {today.ToString("''/")}"); Console.WriteLine($"44. {today.ToString("'':")}"); Console.WriteLine($"45. {today.ToString("'The date is' yyyy-MM-dd")}"); Console.WriteLine($"46. {today.ToString(@"\T\h\e \d\a\t\e \i\s yyyy-MM-dd")}"); Console.WriteLine(); // Combined Format Specifiers Console.WriteLine("Combined Format Specifiers"); Console.WriteLine($"47. {today.ToString("yyyy-MM-dd")}"); Console.WriteLine($"48. {today.ToString("d MMMM yyyy")}"); Console.WriteLine($"49. {today.ToString("dddd, d MMMM yyyy")}"); Console.WriteLine($"50. {today.ToString("hh:mm:ss tt")}"); Console.WriteLine($"51. {today.ToString("HH:mm:ss.fffffff")}"); }}Conclusion
C# comes with helpful default formatting options when working with DateTime objects. However, you’re not limited to these defaults. The DateTime object can be formatted using various format specified, giving you the flexibility to format the date and time any way you choose.