Instanziieren eines "DateTimeOffset"-Objekts

Die DateTimeOffset-Struktur bietet eine Reihe von Möglichkeiten zum Erstellen neuer DateTimeOffset-Werte. Viele von ihnen entsprechen direkt den Methoden zum Instanziieren neuer DateTime-Werte, bieten aber Erweiterungen, mit denen Sie den Offset des Datums- und Uhrzeitwerts von der koordinierten Weltzeit (UTC) angeben können. Ein DateTimeOffset-Wert kann insbesondere wie folgt instanziiert werden:

• Mithilfe eines Datums- und Uhrzeitliterals

• Durch Aufrufen eines DateTimeOffset-Konstruktors

• Durch implizites Konvertieren eines Werts in einen DateTimeOffset-Wert

• Durch Analysieren der Zeichenfolgendarstellung eines Datums- und Uhrzeitwerts.

Dieses Thema enthält ausführlichere Informationen sowie Codebeispiele, die diese Methoden zum Instanziieren neuer DateTimeOffset-Werte veranschaulichen.

Datums- und Zeitliterale

Bei Sprachen mit entsprechender Unterstützung besteht eine der am häufigsten verwendeten Methoden zum Instanziieren eines DateTime-Werts darin, den Datums- und Uhrzeitwert als hartcodierten Literalwert bereitzustellen. Der folgende Visual Basic-Code erstellt beispielsweise ein DateTime-Objekt, dessen Wert dem 1. Mai 2008, 8:06:32 Uhr entspricht:

Dim literalDate1 As Date = #05/01/2008 8:06:32 AM#
Console.WriteLine(literalDate1.ToString())
' Displays:
'              5/1/2008 8:06:32 AM

Bei Verwendung von Sprachen, die DateTime-Literale unterstützen, können DateTimeOffset-Werte auch über Datums- und Uhrzeitliterale initialisiert werden. Der folgende Visual Basic-Code erstellt beispielsweise ein DateTimeOffset-Objekt:

Dim literalDate As DateTimeOffset = #05/01/2008 8:06:32 AM#
Console.WriteLine(literalDate.ToString())
' Displays:
'              5/1/2008 8:06:32 AM -07:00

Wie die Konsolenausgabe zeigt, wird dem auf diese Weise erstellten DateTimeOffset-Wert der Offset der lokalen Zeitzone zugewiesen. Das bedeutet, dass ein DateTimeOffset-Wert, der über ein Zeichenliteral zugewiesen wurde, keinen einzelnen Zeitpunkt identifiziert, wenn der Code auf verschiedenen Computern ausgeführt wird.

DateTimeOffset-Konstruktoren

Der DateTimeOffset-Typ definiert sechs Konstruktoren. Vier davon entsprechen direkt den DateTime-Konstruktoren – mit einem zusätzlichen Parameter vom Typ TimeSpan, der den Datums- und Uhrzeitoffset von UTC definiert. Mit diesen können Sie einen DateTimeOffset-Wert basierend auf dem Wert der einzelnen Datums- und Uhrzeitkomponenten definieren. Der folgende Code verwendet beispielsweise diese vier Konstruktoren, um DateTimeOffset-Objekte mit identischen Werten (5/1/2008 8:06:32 +01:00) zu instanziieren:

DateTimeOffset dateAndTime;

// Instantiate date and time using years, months, days,
// hours, minutes, and seconds
dateAndTime = new DateTimeOffset(2008, 5, 1, 8, 6, 32,
                                 new TimeSpan(1, 0, 0));
Console.WriteLine(dateAndTime);
// Instantiate date and time using years, months, days,
// hours, minutes, seconds, and milliseconds
dateAndTime = new DateTimeOffset(2008, 5, 1, 8, 6, 32, 545,
                                 new TimeSpan(1, 0, 0));
Console.WriteLine("{0} {1}", dateAndTime.ToString("G"),
                             dateAndTime.ToString("zzz"));

// Instantiate date and time using Persian calendar with years,
// months, days, hours, minutes, seconds, and milliseconds
dateAndTime = new DateTimeOffset(1387, 2, 12, 8, 6, 32, 545,
                                 new PersianCalendar(),
                                 new TimeSpan(1, 0, 0));
// Note that the console output displays the date in the Gregorian
// calendar, not the Persian calendar.
Console.WriteLine("{0} {1}", dateAndTime.ToString("G"),
                             dateAndTime.ToString("zzz"));

