What Time is it anyway?

  • Article

DateTime property values off of objects returned from the Operations Manager (OM) SDK are in UTC time. At the time of this writing the "Kind" property of these values is not populated. This may seem trivial or irrelevant but it raises some questions as to how Cmdlets designed to take DateTime values should treat values that do not specify the "Kind" property. Consider the following example.

Monitoring:\localhost\Microsoft.SystemCenter.AllComputersGroup
> $time = [DateTime]::Now

>$time
Monday, November 27, 2006 6:35:10 PM

>$time.Kind
Local

>New-MaintenanceWindow -startTime: ($time) -endTime: ($time.AddDays(1)) -reason: "ApplicationInstallation" -comment: "Testing DateTime.Now";

>Monitoring:localhost\>Get-MaintenanceWindow MonitoringObjectId : 3c8ac4f3-475e-44dd-4163-8a97af363705

StartTime : 11/28/2006 2:35:12 AM
ScheduledEndTime : 11/29/2006 2:35:12 AM
EndTime
Reason : ApplicationInstallation
Comments : testing DateTime.Now
User : SMX\asttest
LastModified : 11/28/2006 2:35:12 AM
ManagementGroup : rogers01dmg
ManagementGroupId : 4e2f3ced-4b50-3939-edac-b9dfabe5effa

Clearly some conversion has occurred here. The value from [DateTime]::Now is in local time. The New-MaintenanceWindow Cmdlet converts the local time to UTC time before creating the maintenance window. All is good as the maintenance window will occur at the local time specified by the user. If you try the same example by specifying a string value for the DateTime parameters you get a different result. Consider the following example where the user is working in the PST time zone.

> [DateTime] $time = "11/28/2006"

>$time
Monday, November 28, 2006 12:00:00 AM

>$time.Kind
Unspecified

>New-MaintenanceWindow -startTime: $time -endTime: ($time.AddDays(1)) -reason: "ApplicationInstallation" -comment: "Testing DateTime string conversion"; >Monitoring:localhost\>Get-MaintenanceWindow
MonitoringObjectId : 3c8ac4f3-475e-44dd-4163-8a97af363705
StartTime : 11/28/2006 12:00:00 AM
ScheduledEndTime : 11/29/2006 12:00:00 AM
EndTime :
Reason : ApplicationInstallation
Comments : testing DateTime.Now
User : SMX\asttest
LastModified : 11/28/2006 2:40:00 AM
ManagementGroup : rogers01dmg
ManagementGroupId : 4e2f3ced-4b50-3939-edac-b9dfabe5effa

Great, the time value specified is the time value that is returned. All is good, or so it seems. There is a problem. The time is understood to be UTC time to the server that determines when the maintenance window starts and stops. In this case the maintenance window is going to start on 11/27/2006 at 2 PM PST. This is not what the user intended in this case. This same problem also occurs when using a DateTime value off of an SDK object to specify the parameter of type DateTime on the OM Cmdlets. If you are confused, try to remember the following guidelines.

  1. Always specify the DateTime.Kind property.
    • [DateTime]::Now and Get-Date specify the DateTime.Kind for you.
    • String conversion as in, "11/27/2006", does not specify the DateTime.Kind property.
    • Objects returned from the OM SDK do not specify the DateTime.Kind property.
  2. DateTime property values off of objects returned from the OM SDK are in UTC time.
  3. DateTime values passed as parameters to OM Cmdlets which do not specify the "Kind" property will be treated as UTC time.
  4. DateTime values passed as parameters to OM Cmdlets in local time will be converted to UTC time.