Instanciando um Objeto DateTimeOffset
A classe DateTimeOffset oferece uma série de maneiras para criar novos valores DateTimeOffset. Muitas delas correspondem diretamente aos métodos disponíveis para instanciar novos valores DateTime, com aprimoramentos que permitem que você especifique o deslocamento do valor de data e hora do Tempo Universal Coordenado (UTC). Em particular, você pode instanciar um valor DateTimeOffset nos seguintes aspectos:
Usando uma data e hora literal.
Chamando um construtor DateTimeOffset.
Convertendo implicitamente um valor para um valor DateTimeOffset.
Ao analisar a representação da sequência de caracteres de uma data e hora.
Este tópico fornece mais detalhes e exemplos de código que ilustram esses métodos de instanciar valores DateTimeOffset.
Data e hora literais
Para as linguagens que dão suporte a ele, uma das maneiras mais comuns para instanciar um valor DateTime é fornecer a data e hora como um valor literal embutido. Por exemplo, o seguinte código de Visual Basic cria um objeto DateTime cujo valor é 1 º de janeiro de 2008, às 10:00 A.M..
Dim literalDate1 As Date = #05/01/2008 8:06:32 AM#
Console.WriteLine(literalDate1.ToString() )
' Displays:
' 5/1/2008 8:06:32 AM
Valores DateTimeOffset também podem ser inicializados usando literais de data e hora ao usar linguagens que oferecem suporte aos literais DateTime. Por exemplo, o seguinte código de Visual Basic cria um objeto DateTimeOffset.
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
Como mostra a saída no console, o valor DateTimeOffset criado dessa maneira é atribuído o deslocamento da zona de tempo local. Isso significa que um valor DateTimeOffset atribuído usando um caractere literal não identifica um único ponto de tempo se o código é executado em computadores diferentes.
Construtores DateTimeOffset
O tipo DateTimeOffset define seis construtores. Quatro deles correspondem diretamente aos construtores DateTime, com um parâmetro adicional do tipo TimeSpan que define o deslocamento d data e hora do UTC. Elas permitem que você defina um valor DateTimeOffset com base no valor do seus componentes individuais de data e hora. Por exemplo, o código a seguir usa esses quatro construtores para instanciar objetos DateTimeOffset com valores idênticos de 7/1/2008 12: 05 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
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
Observe que, quando o valor do objeto DateTimeOffset instanciado usando um objeto PersianCalendar como um dos argumentos para o construtor é exibido no console, ele é expresso como uma data no calendário Gregoriano em vez do calendário persa. Para exibir uma data usando o calendário persa, consulte o exemplo no tópico PersianCalendar.
Os outros dois construtores criam um objeto DateTimeOffset a partir de um valor DateTime. O primeiro desses tem um único parâmetro, o valor DateTime para converter um valor DateTimeOffset. O deslocamento do valor DateTimeOffset resultante depende da propriedade Kind do único parâmetro do construtor. Se o valor for DateTimeKind.Utc, o deslocamento será definido igual a TimeSpan.Zero. Caso contrário, o deslocamento é definido igual ao da zona de tempo local. O exemplo a seguir ilustra o uso desse construtor para instanciar objetos DateTimeOffset que representam o UTC e a zona de tempo local:
' 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.
'
// 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.
Observação
Chamar a sobrecarga do construtor DateTimeOffset que tem um único parâmetro DateTime equivale a executar uma conversão implícita de um valor DateTime para um valor DateTimeOffset.
O segundo construtor que cria uma DateTimeOffset de objeto de um DateTime valor tem dois parâmetros: o DateTime valor para converter e um TimeSpan valor que representa a data e o deslocamento do tempo de UTC. Esse valor de deslocamento deverá corresponder à propriedade Kind do primeiro parâmetro do construtor ou uma ArgumentException é lançada. Se a propriedade Kind do primeiro parâmetro é DateTimeKind.Utc, o valor do segundo parâmetro deve ser TimeSpan.Zero. Se a propriedade Kind do primeiro parâmetro é DateTimeKind.Local, o valor do segundo parâmetro deve ser o deslocamento da zona de tempo do sistema local. Se a propriedade Kind do primeiro parâmetro é DateTimeKind.Unspecified, o deslocamento pode ser qualquer valor válido. O código a seguir ilustra chamadas desse construtor para converter valores DateTime para DateTimeOffset.
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 arbitary 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
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 arbitary 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
Conversão implícita de tipo
O DateTimeOffset tipo oferece suporte a uma conversão de tipo implícito: de um DateTime valor para um DateTimeOffset valor. (Um conversão implícita de tipos implícito é uma conversão de um tipo para outro que não requer uma conversão explícita (em C#) ou de conversão (em Visual Basic) e que não perde informações. Gera um código como as possibilidades a seguir.
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
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
O deslocamento do valor resultante DateTimeOffset depende do valor da propriedade DateTime.Kind. Se o valor for DateTimeKind.Utc, o deslocamento será definido igual a TimeSpan.Zero. Se o valor for qualquer um dos DateTimeKind.Local ou DateTimeKind.Unspecified, o deslocamento é definido igual ao da zona de tempo local.
Ao analisar a representação da sequência de caracteres de uma data e hora
O tipo DateTimeOffset oferece suporte aos quatro métodos que permitem que você converta a representação da sequência de caracteres de uma data e hora em um valor DateTimeOffset:
Parse, que tenta converter uma representação de sequência de caracteres de data e hora para um valor DateTimeOffset e gera uma exceção se a conversão falhar.
TryParse, que tenta converter uma representação de sequência de caracteres de data e hora para um valor DateTimeOffset e retorna false se a conversão falhar.
ParseExact, que tenta converter uma representação de sequência de caracteres de data e hora em um formato determinado para um valor DateTimeOffset. O método gera uma exceção se a conversão falhar.
TryParseExact, que tenta converter uma representação de sequência de caracteres de data e hora em um formato determinado para um valor DateTimeOffset. O método retorna falsese a conversão falhar.
O exemplo a seguir ilustra chamadas para cada um desses quatro métodos de conversão de sequência para instanciar um valor DateTimeOffset.
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
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