David Rickard's Tech Blog

DateTime and DateTimeOffset in .NET: Good practices and common pitfalls

RandomEngy — Sat, 07 Apr 2012 00:37:00 GMT

It becomes necessary to deal with dates and times in most .NET programs. A lot of programs use DateTime but that structure is frought with potential issues when you start serializing, parsing, comparing and displaying dates from different time zones and cultures. In this post I will go over these issues and the APIs and practices you should use to avoid them.

Background

The DateTime structure stores only two pieces of information: Ticks and Kind. 1 tick is 100 nanoseconds (10,000 ticks in a millisecond). The ticks counter represents how many 100ns ticks you are away from 1/1/0001 12:00 AM. It's the part that determines that it's April 6th, 2012, 3:32:07 PM.

Another bit of data is the Kind: represented as a DateTimeKind enumeration. Utc, Local and Unspecified are the possible values. Utc means that the ticks counter represents a Coordinated Universal Time (that doesn't change due to daylight savings or time zones). Local means that it represents the local time of whatever time zone the computer is set to. This one is sensitive to daylight savings. Note that a timezone offset is not built in to the DateTime structure. It can only get back to a real UTC time by checking the current time zone settings on the computer. ToUniversalTime() and ToLocalTime() will do these conversions. It will return a new DateTime value with the Ticks adjusted to get the correct year/month/day and with the requested type. Calling ToUniversalTime() on a UTC DateTime or ToLocalTime() on a Local DateTime has no effect. Remember that these functions are generating a new DateTime value and not modifying the original.

There's also a third type: Unspecified. This means we don't know whether it's local or UTC. All we know is the year, month, day, etc. When working with DateTime values, Unspecified is not very helpful since we don't know what to do when we want to get a local or UTC time from it. If you call ToUniversalTime() on one of these, it assumes that the type must have been Local and converts based on that. If you call ToLocalTime() it assumes that the type must have been UTC and converts in that direction.

DateTimeOffset is a newer structure. It is also based on ticks but instead of storing a Kind, it keeps track of the offset from UTC as a TimeSpan. A DateTimeOffset always knows what time zone it's in. Calling ToUniversalTime() will always result in a TimeSpan.Zero offset, and ToLocalTime() will convert and result in an offset of the user's current time zone.

Use DateTimeOffset, not DateTime

DateTime has countless traps in it that are designed to give your code bugs:

DateTime values with DateTimeKind.Unspecified are bad news. It's common for code to call ToUniversalTime() or ToLocalTime() to make sure it's got the date properly ready for storage or display respectively. If you call ToUniversalTime() it converts X hours in one direction, but if you call ToLocalTime() on it, it converts X hours in the opposite direction. Both of those can't possibly be correct.
DateTime doesn't care about UTC/Local when doing comparisons. It only cares about the number of Ticks on the objects. It could not care less that you've lovingly specified that value A is most certainly UTC and value B is local; it won't do any conversions for you. 7:30 AM Local is always going to be evaluated as less than 8:22 AM UTC, even if your timezone is EDT and really the first time was 11:30 AM UTC.
DateTime values are not aware of standard format strings. For instance the "r" (RFC1123, the format used in HTTP headers) and "u" (universal sortable) formats both put UTC markers in the string you serialize to. If you call .ToString("u") on a local time, DateTime will happily label your local time as UTC without doing any conversion. The basically guarantees disaster when it gets parsed back in again.
Parsing a string that has a UTC marker with DateTime does not guarantee a UTC time. If you run DateTime.Parse("2012-04-06 23:46:23Z") you might expect the result to be a UTC DateTime since the "Z" UTC flag is right there in the string, but you do not. It will correctly note that it is dealing with a UTC time, then promptly convert it to a Local time. It's still technically correct, but it can result in the hours count changing when you are not expecting it to.

But DateTimeOffset doesn't have any of these problems! It's the newer, more robust version; think of it as DateTime v2. They couldn't fix the old DateTime object because that might break existing code that was relying on the bad behavior.

So you'll want to use DateTimeOffset in any situation that you're referring to a specific point in time. You might still use DateTime for things like general dates (July 4th, 1776) or store hours (9AM-5PM), since they are not affected by time zones.

Pick the right format when serializing

It's common to convert DateTimeOffset values to strings for storage or sending them somewhere else. The list of standard date and time format strings is helpful when you are contemplating how to do this. These are used with the DateTimeOffset.ToString method: for example myDate.ToString("u"). Note how with most of the standard formats you get different values for different cultures: different month names, swapped month/day places, etc. If you use one of these to serialize and Parse back in, it might work if you have the same culture on both sides, but will break if one side uses a different culture. You can get failed parses or swapped month/day values. Only the "o", "r", "s" and "u" formats are culture-invariant. Use one of those for serialization:

Format string	Name	Example
"o"	Round-trip	2012-04-17T16:46:48.0820143+00:00 (UTC) 2012-04-17T09:46:48.0820143-07:00 (local)	The only format that preserves the DateTimeOffset fully. The others round to the nearest second.
"r"	RFC1123	Tue, 17 Apr 2012 16:46:48 GMT	Used for HTTP headers
"u"	Universal sortable	2012-04-17 16:46:48Z
"s"	Sortable	2012-04-17T16:46:48 (UTC) 2012-04-17T09:46:48 (local)	Not a great format for this use as it has no timezone or UTC marker and can change based on what offset you have

Conclusion

Use DateTimeOffset and be careful with serialization. If you're dealing with legacy code that's using DateTime, be aware of all the timezone-related pitfalls when comparing, serializing, parsing and converting.

One final issue...

If it is Coordinated Universal Time, why is the acronym UTC and not CUT? When the English and the French were getting together to work out the notation, the french wanted TUC, for Temps Universel Coordonné. UTC was a compromise: it fit equally badly for each language. :)

