The Special Case of XML
Found at
http://msdn.microsoft.com/netframew.../library/en-us/dndotnet/html/datetimecode.asp
Several people I've talked to recently had the design goal of
serializing time values over Web services such that the XML that
represents the DateTime would be formatted in GMT (e.g., with a zero
offset). While I've heard various reasons ranging from the desire to
simply parse the field as a text string for display in a client to
wanting to preserve the "stored in UCT" assumptions that exist on the
server to the callers of Web services, I've not been convinced that
there is ever a good reason to control the marshalling format on the
wire to this degree. Why? Simply because the XML encoding for a DateTime
type is perfectly adequate for representing an instant in time, and the
XML serializer that is built into the .NET Framework does a fine job of
managing the serialization and deserialization issues associated with
time values.
Further, it turns out that forcing the System.XML.Serialization
serializer to encode a date value in GMT on the wire is not possible in
..NET, at least not today. As a programmer, designer, or project
manager, your job then becomes making sure that the data that is being
passed in your application is performed accurately with a minimum of
cost.
Several of the groups I talked with in the research that went into this
paper had adopted the strategy of defining special classes and writing
their own XML serializers so that they have full control over what the
DateTime values on the wire looked like in their XML. While I admire the
pluck that developers have when making the leap into this brave
undertaking, rest assured that the nuances of dealing with daylight
savings time and time zone conversion issues alone should make a good
manager say, "No way," especially when the mechanisms provided in the
..NET Framework do a perfectly accurate job of serializing time values
already.
There is only one trick you have to be aware of, and as a designer you
MUST understand this and adhere to the rule (see Rule #5).
Code that doesn't work:
Let's first define a simple XML class with a DateTime member variable.
For completeness, this class is the simplified equivalent of the
recommended approach illustrated later in the article.
<XmlType(TypeName:="timeTestDef", _
Namespace:= "
http://tempuri.org/Timetester.xsd")>), _
XmlRoot(), Serializable()> _
Public Class timeTestDef
Private __timeVal As DateTime
<XmlIgnore()> _
Public timeValSpecified As Boolean
<XmlElement(ElementName:="timeVal", IsNullable:=False, _
Form:=XmlSchemaForm.Qualified, DataType:="dateTime", _
Namespace:="
http://tempuri.org/Timetester.xsd")> _
Public Property timeVal() As DateTime
Get
timeVal = __timeVal
End Get
Set(ByVal Value As DateTime)
__timeVal = Value
timeValSpecified = True
End Set
End Property
End Class
Now, let's use this class to write some XML to a file.
' write out to the file
Dim t As Xml.XmlTextWriter
Dim ser As XmlSerializer
Dim tt As New timeTest ' a class that has a DateTime variable
' set the fields in your class
tt.timeVal = DateTime.Parse("12/12/2003 12:01:02 PM")
tt.timeVal = tt.TimeVal.ToUniversalTime()
' get a serializer for the root type, and serialize this UTC time
ser = New XmlSerializer(GetType(timeTest))
t = New Xml.XmlTextWriter("c:\timetest.xml", System.Text.Encoding.UTF8)
ser.Serialize(t, tt)
t.Close()
t = Nothing
tt = Nothing
When this code runs, the XML that is serialized to the output file
contains an XML DateTime representation as follows:
<timeVal>2003-12-12T20:01:02.0000000-08:00</timeVal>
This is an error: the value encoded in the XML is off by eight hours!
Since this happens to be the time zone offset of my current machine, we
should be suspicious. Looking at the XML itself, the date is right, and
the 20:01:02 date corresponds to the clock time in London for my own
noontime, but the offset portion is not correct for a London-based
clock. When the XML looks like the London time, the offset should also
represent the London viewpoint, which this code doesn't achieve.
The XML serializer always assumes that DateTime values being serialized
represent local machine time, so it applies the machine local time zone
offset as the offset portion of the encoded XML time. When we
deserialize this onto another machine, the original offset is subtracted
from the value being parsed, and the current machine's time-zone offset
is added.
When we start with a local time, the result of serialization (encode to
XML DateTime followed by decode to local machine time) is always
correct-but only if the starting DateTime value being serialized
represents local time when serialization begins. In the case of this
broken code example, we had already adjusted the DateTime value in the
timeVal member variable to UCT time, so when we serialize and
deserialize, the result is off by the number of hours equal to the
time-zone offset of the originating machine. This is bad.
Best Practice #4
When testing, calculate the value you expect to see in the XML string
that is serialized using a machine local time view of the point in time
being tested. If the XML in the serialization stream differs, log a bug!
Fixing this code is simple. Comment out the line that calls
ToUniversalTime().
Best Practice #5
When writing code to serialize classes that have DateTime member
variables, the values must represent local time. If they do not contain
local time, adjust them prior to any serialization step, including
passing or returning types that contain DateTime values in Web services.
The Class Coders Quandary
Earlier we looked at a pretty unsophisticated class that exposed a
DateTime property. In that class, we simply serialized what we stored in
a DateTime, without regard to whether the value represented a local or
universal time viewpoint. Let's look at a more sophisticated approach
that offers programmers an overt choice as to what time-zone assumptions
they desire, while always serializing properly.
When coding a class that will have a member variable of type DateTime, a
programmer has a choice of making the member variable public or writing
the property logic to wrap the member variable with get/set operations.
Choosing to make the type public has several disadvantages that, in the
case of DateTime types, can have consequences that are not under the
class developer's control.
Using what we learned so far, consider instead providing two properties
for each DateTime type.
The following example illustrates the recommended approach to managing
DateTime member variables:
<XmlType(TypeName:="timeTestDef", _
Namespace:= "
http://tempuri.org/Timetester.xsd")>), _
XmlRoot(), Serializable(), _
EditorBrowsable(EditorBrowsableState.Advanced)> _
Public Class timeTestDef
Private __timeVal As DateTime
<XmlIgnore()> _
Public timeValSpecified As Boolean
<XmlElement(ElementName:="timeVal", IsNullable:=False, _
Form:=XmlSchemaForm.Qualified, DataType:="dateTime", _
Namespace:="
http://tempuri.org/Timetester.xsd")> _
Public Property timeVal() As DateTime
Get
timeVal = __timeVal.ToLocalTime()
End Get
Set(ByVal Value As DateTime)
__timeVal = Value.ToUniversalTime()
timeValSpecified = True
End Set
End Property
<XmlIgnore()> _
Public Property timeValUTC() As DateTime
Get
timeValUTC = __timeVal
End Get
Set(ByVal Value As DateTime)
__timeVal = Value
timeValSpecified = True
End Set
End Property
End Class
This example is the corrected equivalent to the prior class
serialization example. In both class examples (this one and the earlier
one), the classes are implementations that are described with the
following schema:
<?xml version="1.0" encoding="utf-8" ?>
<xs:schema id="Timetester"
targetNamespace="
http://tempuri.org/Timetester.xsd"
elementFormDefault="qualified"
xmlns="
http://tempuri.org/Timetester.xsd"
xmlns:mstns="
http://tempuri.org/Timetester.xsd"
xmlns:xs="
http://www.w3.org/2001/XMLSchema">
<xs:element name="timeTest" type="timeTestDef"/>
<xs:complexType name="timeTestDef">
<xs:sequence>
<xs:element name="timeVal" type="xs:dateTime"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
In this schema, and in any class implementations, we define a member
variable that represents an optional time value. In our recommended
example, we have provided two properties with both getters and
setters-one for the universal time and one for local time. The
angle-bracketed attributes that you see in the code tell the XML
serializer to use the local time version for serialization, and
generally make the class implementation result in schema-compliant
output. To make the class properly deal with the optional lack of
expression when no value is set in the instance, the timeValSpecified
variable and associated logic in the property setter controls whether
the XML element is expressed at serialization time or not. This optional
behavior exploits a feature in the serialization subsystem that was
designed to support optional XML content.
Using this approach to managing DateTime values in your .NET classes
gives you the best of both worlds-you get storage access based on
universal time so that calculations are accurate, and you get proper
serialization of local time views.
Best Practice #6
When coding, make DateTime member variables private and provide two
properties for manipulating your DateTime members in either local or
universal time. Bias the storage in the private member as UCT time by
controlling the logic in your getters and setters. Add the XML
serialization attributes to the local time property declaration to make
sure that the local time value is what is serialized (see example).
Caveats to this approach
The recommended approach of managing a DateTime in Universal time within
your private member variables is sound, as is the recommendation to
provide dual properties to allow coders to deal with the versions of
time that they are most comfortable with. One issue that a developer
using this or any other approach that exposes any local time to a
program continues to be the 25-hour-day issue around daylight savings
time. This will continue to be an issue for programs that use CLR
version 1.0 and 1.1, so you have to be aware as to whether your program
falls into this special case (the added or missing hour for the time
being represented), and adjust manually. For those who cannot tolerate a
one-hour per year issue window, the current recommendation is to store
your dates as strings or some other self-managed approach. (Unix long
integers are a good option.)
For CLR version 2.0 (available in the upcoming release of Visual StudioR
code-named "Whidbey"), awareness of whether a DateTime contains a local
time or a universal time value is being added to the .NET Framework. At
that point, the recommended pattern will continue to work, but for
programs that interact with member variables via the UTC properties,
these errors in the missing/extra hour period will be eliminated. For
this reason, the best practice for coding using dual properties is
strongly suggested today, so that your programs will migrate cleanly to
CLR version 2.0.
