Partager via


TimeZoneInfo.GetAmbiguousTimeOffsets Method (DateTime)

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Returns information about the possible dates and times that an ambiguous date and time can be mapped to.

Namespace:  System
Assembly:  mscorlib (in mscorlib.dll)

Syntax

'Declaration
Public Function GetAmbiguousTimeOffsets ( _
    dateTime As DateTime _
) As TimeSpan()
public TimeSpan[] GetAmbiguousTimeOffsets(
    DateTime dateTime
)

Parameters

Return Value

Type: array<System.TimeSpan[]
An array of TimeSpan objects that represents possible Coordinated Universal Time (UTC) offsets that a particular date and time can be mapped to.

Exceptions

Exception Condition
ArgumentException

dateTime is not an ambiguous time.

Remarks

The precise behavior of this method depends on the relationship between the Kind property and the TimeZoneInfo object, as the following table shows.

TimeZoneInfo object type

Kind property value

Behavior

TimeZoneInfo.Local

DateTimeKind.Local or DateTimeKind.Unspecified

Returns ambiguous time offsets for dateTime.

TimeZoneInfo.Local

DateTimeKind.Utc

Converts dateTime to the local time, and then returns ambiguous time offsets for that time.

TimeZoneInfo.Utc

Any value.

Throws an ArgumentException.

Any other time zone.

Local or DateTimeKind.Utc

Converts dateTime to the specified time zone, and then determines whether that time is ambiguous.

Any other time zone.

DateTimeKind.Unspecified

Determines whether dateTime is ambiguous in the specified time zone.

The order of TimeSpan objects in the array returned by this method is undefined. However, you can determine which element represents an offset from the time zone's standard time by comparing its value with the time zone's BaseUtcOffset property.

Version Notes

XNA Framework

 When this method is used in the XNA Framework, it throws a NotSupportedException exception.

Examples

The following example defines a method named ShowPossibleUtcTimes that uses the GetAmbiguousTimeOffsets(DateTime) method to map an ambiguous time to its possible corresponding Coordinated Universal Time (UTC) times.

Private Sub ShowPossibleUtcTimes(ByVal outputBlock As System.Windows.Controls.TextBlock, ByVal ambiguousTime As Date, ByVal timeZone As TimeZoneInfo)
   ' Determine if time is ambiguous in target time zone
   If Not timeZone.IsAmbiguousTime(ambiguousTime) Then
      outputBlock.Text &= String.Format("{0} is not ambiguous in time zone {1}.", _
                        ambiguousTime, _
                        timeZone.DisplayName) & vbCrLf
   Else
      ' Display time and its time zone (local, UTC, or indicated by timeZone argument)
      Dim originalTimeZoneName As String
      If ambiguousTime.Kind = DateTimeKind.Utc Then
         originalTimeZoneName = "UTC"
      ElseIf ambiguousTime.Kind = DateTimeKind.Local Then
         originalTimeZoneName = "local time"
      Else
         originalTimeZoneName = timeZone.DisplayName
      End If
      outputBlock.Text &= String.Format("{0} {1} maps to the following possible times:", _
                        ambiguousTime, originalTimeZoneName) & vbCrLf
      ' Get ambiguous offsets 
      Dim offsets() As TimeSpan = timeZone.GetAmbiguousTimeOffsets(ambiguousTime)

      ' Display each offset and its mapping to UTC
      For Each offset As TimeSpan In offsets
         If offset.Equals(timeZone.BaseUtcOffset) Then
            outputBlock.Text &= String.Format("If {0} is {1}, {2} UTC", ambiguousTime, timeZone.StandardName, ambiguousTime - offset) & vbCrLf
         Else
            outputBlock.Text &= String.Format("If {0} is {1}, {2} UTC", ambiguousTime, timeZone.DaylightName, ambiguousTime - offset) & vbCrLf
         End If
      Next
   End If
End Sub
private void ShowPossibleUtcTimes(System.Windows.Controls.TextBlock outputBlock, 
                                  DateTime ambiguousTime, TimeZoneInfo timeZone)
{
   // Determine if time is ambiguous in target time zone
   if (!timeZone.IsAmbiguousTime(ambiguousTime))
   {
      outputBlock.Text += String.Format("{0} is not ambiguous in time zone {1}.",
                        ambiguousTime,
                        timeZone.DisplayName) + "\n";
   }
   else
   {
      // Display time and its time zone (local, UTC, or indicated by timeZone argument)
      string originalTimeZoneName;
      if (ambiguousTime.Kind == DateTimeKind.Utc)
         originalTimeZoneName = "UTC";
      else if (ambiguousTime.Kind == DateTimeKind.Local)
         originalTimeZoneName = "local time";
      else
         originalTimeZoneName = timeZone.DisplayName;

      outputBlock.Text += String.Format("{0} {1} maps to the following possible times:",
                        ambiguousTime, originalTimeZoneName) + "\n";
      // Get ambiguous offsets 
      TimeSpan[] offsets = timeZone.GetAmbiguousTimeOffsets(ambiguousTime);

      // Display each offset and its mapping to UTC
      foreach (TimeSpan offset in offsets)
      {
         if (offset.Equals(timeZone.BaseUtcOffset))
            outputBlock.Text += String.Format("If {0} is {1}, {2} UTC", ambiguousTime, timeZone.StandardName, ambiguousTime - offset) + "\n";
         else
            outputBlock.Text += String.Format("If {0} is {1}, {2} UTC", ambiguousTime, timeZone.DaylightName, ambiguousTime - offset) + "\n";
      }
   }
}

The method can then be called using code such as the following:

ShowPossibleUtcTimes(outputBlock, #11/4/2007 1:00:00 AM#, _ 
                     TimeZoneInfo.Local)
' 
' This example produces the following output if run in the Pacific time zone:
'
'    11/4/2007 1:00:00 AM (GMT-08:00) Pacific Time (US & Canada) maps to the following possible times: 
'    If 11/4/2007 1:00:00 AM is Pacific Standard Time, 11/4/2007 9:00:00 AM UTC                        
'    If 11/4/2007 1:00:00 AM is Pacific Daylight Time, 11/4/2007 8:00:00 AM UTC                        
' 
ShowPossibleUtcTimes(outputBlock, new DateTime(2007, 11, 4, 1, 0, 0),
                     TimeZoneInfo.Local);
// 
// This example produces the following output if run in the Pacific time zone:
//
//    11/4/2007 1:00:00 AM (GMT-08:00) Pacific Time (US & Canada) maps to the following possible times:
//    If 11/4/2007 1:00:00 AM is Pacific Standard Time, 11/4/2007 9:00:00 AM UTC
//    If 11/4/2007 1:00:00 AM is Pacific Daylight Time, 11/4/2007 8:00:00 AM UTC
//

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.