// Instantiate date and time using number of ticks
// 05/01/2008 8:06:32 AM is 633,452,259,920,000,000 ticks
dateAndTime = new DateTimeOffset(633452259920000000, new TimeSpan(1, 0, 0));
Console.WriteLine(dateAndTime);
// The example displays the following output to the console:
//       5/1/2008 8:06:32 AM +01:00
//       5/1/2008 8:06:32 AM +01:00
//       5/1/2008 8:06:32 AM +01:00
//       5/1/2008 8:06:32 AM +01:00

Dim dateAndTime As DateTimeOffset

' Instantiate date and time using years, months, days, 
' hours, minutes, and seconds
dateAndTime = New DateTimeOffset(2008, 5, 1, 8, 6, 32, _
                                 New TimeSpan(1, 0, 0))
Console.WriteLine(dateAndTime)
' Instantiate date and time using years, months, days,
' hours, minutes, seconds, and milliseconds
dateAndTime = New DateTimeOffset(2008, 5, 1, 8, 6, 32, 545, _
                                 New TimeSpan(1, 0, 0))
Console.WriteLine("{0} {1}", dateAndTime.ToString("G"), _
                             dateAndTime.ToString("zzz"))

' Instantiate date and time using Persian calendar with years,
' months, days, hours, minutes, seconds, and milliseconds
dateAndTime = New DateTimeOffset(1387, 2, 12, 8, 6, 32, 545, New PersianCalendar, New TimeSpan(1, 0, 0))
' Note that the console output displays the date in the Gregorian
' calendar, not the Persian calendar. 
Console.WriteLine("{0} {1}", dateAndTime.ToString("G"), _
                             dateAndTime.ToString("zzz"))

' Instantiate date and time using number of ticks
' 05/01/2008 8:06:32 AM is 633,452,259,920,000,000 ticks
dateAndTime = New DateTimeOffset(633452259920000000, New TimeSpan(1, 0, 0))
Console.WriteLine(dateAndTime)
' The example displays the following output to the console:
'       5/1/2008 8:06:32 AM +01:00
'       5/1/2008 8:06:32 AM +01:00
'       5/1/2008 8:06:32 AM +01:00
'       5/1/2008 8:06:32 AM +01:00

Hinweis: Wenn der Wert des DateTimeOffset-Objekts, bei dessen Instanziierung ein PersianCalendar-Objekt als eines der Argumente für den Konstruktor verwendet wurde, in der Konsole angezeigt wird, wird es als Datum im gregorianischen Kalender und nicht als Datum im persischen Kalender ausgedrückt. Informationen dazu, wie Sie ein Datum unter Verwendung des persischen Kalenders ausgeben, finden Sie im Beispiel des Themas PersianCalendar.

Die beiden anderen Konstruktoren erstellen ein DateTimeOffset-Objekt auf der Grundlage eines DateTime-Werts. Der erste verfügt über einen einzelnen Parameter. Hierbei handelt es sich um den DateTime-Wert, der in einen DateTimeOffset-Wert konvertiert werden soll. Der Offset des resultierenden DateTimeOffset-Werts hängt von der Kind-Eigenschaft des einzelnen Parameters des Konstruktors ab. Lautet der Wert DateTimeKind.Utc, wird der Offset auf TimeSpan.Zero festgelegt. Andernfalls wird die Abweichung entsprechend der lokalen Zeitzone eingestellt. Das folgende Beispiel veranschaulicht die Verwendung dieses Konstruktors für die Instanziierung von DateTimeOffset-Objekten, die UTC und die lokale Zeitzone darstellen:

// Declare date; Kind property is DateTimeKind.Unspecified
DateTime sourceDate = new DateTime(2008, 5, 1, 8, 30, 0);
DateTimeOffset targetTime;

// Instantiate a DateTimeOffset value from a UTC time
DateTime utcTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Utc);
targetTime = new DateTimeOffset(utcTime);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00
// Because the Kind property is DateTimeKind.Utc,
// the offset is TimeSpan.Zero.

// Instantiate a DateTimeOffset value from a UTC time with a zero offset
targetTime = new DateTimeOffset(utcTime, TimeSpan.Zero);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00
// Because the Kind property is DateTimeKind.Utc,
// the call to the constructor succeeds

// Instantiate a DateTimeOffset value from a UTC time with a negative offset
try
{
   targetTime = new DateTimeOffset(utcTime, new TimeSpan(-2, 0, 0));
   Console.WriteLine(targetTime);
}
catch (ArgumentException)
{
   Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.",
                      targetTime);
}
// Throws exception and displays the following to the console:
//   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM +00:00 failed.

// Instantiate a DateTimeOffset value from a local time
DateTime localTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Local);
targetTime = new DateTimeOffset(localTime);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00
// Because the Kind property is DateTimeKind.Local,
// the offset is that of the local time zone.

