Converting Date and Time Values

Article
10/20/2016

Applies to: SharePoint Foundation 2010

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

To convert values from UTC format to local time, 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 format, instead use the LocalTimeToUTC method.

In addition to converting between local and UTC time formats, 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 the reverse. 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 that is 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.
```
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)))
```
```
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).

You can use this method, for example, in a document library event handler where custom DateTime column values are returned as strings in ISO8601 format through the PropertiesBefore and PropertiesAfter properties of the SPListEvent class. 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.

Share via

Converting Date and Time Values

See Also

Concepts

Additional resources