Ler em inglês

Partilhar via


Instanciando um objeto DateTimeOffset

A DateTimeOffset estrutura oferece várias maneiras de criar novos DateTimeOffset valores. Muitos deles correspondem diretamente aos métodos disponíveis para instanciar novos DateTime valores, com aprimoramentos que permitem especificar o deslocamento do valor de data e hora do Tempo Universal Coordenado (UTC). Em particular, você pode instanciar um DateTimeOffset valor das seguintes maneiras:

  • Usando um literal de data e hora.

  • Chamando um DateTimeOffset construtor.

  • Convertendo implicitamente um valor em DateTimeOffset valor.

  • Analisando a representação de cadeia de caracteres de uma data e hora.

Este tópico fornece mais detalhes e exemplos de código que ilustram esses métodos de instanciação de novos DateTimeOffset valores.

Literais de data e hora

Para idiomas que oferecem suporte a ele, uma das maneiras mais comuns de instanciar um DateTime valor é fornecer a data e a hora como um valor literal codificado. Por exemplo, o seguinte código do Visual Basic cria um DateTime objeto cujo valor é 1 de maio de 2008, às 08:06:32.

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

DateTimeOffset Os valores também podem ser inicializados usando literais de data e hora ao usar idiomas que suportam DateTime literais. Por exemplo, o seguinte código do Visual Basic cria um DateTimeOffset objeto.

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 do console, o DateTimeOffset valor criado dessa forma recebe o deslocamento do fuso horário local. Isso significa que um DateTimeOffset valor atribuído usando um literal de caractere não identifica um único ponto de tempo se o código for executado em computadores diferentes.

DateTimeOffset construtores

O DateTimeOffset tipo define seis construtores. Quatro deles correspondem diretamente aos DateTime construtores, com um parâmetro adicional do tipo TimeSpan que define o deslocamento de data e hora do UTC. Eles permitem que você defina um DateTimeOffset valor com base no valor de seus componentes individuais de data e hora. Por exemplo, o código a seguir usa esses quatro construtores para instanciar DateTimeOffset objetos com valores idênticos de 5/1/2008 8:06:32 +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 DateTimeOffset valor do objeto instanciado usando um PersianCalendar objeto como um dos argumentos para seu construtor é exibido no console, ele é expresso como uma data no calendário gregoriano em vez do persa. Para gerar uma data usando o calendário persa, consulte o PersianCalendar exemplo no tópico.

Os outros dois construtores criam um DateTimeOffset objeto a partir de um DateTime valor. O primeiro deles tem um único parâmetro, o DateTime valor a ser convertido em um DateTimeOffset valor. O deslocamento do valor resultante DateTimeOffset depende da Kind propriedade do parâmetro único do construtor. Se o seu valor for DateTimeKind.Utc, o deslocamento é definido como TimeSpan.Zero. Caso contrário, seu deslocamento é definido como igual ao do fuso horário local. O exemplo a seguir ilustra o uso desse construtor para instanciar DateTimeOffset objetos que representam UTC e o fuso horário local:

// 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.

Nota

Chamar a sobrecarga do DateTimeOffset construtor que tem um único DateTime parâmetro é equivalente a executar uma conversão implícita de um DateTime valor em um DateTimeOffset valor.

O segundo construtor que cria um DateTimeOffset objeto a partir de um DateTime valor tem dois parâmetros: o DateTime valor a ser convertido e um TimeSpan valor que representa o deslocamento de data e hora do UTC. Esse valor de deslocamento deve corresponder à Kind propriedade do primeiro parâmetro do construtor ou um ArgumentException é lançado. Se a Kind propriedade do primeiro parâmetro for DateTimeKind.Utc, o valor do segundo parâmetro deverá ser TimeSpan.Zero. Se a Kind propriedade do primeiro parâmetro for DateTimeKind.Local, o valor do segundo parâmetro deverá ser o deslocamento do fuso horário do sistema local. Se a Kind propriedade do primeiro parâmetro for DateTimeKind.Unspecified, o deslocamento pode ser qualquer valor válido. O código a seguir ilustra chamadas para este construtor para converter DateTime em DateTimeOffset valores.

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

Conversão de tipo implícita

O DateTimeOffset tipo suporta uma conversão de tipo implícita : de um DateTime valor para um DateTimeOffset valor. (Uma conversão de tipo implícita é uma conversão de um tipo para outro que não requer uma conversão explícita (em C#) ou conversão (em Visual Basic) e que não perde informações.) Ele torna possível um código como o seguinte.

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 DateTime.Kind propriedade. Se o seu valor for DateTimeKind.Utc, o deslocamento é definido como TimeSpan.Zero. Se o seu valor for um ou DateTimeKind.LocalDateTimeKind.Unspecified, o deslocamento é definido como igual ao do fuso horário local.

Analisando a representação de cadeia de caracteres de uma data e hora

O DateTimeOffset tipo suporta quatro métodos que permitem converter a representação de cadeia de caracteres de uma data e hora em um DateTimeOffset valor:

  • Parse, que tenta converter a representação de cadeia de caracteres de uma data e hora em um DateTimeOffset valor e lança uma exceção se a conversão falhar.

  • TryParse, que tenta converter a representação de cadeia de caracteres de uma data e hora em um DateTimeOffset valor e retorna false se a conversão falhar.

  • ParseExact, que tenta converter a representação de cadeia de caracteres de uma data e hora em um formato especificado em um DateTimeOffset valor. O método lança uma exceção se a conversão falhar.

  • TryParseExact, que tenta converter a representação de cadeia de caracteres de uma data e hora em um formato especificado em um DateTimeOffset valor. O método retorna false se a conversão falhar.

O exemplo a seguir ilustra chamadas para cada um desses quatro métodos de conversão de cadeia de caracteres para instanciar um DateTimeOffset valor.

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

Consulte também