{"id":63713,"date":"2022-01-20T07:00:52","date_gmt":"2022-01-20T06:00:52","guid":{"rendered":"https:\/\/drafts.code-maze.com\/?p=63713"},"modified":"2024-02-01T15:34:16","modified_gmt":"2024-02-01T14:34:16","slug":"convert-datetime-to-iso-8601-string-csharp","status":"publish","type":"post","link":"https:\/\/code-maze.com\/convert-datetime-to-iso-8601-string-csharp\/","title":{"rendered":"Convert DateTime to ISO 8601 String in C#"},"content":{"rendered":"

In this article, we are going to learn how to convert DateTime to ISO 8601 string in C#. There are various formats of ISO 8601 compliant date and time strings. We are going to build a console application and explore all these different formats.\u00a0<\/p>\n

To download the source code for this article, you can visit our GitHub repository<\/a>.<\/div>\n

Let’s start.<\/p>\n

Standard DateTime Format Strings<\/h2>\n

The standard DateTime<\/code> format specifier is the most convenient way to get an ISO 8601<\/a> output. While there are many standard format specifiers, only three of them can give us ISO 8601 compliant output: “s<\/strong>“, “o<\/strong>“, “u<\/strong>“.<\/p>\n

To begin, let’s update our Program<\/code> class and declare two DateTime<\/code> objects, one local and another as a UTC standard type:<\/p>\n

var localTime = new DateTime(2022, 1, 13, 16, 25, 35, 125, DateTimeKind.Local);\r\nvar utcTime = new DateTime(2022, 1, 13, 16, 25, 35, 125, DateTimeKind.Utc);\r\n<\/pre>\n
Now, let’s explore the different specifiers.<\/p>\n
Sortable Format Specifier (“s”)<\/h3>\n
The sortable format specifier (“s<\/strong>“) is useful to get an ISO 8601 compliant sortable string:<\/p>\n
Console.WriteLine($\"Local: {localTime.ToString(\"s\")}\"); \/\/ 2022-01-13T16:25:35\r\nConsole.WriteLine($\"UTC: {utcTime.ToString(\"s\")}\");     \/\/ 2022-01-13T16:25:35<\/pre>\n
This is the most common way of getting ISO 8601 compliant DateTime<\/code> strings.<\/p>\n
Round-trip Format Specifier (“o”)<\/h3>\n
The round-trip format specifier (“o<\/strong>“) is useful to get an ISO 8601 string which includes time-zone information:<\/p>\n
Console.WriteLine($\"Local: {localTime.ToString(\"o\")}\"); \/\/ 2022-01-13T16:25:35.1250000+06:00\r\nConsole.WriteLine($\"UTC: {utcTime.ToString(\"o\")}\");     \/\/ 2022-01-13T16:25:35.1250000Z<\/pre>\n
We can see that the output of localTime<\/code> includes the time-zone information at the end (+6:00<\/strong>) which is interpreted as UTC+06:00<\/code>. In contrast, utcTime<\/code> prints just ‘Z<\/strong>‘ at the end, which complies with the ISO 8601 standard for UTC+00:00<\/code> DateTime. In addition, the output contains the fraction of seconds part up to 7 digits. This is why round-trip format is recommended when accuracy is an important concern.<\/p>\n
Universal Format Specifier (“u”)<\/h3>\n
While working with DateTime<\/code>, it’s a common scenario to get the output directly in UTC value as well as in ISO 8601 compliant format. We can use the universal format specifier (“u<\/strong>“) for such cases.<\/p>\n
Unlike the previous two cases, we need slight customization here, so let’s create an extension method:<\/p>\n
public static string ToUniversalIso8601(this DateTime dateTime)\r\n{\r\n    return dateTime.ToUniversalTime().ToString(\"u\").Replace(\" \", \"T\");\r\n}<\/pre>\n
In this method, we convert the date to UTC value and then format it using ToString(\"u\")<\/code>. Furthermore, we replace whitespace with “T<\/strong>“. This is because ISO 8601 does not allow whitespace as the date-time separator but expects “T<\/strong>” instead. So, we have our extension method ready for standard ISO 8601 compliant UTC output:<\/p>\n
Console.WriteLine($\"Local: {localTime.ToUniversalIso8601()}\");  \/\/ 2022-01-13T10:25:35Z\r\nConsole.WriteLine($\"UTC: {utcTime.ToUniversalIso8601()}\");      \/\/ 2022-01-13T16:25:35Z<\/pre>\n
As expected, the resulting strings are all in UTC standard.<\/p>\n
Custom DateTime Format Strings<\/h2>\n
The standard C# format strings can’t cover all the output patterns that ISO 8601 supports.<\/strong> But, we have custom format strings<\/a> that can cover the majority of the cases.<\/p>\n
Similarly to the standard formats, we can simply call the ToString<\/code> method with the custom format:<\/p>\n
var output = localTime.ToString(\"yyyy-MM-ddTHH:mm:ssK\");<\/code><\/p>\n
Not all custom formats are ISO 8601 compliant.<\/strong> According to ISO 8601 rules, we can use various combinations of date and time formats as long as the format honors the chronological order of date and time components. There are certain other restrictions, too. For example, we can use “yyyy-MM” but not “yyyyMM” which is prohibited because of ambiguity.<\/p>\n
ISO 8601 Compliant Custom DateTime Formats<\/h3>\n
So, what are the supported formats then? Let’s have a look at this table of some compliant formats along with their effect on localTime<\/code>:<\/p>\n\n\n\n\n\t\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t
Format<\/th>Output<\/th>Type<\/th>\n<\/tr>\n<\/thead>\n
yyyy-MM-dd<\/td>2022-01-13<\/td>Calendar Date<\/td>\n<\/tr>\n
yyyyMMdd<\/td>20220113<\/td>Calendar Date<\/td>\n<\/tr>\n
yyyy-MM<\/td>2022-01<\/td>Calendar Date<\/td>\n<\/tr>\n
\u2013MM-dd<\/td>\u201301-13<\/td>Calendar Date<\/td>\n<\/tr>\n
\u2013MMdd<\/td>\u20130113<\/td>Calendar Date<\/td>\n<\/tr>\n
THH:mm:ss.fff<\/td>T16:25:35.125<\/td>Time<\/td>\n<\/tr>\n
THH:mm:ss<\/td>T16:25:35<\/td>Time<\/td>\n<\/tr>\n
THH:mm<\/td>T16:25<\/td>Time<\/td>\n<\/tr>\n
THH<\/td>T16<\/td>Time<\/td>\n<\/tr>\n
THHmmssfff<\/td>T162535125<\/td>Time<\/td>\n<\/tr>\n
yyyyMMddTHHmmssK<\/td>20220113T162535+06:00<\/td>Date and Time<\/td>\n<\/tr>\n
yyyyMMddTHHmm<\/td>20220113T1625<\/td>Date and Time<\/td>\n<\/tr>\n
yyyy-MM-ddTHH:mmZ<\/td>2022-01-13T16:25Z<\/td>Date and Time<\/td>\n<\/tr>\n
yyyyMMddTHHmmsszzz<\/td>20220113T162535+06:00<\/td>Date and Time<\/td>\n<\/tr>\n
yyyyMMddTHHmmsszz<\/td>20220113T162535+06<\/td>Date and Time<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n
Custom Formats with Time Zone<\/h3>\n
We’ve used several custom formats that include special characters ‘Z<\/strong>‘, ‘z<\/strong>‘, and ‘K<\/strong>‘. It’s worth knowing a bit more about them as they have an essential role in producing ISO 8601 compliant output with time-zone information.<\/p>\n
‘Z<\/strong>‘ does not have any special interpretation as a C# formatting literal<\/strong>, but does have special meaning from ISO 8601 perspective. Any date string with ‘Z<\/strong>‘ appended at the end implies that it represents a UTC DateTime<\/code>.<\/p>\n
In contrast, ‘z’ and ‘K’ are purely C# formatting literals that add time zone information based on the <\/strong>DateTimeKind<\/code> value associated with the DateTime<\/code> object<\/strong>. While ‘K<\/strong>‘ provides full time-zone phrase, ‘z<\/strong>‘ offers flexibility to print in a short phrase:<\/p>\n
var format = \"yyyy-MM-ddTHH:mm:ssK\";\r\nvar unspecified = new DateTime(2022, 1, 13, 16, 25, 30, DateTimeKind.Unspecified);\r\nvar utc = new DateTime(2022, 1, 13, 16, 25, 30, DateTimeKind.Utc);\r\nvar local = new DateTime(2022, 1, 13, 16, 25, 30, DateTimeKind.Local);\r\n\r\nConsole.WriteLine(unspecified.ToString(format));            \/\/ 2022-01-13T16:25:30\r\nConsole.WriteLine(utc.ToString(format));                    \/\/ 2022-01-13T16:25:30Z\r\nConsole.WriteLine(local.ToString(format));                  \/\/ 2022-01-13T16:25:30+06:00\r\nConsole.WriteLine(local.ToString(\"yyyy-MM-ddTHH:mm:sszz\")); \/\/ 2022-01-13T16:25:30+06<\/pre>\n
We can see that the time zones have been applied to the resulting strings as expected.<\/span><\/p>\n
Week Dates<\/h2>\n
ISO 8601 week date patterns are something that we can’t produce directly using format strings. So, we are going to build extension methods that can give us the desired outputs.<\/p>\n
Week dates can be presented in two forms:<\/p>\n