Converting Date and Time Values

Microsoft Windows® SharePoint™ Services 2.0 stores date and time values in Coordinated Universal Time (UTC), and almost all date and time values that are returned by members of the object model are in UTC. The one exception is list column values that are obtained through the indexer for the SPListItem class, which are in the local time for the site. Use the DatesInUtc property of the SPQuery class to use the indexer to return values in UTC.

To convert values to local time from UTC, use the UTCToLocalTime method of the SPTimeZone class, which can be accessed through the RegionalSettings property for the current site, as follows: mySite.RegionalSettings.TimeZone.UtcTimeToLocalTime(date). To convert values from local time to UTC, instead use the LocalTimeToUTC method.

In addition to converting between local and UTC time, you may also need to convert between date and time formats, for example, from ISO8601 format (YYYY-MM-DDTHH:MM:SSZ) to System.DateTime format (mm/dd/yyyy hh:mm:ss AM or PM), or vice versa. The SPUtility class provides several methods that can be used to convert or modify the format of date and time values, such as the following:

• CreateISO8601DateTimeFromSystemDateTime — from system DateTime format to ISO8601 DateTime format (yyyy-mm-ddThh:mm:ssZ). This method is useful, for example, when building a query with a filter based on a System.DateTime value. The following example returns all items in a document library that have been modified in the past five days:

  [Visual Basic .NET]
  
  Dim query As New SPQuery()
  
  query.Query = String.Format("<Where><Gt><FieldRef Name='Modified'/>" _
      & "<Value Type='DateTime' StorageTZ='TRUE'>{0}</Value></Gt></Where>", _
      SPUtility.CreateISO8601DateTimeFromSystemDateTime(DateTime.UtcNow.AddDays(-5)))
  
  [C#]
  
  SPQuery query = new SPQuery();
  
  query.Query = String.Format("<Where><Gt><FieldRef Name='Modified'/>" +
      "<Value Type='DateTime' StorageTZ='TRUE'>{0}</Value></Gt></Where>",
      SPUtility.CreateISO8601DateTimeFromSystemDateTime(DateTime.UtcNow.AddDays(-5)));
  

  In the example, the CreateISO8601DateTimeFromSystemDateTime method converts a DateTime value to ISO8601 format for use within a query string in Collaborative Application Markup Language (CAML). The Format method of System.String inserts the converted value into the query string.

• CreateSystemDateTimeFromXmlDataDateTimeFormat — from ISO8601 DateTime format to System.DateTime format (opposite of the previous method).

  This method can be used, for example, in a document library event handler where custom DateTime column values are returned through the PropertiesBefore and PropertiesAfter properties of the SPListEvent class as strings in ISO8601 format. This method can be used to convert the strings to a DateTime value.

• FormatDate — from System.DateTime format to a specified SPDateFormat format using the current regional settings of the site.

• ParseDate — from the specified strings containing date and time values to a System.DateTime object using the current regional settings of the site.