// Instantiate a DateTimeOffset value from an unspecified time
targetTime = new DateTimeOffset(sourceDate);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00
// Because the Kind property is DateTimeKind.Unspecified,
// the offset is that of the local time zone.

' Declare date; Kind property is DateTimeKind.Unspecified
Dim sourceDate As Date = #5/1/2008 8:30 AM#
Dim targetTime As DateTimeOffset

' Instantiate a DateTimeOffset value from a UTC time 
Dim utcTime As Date = Date.SpecifyKind(sourceDate, DateTimeKind.Utc)
targetTime = New DateTimeOffset(utcTime)
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM +00:00
' Because the Kind property is DateTimeKind.Utc, 
' the offset is TimeSpan.Zero.


' Instantiate a DateTimeOffset value from a local time
Dim localTime As Date = Date.SpecifyKind(sourceDate, DateTimeKind.Local)
targetTime = New DateTimeOffset(localTime)
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM -07:00
' Because the Kind property is DateTimeKind.Local, 
' the offset is that of the local time zone.

' Instantiate a DateTimeOffset value from an unspecified time
targetTime = New DateTimeOffset(sourceDate)
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM -07:00
' Because the Kind property is DateTimeKind.Unspecified, 
' the offset is that of the local time zone.

'

Hinweis

Das Aufrufen der Überladung des DateTimeOffset-Konstruktors mit einem einzelnen DateTime-Parameter entspricht dem impliziten Konvertieren eines DateTime-Werts in einen DateTimeOffset-Wert.

Der zweite Konstruktor, der ein DateTimeOffset-Objekt auf der Grundlage eines DateTime-Werts erstellt, verfügt über zwei Parameter: den zu konvertierenden DateTime-Wert und einen TimeSpan-Wert, der den Datums- und Uhrzeitoffset von UTC darstellt. Dieser Offsetwert muss der Kind-Eigenschaft des ersten Parameters des Konstruktors entsprechen. Andernfalls wird eine Ausnahme vom Typ ArgumentException ausgelöst. Wenn die Kind-Eigenschaft des ersten Parameters DateTimeKind.Utc lautet, muss der Wert des zweiten Parameters TimeSpan.Zero lauten. Wenn die Kind-Eigenschaft des ersten Parameters DateTimeKind.Local lautet, muss der Wert des zweiten Parameters dem Offset der Zeitzone des lokalen Systems entsprechen. Wenn die Kind-Eigenschaft des ersten Parameters DateTimeKind.Unspecified lautet, kann der Offset einen beliebigen gültigen Wert haben. Der folgende Code veranschaulicht Aufrufe dieses Konstruktors für die Konvertierung von DateTime in DateTimeOffset-Werte:

DateTime sourceDate = new DateTime(2008, 5, 1, 8, 30, 0);
DateTimeOffset targetTime;

// Instantiate a DateTimeOffset value from a UTC time with a zero offset.
DateTime utcTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Utc);
targetTime = new DateTimeOffset(utcTime, TimeSpan.Zero);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00
// Because the Kind property is DateTimeKind.Utc,
// the call to the constructor succeeds

// Instantiate a DateTimeOffset value from a UTC time with a non-zero offset.
try
{
   targetTime = new DateTimeOffset(utcTime, new TimeSpan(-2, 0, 0));
   Console.WriteLine(targetTime);
}
catch (ArgumentException)
{
   Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.",
                      utcTime);
}
// Throws exception and displays the following to the console:
//   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM failed.

// Instantiate a DateTimeOffset value from a local time with
// the offset of the local time zone
DateTime localTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Local);
targetTime = new DateTimeOffset(localTime,
                                TimeZoneInfo.Local.GetUtcOffset(localTime));
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00
// Because the Kind property is DateTimeKind.Local and the offset matches
// that of the local time zone, the call to the constructor succeeds.

// Instantiate a DateTimeOffset value from a local time with a zero offset.
try
{
   targetTime = new DateTimeOffset(localTime, TimeSpan.Zero);
   Console.WriteLine(targetTime);
}
catch (ArgumentException)
{
   Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.",
                      localTime);
}
// Throws exception and displays the following to the console:
//   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM failed.

// Instantiate a DateTimeOffset value with an arbitrary time zone.
string timeZoneName = "Central Standard Time";
TimeSpan offset = TimeZoneInfo.FindSystemTimeZoneById(timeZoneName).
                         GetUtcOffset(sourceDate);
targetTime = new DateTimeOffset(sourceDate, offset);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -05:00

Dim sourceDate As Date = #5/1/2008 8:30 AM#
Dim targetTime As DateTimeOffset

