Instruções: como obter um objeto TimeZoneInfo

  • Artigo

A maneira mais comum de obter um objeto TimeZoneInfo é recuperar informações sobre ele do Registro. Para obter o objeto, chame o método static (Shared no Visual Basic) TimeZoneInfo.FindSystemTimeZoneById, que examina o registro. Manipule as exceções geradas pelo método, particularmente a TimeZoneNotFoundException gerada se o fuso horário não estiver definido no registro.

Observação

A partir do .NET 8, TimeZoneInfo.FindSystemTimeZoneById retorna um objeto TimeZoneInfo armazenado em cache em vez de instanciar um novo objeto. Para obter mais informações, confira FindSystemTimeZoneById não retorna um novo objeto.

Exemplo

O código a seguir recupera um objeto TimeZoneInfo que representa o fuso horário padrão do Leste dos EUA e exibe a hora oficial do Leste dos EUA que corresponde à hora local.

DateTime timeNow = DateTime.Now;
try
{
    TimeZoneInfo easternZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");
    DateTime easternTimeNow = TimeZoneInfo.ConvertTime(
        timeNow,
        TimeZoneInfo.Local,
        easternZone
        );
    Console.WriteLine("{0} {1} corresponds to {2} {3}.",
                      timeNow,
                      TimeZoneInfo.Local.IsDaylightSavingTime(timeNow) ?
                                TimeZoneInfo.Local.DaylightName :
                                TimeZoneInfo.Local.StandardName,
                      easternTimeNow,
                      easternZone.IsDaylightSavingTime(easternTimeNow) ?
                                  easternZone.DaylightName :
                                  easternZone.StandardName);
}
// Handle exception
//
// As an alternative to simply displaying an error message, an alternate Eastern
// Standard Time TimeZoneInfo object could be instantiated here either by restoring
// it from a serialized string or by providing the necessary data to the
// CreateCustomTimeZone method.
catch (TimeZoneNotFoundException)
{
    Console.WriteLine("The Eastern Standard Time Zone cannot be found on the local system.");
}
catch (InvalidTimeZoneException)
{
    Console.WriteLine("The Eastern Standard Time Zone contains invalid or missing data.");
}
catch (SecurityException)
{
    Console.WriteLine("The application lacks permission to read time zone information from the registry.");
}
catch (OutOfMemoryException)
{
    Console.WriteLine("Not enough memory is available to load information on the Eastern Standard Time zone.");
}
// If we weren't passing FindSystemTimeZoneById a literal string, we also
// would handle an ArgumentNullException.

Dim timeNow As Date = Date.Now
Try
    Dim easternZone As TimeZoneInfo = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time")
    Dim easternTimeNow As Date = TimeZoneInfo.ConvertTime(timeNow, TimeZoneInfo.Local, easternZone)
    Console.WriteLine("{0} {1} corresponds to {2} {3}.", _
                      timeNow, _
                      IIf(TimeZoneInfo.Local.IsDaylightSavingTime(timeNow), _
                          TimeZoneInfo.Local.DaylightName, TimeZoneInfo.Local.StandardName), _
                      easternTimeNow, _
                      IIf(easternZone.IsDaylightSavingTime(easternTimeNow), _
                          easternZone.DaylightName, easternZone.StandardName))
    ' Handle exception
    '
    ' As an alternative to simply displaying an error message, an alternate Eastern
    ' Standard Time TimeZoneInfo object could be instantiated here either by restoring
    ' it from a serialized string or by providing the necessary data to the
    ' CreateCustomTimeZone method.
Catch e As TimeZoneNotFoundException
    Console.WriteLine("The Eastern Standard Time Zone cannot be found on the local system.")
Catch e As InvalidTimeZoneException
    Console.WriteLine("The Eastern Standard Time Zone contains invalid or missing data.")
Catch e As SecurityException
    Console.WriteLine("The application lacks permission to read time zone information from the registry.")
Catch e As OutOfMemoryException
    Console.WriteLine("Not enough memory is available to load information on the Eastern Standard Time zone.")
    ' If we weren't passing FindSystemTimeZoneById a literal string, we also 
    ' would handle an ArgumentNullException.
End Try

O parâmetro único do método TimeZoneInfo.FindSystemTimeZoneById é o identificador do fuso horário que você deseja recuperar, que corresponde à propriedade TimeZoneInfo.Id do objeto. O identificador do fuso horário é um campo de chave que identifica exclusivamente o fuso horário. Enquanto a maioria das chaves são relativamente curtas, o identificador de fuso horário é comparativamente longo. Na maioria dos casos, o valor dele corresponde ao da propriedade StandardName de um objeto TimeZoneInfo, que é usada para fornecer o nome da hora padrão do fuso horário. No entanto, há exceções. A melhor maneira de certificar-se de que você forneça um identificador válido é enumerar os fusos horários disponíveis no sistema e observar os identificadores dos fusos horários presentes nele. Para obter uma ilustração, veja Como enumerar os fusos horários presentes em um computador. O artigo Localizar os fusos horários definidos em um sistema local também contém uma lista de identificadores de fuso horário selecionados.

Se o fuso horário for encontrado, o método retornará o objeto TimeZoneInfo dele. Se o fuso horário não for encontrado, o método lançará uma TimeZoneNotFoundException. Se o fuso horário for encontrado, mas seus dados estiverem corrompidos ou incompletos, o método lançará uma InvalidTimeZoneException.

Se o aplicativo depender de um fuso horário que deve estar presente, primeiro chame o método FindSystemTimeZoneById para recuperar as informações de fuso horário do registro. Se a chamada de método falhar, o manipulador de exceção deverá criar uma instância do fuso horário ou criá-la novamente desserializando um objeto TimeZoneInfo serializado. Confira Como restaurar os fusos horários de um recurso inserido para obter um exemplo.

Confira também