Using the Dispatcher with MVVM

RandomEngy — Thu, 01 Apr 2010 03:27:00 GMT

When writing an MVVM application, you want to separate from the UI. However you also need to make sure that UI updates happen on the UI thread. Changes made through INotifyPropertyChanged get automatically marshaled to the UI thread, so in most cases you’ll be fine. However, when using INotifyCollectionChanged (such as with an ObservableCollection), these changes are not marshaled to the UI thread.

This means that unless you modify your collection on the UI thread, you’ll get a cross threading error. Thus the problem. We’re in the ViewModel and we don’t have access to the Dispatcher. That’s on a View object. How do we update the collection on the UI thread?

I came up with a small static class to help with this:

public static class DispatchService
{
    public static void Invoke(Action action)
    {
        Dispatcher dispatchObject = Application.Current.Dispatcher;
        if (dispatchObject == null || dispatchObject.CheckAccess())
	{
            action();
        }
        else
        {
            dispatchObject.Invoke(action);
        }
    }
}

When your ViewModel gives the DispatchService actions, it can run them on the correct thread. Which is, in the case of unit tests, always the current thread. A call to the DispatchService may look like this:

DispatchService.Invoke(() =>
{
    this.MyCollection.Add("new value");
});

The use of a simple lambda statement makes it a relatively lightweight way of updating on the correct thread.

Saving window size and location in WPF and WinForms

RandomEngy — Tue, 09 Mar 2010 03:18:00 GMT

A common user interface tweak is to save the size and location of a window and restore that state when the program starts up again. That way, the users don’t need to re-do their work of resizing and moving the windows to where they want them. However I’ve found that there isn’t really a convenient way to do with in C#. Many solutions focus on recording the window width, height, x and y coordinates and current state (maximized, restored, etc), then applying all those values again on startup. But then you have to deal with edge cases: What if the user has changed resolutions since your program last ran? What if it was present on a monitor that’s now disconnected?

Fortunately, there are a couple of native Windows functions that can do all this work for us: SetWindowPlacement and GetWindowPlacement. MSDN has a sample demonstrating how to PInvoke to these functions in a WPF project, but it’s got a few issues with it. For one, it’s trying to store the placement as a custom type in settings, which can cause strange errors every time you open your Settings file. Here’s my take on it:

using System;
using System.IO;
using System.Runtime.InteropServices;
using System.Text;
using System.Xml;
using System.Xml.Serialization;

namespace WindowPlacementExample
{
    // RECT structure required by WINDOWPLACEMENT structure
    [Serializable]
    [StructLayout(LayoutKind.Sequential)]
    public struct RECT
    {
        public int Left;
        public int Top;
        public int Right;
        public int Bottom;

        public RECT(int left, int top, int right, int bottom)
        {
            this.Left = left;
            this.Top = top;
            this.Right = right;
            this.Bottom = bottom;
        }
    }