' Instantiate a DateTimeOffset value from a UTC time with a zero offset.
Dim utcTime As Date = Date.SpecifyKind(sourceDate, DateTimeKind.Utc)
targetTime = New DateTimeOffset(utcTime, TimeSpan.Zero)
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM +00:00
' Because the Kind property is DateTimeKind.Utc,  
' the call to the constructor succeeds.

' Instantiate a DateTimeOffset value from a UTC time with a non-zero offset.
Try
    targetTime = New DateTimeOffset(utcTime, New TimeSpan(-2, 0, 0))
    Console.WriteLine(targetTime)
Catch e As ArgumentException
    Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.", _
                       utcTime)
End Try
' Throws exception and displays the following to the console:
'   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM failed.

' Instantiate a DateTimeOffset value from a local time with 
' the offset of the local time zone.
Dim localTime As Date = Date.SpecifyKind(sourceDate, DateTimeKind.Local)
targetTime = New DateTimeOffset(localTime, _
                                TimeZoneInfo.Local.GetUtcOffset(localTime))
Console.WriteLine(targetTime)
' Because the Kind property is DateTimeKind.Local and the offset matches
' that of the local time zone, the call to the constructor succeeds.

' Instantiate a DateTimeOffset value from a local time with a zero offset.
Try
    targetTime = New DateTimeOffset(localTime, TimeSpan.Zero)
    Console.WriteLine(targetTime)
Catch e As ArgumentException
    Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.", _
                       localTime)
End Try
' Throws exception and displays the following to the console:
'   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM failed.

' Instantiate a DateTimeOffset value with an arbitrary time zone.
Dim timeZoneName As String = "Central Standard Time"
Dim offset As TimeSpan = TimeZoneInfo.FindSystemTimeZoneById(timeZoneName). _
                         GetUtcOffset(sourceDate)
targetTime = New DateTimeOffset(sourceDate, offset)
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM -05:00

Implizite Typkonvertierung

Der DateTimeOffset-Typ unterstützt eine einzelne implizite Typkonvertierung: von einem DateTime-Wert in einen DateTimeOffset-Wert. (Eine implizite Typkonvertierung ist eine Konvertierung zwischen Typen, für die keine explizite Umwandlung (in C#) oder Konvertierung (in Visual Basic) erforderlich ist und bei der keine Informationen verloren gehen.) Dies ermöglicht beispielsweise folgenden Code:

DateTimeOffset targetTime;

// The Kind property of sourceDate is DateTimeKind.Unspecified
DateTime sourceDate = new DateTime(2008, 5, 1, 8, 30, 0);
targetTime = sourceDate;
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00

// define a UTC time (Kind property is DateTimeKind.Utc)
DateTime utcTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Utc);
targetTime = utcTime;
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00

// Define a local time (Kind property is DateTimeKind.Local)
DateTime localTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Local);
targetTime = localTime;
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00

Dim targetTime As DateTimeOffset

' The Kind property of sourceDate is DateTimeKind.Unspecified
Dim sourceDate As Date = #5/1/2008 8:30 AM#
targetTime = sourceDate
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM -07:00

' define a UTC time (Kind property is DateTimeKind.Utc)
Dim utcTime As Date = Date.SpecifyKind(sourceDate, DateTimeKind.Utc)
targetTime = utcTime
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM +00:00

' Define a local time (Kind property is DateTimeKind.Local)
Dim localTime As Date = Date.SpecifyKind(sourceDate, DateTimeKind.Local)
targetTime = localTime
Console.WriteLine(targetTime)
' Displays 5/1/2008 8:30:00 AM -07:00

Der Offset des resultierenden DateTimeOffset-Werts hängt vom DateTime.Kind-Eigenschaftswert ab. Lautet der Wert DateTimeKind.Utc, wird der Offset auf TimeSpan.Zero festgelegt. Ist der Wert entweder DateTimeKind.Local oder DateTimeKind.Unspecified, wird der Offset gemäß der lokalen Zeitzone festgelegt.

Analysieren der Zeichenfolgendarstellung einer Datums- und Uhrzeitangabe

Der DateTimeOffset-Typ unterstützt vier Methoden, die die Konvertierung der Zeichenfolgendarstellung eines Datums und einer Uhrzeit in einen DateTimeOffset-Wert ermöglichen:

• Parse: Versucht, die Zeichenfolgendarstellung einer Datums- und Uhrzeitangabe in einen DateTimeOffset-Wert zu konvertieren, und löst eine Ausnahme aus, wenn bei der Konvertierung ein Fehler auftritt.

