DateTime.TryParse And The Case Of Z Letter

Recently, I’ve been tasked to provide data in a specific format from the backend to the frontend and I noticed a behavior that I found a bit odd.
  1. private static void OutputDateInfo(string value)  
  2. {  
  3.     Console.WriteLine($"Input: {value}");  
  4.     if (DateTime.TryParse(value, out DateTime dateTimeValue))  
  5.     {  
  6.         Console.WriteLine($"Setialized to universal format   
  7.                 {dateTimeValue.ToString("yyyy-MM-dd'T'HH:mm:ssZ")}");  
  8.     }  
  9.     Console.WriteLine();  
  10. }  
  11.   
  12. //somewhere in main  
  13. OutputDateInfo("2021-04-15T21:01:00.0000000Z");  
  14. OutputDateInfo("2021-04-15T21:01:00.0000000");  
produces the output,
  1. Input: 2021-04-15T21:01:00.0000000Z    
  2. Serialized to universal format 2021-04-16T00:01:00Z    
  3.     
  4. Input: 2021-04-15T21:01:00.0000000    
  5. Serialized to universal format 2021-04-15T21:01:00Z     
So as I was in Kyiv which is in UTC+3 timezone it looked as letter Z forced the ToString method to convert date to local time.
 
As documentation reads,
 
If s contains no time zone information, the result contains a DateTime value whose Kind property is DateTimeKind.Unspecified when the method returns. If the string to be parsed contains time zone information, the result contains a DateTime value whose Kind property is DateTimeKind.Local when the method returns.
 
Is this DateTimeKind that makes ToString cast date to the local timezone? Let’s log more properties to see if it is the case,
  1. private static void OutputDateInfo(string value)  
  2. {  
  3.     Console.WriteLine($"Input: {value}");  
  4.     if (DateTime.TryParse(value, out DateTime dateTimeValue))  
  5.     {  
  6.         Console.WriteLine($"Setialized to universal format   
  7.                          {dateTimeValue.ToString("yyyy-MM-dd'T'HHssZ")}");  
  8.         Console.WriteLine($"Setialized to default format {dateTimeValue}");  
  9.         Console.WriteLine($"Setialized with conversion to universal time   
  10.                          {dateTimeValue.ToUniversalTime()}");  
  11.         Console.WriteLine($"Kind: {dateTimeValue.Kind}");  
  12.     }  
  13.     Console.WriteLine();  
  14. }  
Now we see in a console,
  1. Input: 2021-04-15T21:01:00.0000000Z    
  2. Serialized to universal format 2021-04-16T00:01:00Z    
  3. Serialized to default format 16.04.2021 0:01:00    
  4. Serialized with conversion to universal time 15.04.2021 21:01:00    
  5. Kind: Local    
  6.     
  7. Input: 2021-04-15T21:01:00.0000000    
  8. Serialized to universal format 2021-04-15T21:01:00Z    
  9. Serialized to default format 15.04.2021 21:01:00    
  10. Serialized with conversion to universal time 15.04.2021 18:01:00    
  11. Kind: Unspecified     
So indeed when we call ToString on a DateTimeKind.Local instance, it will be adjusted according to server timezone.
 
But why letter Z is treated as timezone information? The documentation referred to above has no example with Z letter. The answer is that format in question is ISO-8601 format and Z stands for “Zero UTC offset”. Is the string of this format treated just as any other string with timezone specified or is this some kind of special treatment? We’ll get an answer by comparing them,
  1. OutputDateInfo("2021-04-15T2100.0000000Z");  
  2. OutputDateInfo("2021-04-15T2100.0000000");  
  3. OutputDateInfo("2021-04-15T1400.0000000 -7:00");  
yields,
  1. Input: 2021-04-15T21:01:00.0000000Z    
  2. Serialized to universal format 2021-04-16T00:01:00Z    
  3. Serialized to default format 16.04.2021 0:01:00    
  4. Serialized with conversion to universal time 15.04.2021 21:01:00    
  5. Kind: Local    
  6.     
  7. Input: 2021-04-15T21:01:00.0000000    
  8. Serialized to universal format 2021-04-15T21:01:00Z    
  9. Serialized to default format 15.04.2021 21:01:00    
  10. Serialized with conversion to universal time 15.04.2021 18:01:00    
  11. Kind: Unspecified    
  12.     
  13. Input: 2021-04-15T14:01:00.0000000 -7:00    
  14. Serialized to universal format 2021-04-16T00:01:00Z    
  15. Serialized to default format 16.04.2021 0:01:00    
  16. Serialized with conversion to universal time 15.04.2021 21:01:00    
  17. Kind: Local     
As you can see, a string of ISO-8601 format is treated just like any other date string with a timezone specified.
 
My intent though wasn’t to treat it as local time but instead as UTC time. My goal was to provide universal time to the front end so it will adjust it to end-users local time. How can we trick .NET into thinking that this is universal time without any timezone? The answer is the overload that accepts DateTimeStyles:
  1. private static void OutputDateInfo(string value)  
  2. {  
  3.     Console.WriteLine($"Input: {value}");  
  4.     if (DateTime.TryParse(value, null, DateTimeStyles.AdjustToUniversal,   
  5.                           out DateTime universalTime))  
  6.     {  
  7.         Console.WriteLine($"Adjusted to universal {universalTime}");  
  8.     }  
  9.   
  10.     Console.WriteLine();  
  11. }  
Outputs
  1. Input: 2021-04-15T21:01:00.0000000Z  
  2. Adjusted to universal 15.04.2021 21:01:00  
  3.   
  4. Input: 2021-04-15T21:01:00.0000000  
  5. Adjusted to universal 15.04.2021 21:01:00  
  6.   
  7. Input: 2021-04-15T14:01:00.0000000 -7:00  
  8. Adjusted to universal 15.04.2021 21:01:00  
Job done!
 

Conclusion

 
In my opinion, DateTimeKind is underrepresented in literature and blogs. However, this is the thing that should definitely be taken into account when parsing date strings and converting dates back to a string. Also, it is worth remembering that ISO-8601 format date strings are treated just like any other string with timezone info specified, although it might be unobvious at first glance.