    // POINT structure required by WINDOWPLACEMENT structure
    [Serializable]
    [StructLayout(LayoutKind.Sequential)]
    public struct POINT
    {
        public int X;
        public int Y;

        public POINT(int x, int y)
        {
            this.X = x;
            this.Y = y;
        }
    }

    // WINDOWPLACEMENT stores the position, size, and state of a window
    [Serializable]
    [StructLayout(LayoutKind.Sequential)]
    public struct WINDOWPLACEMENT
    {
        public int length;
        public int flags;
        public int showCmd;
        public POINT minPosition;
        public POINT maxPosition;
        public RECT normalPosition;
    }

    public static class WindowPlacement
    {
        private static Encoding encoding = new UTF8Encoding();
        private static XmlSerializer serializer = new XmlSerializer(typeof(WINDOWPLACEMENT));

        [DllImport("user32.dll")]
        private static extern bool SetWindowPlacement(IntPtr hWnd, [In] ref WINDOWPLACEMENT lpwndpl);

        [DllImport("user32.dll")]
        private static extern bool GetWindowPlacement(IntPtr hWnd, out WINDOWPLACEMENT lpwndpl);

        private const int SW_SHOWNORMAL = 1;
        private const int SW_SHOWMINIMIZED = 2;

        public static void SetPlacement(IntPtr windowHandle, string placementXml)
        {
            if (string.IsNullOrEmpty(placementXml))
            {
                return;
            }

            WINDOWPLACEMENT placement;
            byte[] xmlBytes = encoding.GetBytes(placementXml);

            try
            {
                using (MemoryStream memoryStream = new MemoryStream(xmlBytes))
                {
                    placement = (WINDOWPLACEMENT)serializer.Deserialize(memoryStream);
                }

                placement.length = Marshal.SizeOf(typeof(WINDOWPLACEMENT));
                placement.flags = 0;
                placement.showCmd = (placement.showCmd == SW_SHOWMINIMIZED ? SW_SHOWNORMAL : placement.showCmd);
                SetWindowPlacement(windowHandle, ref placement);
            }
            catch (InvalidOperationException)
            {
                // Parsing placement XML failed. Fail silently.
            }
        }

        public static string GetPlacement(IntPtr windowHandle)
        {
            WINDOWPLACEMENT placement = new WINDOWPLACEMENT();
            GetWindowPlacement(windowHandle, out placement);

            using (MemoryStream memoryStream = new MemoryStream())
            {
                using (XmlTextWriter xmlTextWriter = new XmlTextWriter(memoryStream, Encoding.UTF8))
                {
                    serializer.Serialize(xmlTextWriter, placement);
                    byte[] xmlBytes = memoryStream.ToArray();
                    return encoding.GetString(xmlBytes);
                }
            }
        }
    }
}

To get the placement of an existing window, you give it the native handle for the window, and get back a string of XML that represents the placement for the window. You save this string somewhere, then when the program starts back up again, apply it with SetPlacement. The above code works for both WinForms and WPF. And in both cases you can open your Properties/Settings.settings file and add a new setting to store the string:

This will store the window state locally, per-user. Of course you could also store the string wherever you wanted to.

What I like about this approach is that the WindowPlacement class does the XML serialization for you and gives you a nice, tidy string containing all the placement data.

But where in the program code should we hook in to save and re-apply the window placements? The answer is a bit different between WinForms and WPF.

WPF:

You might benefit by throwing a couple of extension methods on the WindowPlacement class to make things a bit easier:

public static void SetPlacement(this Window window, string placementXml)
{
    WindowPlacement.SetPlacement(new WindowInteropHelper(window).Handle, placementXml);
}

public static string GetPlacement(this Window window)
{
    return WindowPlacement.GetPlacement(new WindowInteropHelper(window).Handle);
}

To save the window placement, just handle the Closing event on the Window:

private void Window_Closing(object sender, CancelEventArgs e)
{
    Settings.Default.MainWindowPlacement = this.GetPlacement();
    Settings.Default.Save();
}

To restore, you’ll need to hook in on SourceInitialized:

protected override void OnSourceInitialized(EventArgs e)
{
    base.OnSourceInitialized(e);
    this.SetPlacement(Settings.Default.MainWindowPlacement);
}

WinForms:

This one is a bit more straightforward. Save on the FormClosing event and restore the window state in the Load event handler. The Form’s native handle is accessible from its Handle property.

Now we have a robust and relatively painless way of persisting window sizes and positions, and we only need to keep track of one string per window.