• TryParse: Versucht, die Zeichenfolgendarstellung einer Datums- und Uhrzeitangabe in einen DateTimeOffset-Wert zu konvertieren, und gibt false zurück, wenn bei der Konvertierung ein Fehler auftritt.

• ParseExact: Versucht, die Zeichenfolgendarstellung einer Datums- und Uhrzeitangabe in einem angegebenen Format in einen DateTimeOffset-Wert zu konvertieren. Die Methode löst eine Ausnahme aus, wenn bei der Konvertierung ein Fehler auftritt.

• TryParseExact: Versucht, die Zeichenfolgendarstellung einer Datums- und Uhrzeitangabe in einem angegebenen Format in einen DateTimeOffset-Wert zu konvertieren. Die Methode gibt false zurück, wenn bei der Konvertierung ein Fehler auftritt.

Das folgende Beispiel veranschaulicht Aufrufe dieser vier Konvertierungsmethoden zum Instanziieren eines DateTimeOffset-Werts:

string timeString;
DateTimeOffset targetTime;

timeString = "05/01/2008 8:30 AM +01:00";
try
{
   targetTime = DateTimeOffset.Parse(timeString);
   Console.WriteLine(targetTime);
}
catch (FormatException)
{
   Console.WriteLine("Unable to parse {0}.", timeString);
}

timeString = "05/01/2008 8:30 AM";
if (DateTimeOffset.TryParse(timeString, out targetTime))
   Console.WriteLine(targetTime);
else
   Console.WriteLine("Unable to parse {0}.", timeString);

timeString = "Thursday, 01 May 2008 08:30";
try
{
   targetTime = DateTimeOffset.ParseExact(timeString, "f",
                CultureInfo.InvariantCulture);
   Console.WriteLine(targetTime);
}
catch (FormatException)
{
   Console.WriteLine("Unable to parse {0}.", timeString);
}

timeString = "Thursday, 01 May 2008 08:30 +02:00";
string formatString;
formatString = CultureInfo.InvariantCulture.DateTimeFormat.LongDatePattern +
                " " +
                CultureInfo.InvariantCulture.DateTimeFormat.ShortTimePattern +
                " zzz";
if (DateTimeOffset.TryParseExact(timeString,
                                formatString,
                                CultureInfo.InvariantCulture,
                                DateTimeStyles.AllowLeadingWhite,
                                out targetTime))
   Console.WriteLine(targetTime);
else
   Console.WriteLine("Unable to parse {0}.", timeString);
// The example displays the following output to the console:
//    5/1/2008 8:30:00 AM +01:00
//    5/1/2008 8:30:00 AM -07:00
//    5/1/2008 8:30:00 AM -07:00
//    5/1/2008 8:30:00 AM +02:00

Dim timeString As String
Dim targetTime As DateTimeOffset

timeString = "05/01/2008 8:30 AM +01:00"
Try
    targetTime = DateTimeOffset.Parse(timeString)
    Console.WriteLine(targetTime)
Catch e As FormatException
    Console.WriteLine("Unable to parse {0}.", timeString)
End Try

timeString = "05/01/2008 8:30 AM"
If DateTimeOffset.TryParse(timeString, targetTime) Then
    Console.WriteLine(targetTime)
Else
    Console.WriteLine("Unable to parse {0}.", timeString)
End If

timeString = "Thursday, 01 May 2008 08:30"
Try
    targetTime = DateTimeOffset.ParseExact(timeString, "f", _
                 CultureInfo.InvariantCulture)
    Console.WriteLine(targetTime)
Catch e As FormatException
    Console.WriteLine("Unable to parse {0}.", timeString)
End Try

timeString = "Thursday, 01 May 2008 08:30 +02:00"
Dim formatString As String
formatString = CultureInfo.InvariantCulture.DateTimeFormat.LongDatePattern & _
                " " & _
                CultureInfo.InvariantCulture.DateTimeFormat.ShortTimePattern & _
                " zzz"
If DateTimeOffset.TryParseExact(timeString, _
                                formatString, _
                                CultureInfo.InvariantCulture, _
                                DateTimeStyles.AllowLeadingWhite, _
                                targetTime) Then
    Console.WriteLine(targetTime)
Else
    Console.WriteLine("Unable to parse {0}.", timeString)
End If
' The example displays the following output to the console:
'    5/1/2008 8:30:00 AM +01:00
'    5/1/2008 8:30:00 AM -07:00
'    5/1/2008 8:30:00 AM -07:00
'    5/1/2008 8:30:00 AM +02:00

Weitere Informationen

• Datumsangaben, Uhrzeiten und Zeitzonen