Compartilhar via

Trabalhar com calendários

Embora um valor de data e hora represente um momento no tempo, sua representação textual é sensível à cultura e depende das convenções usadas para exibir valores de data e hora, bem como do calendário utilizado por essa cultura. Este tópico explora o suporte para calendários no .NET e discute o uso das classes de calendário ao trabalhar com valores de data.

Calendários no .NET

Todos os calendários no .NET derivam da System.Globalization.Calendar classe, que fornece a implementação do calendário base. Uma das classes que herda da classe Calendar é a classe EastAsianLunisolarCalendar, que é a classe base para todos os calendários lunisolares. O .NET inclui as seguintes implementações de calendário:

Um calendário pode ser usado de duas maneiras:

  • Como o calendário usado por uma cultura específica. Cada CultureInfo objeto tem um calendário atual, que é o calendário que o objeto está usando no momento. As representações de cadeia de caracteres de todos os valores de data e hora refletem automaticamente a cultura atual e seu calendário atual. Normalmente, o calendário atual é o calendário padrão da cultura. CultureInfo os objetos também têm calendários opcionais, que incluem calendários adicionais que a cultura pode usar.

  • Como um calendário autônomo independente de uma cultura específica. Nesse caso, Calendar os métodos são usados para expressar datas como valores que refletem o calendário.

Observe que seis classes de calendário – ChineseLunisolarCalendar, JapaneseLunisolarCalendar, JulianCalendar, KoreanLunisolarCalendar, PersianCalendare TaiwanLunisolarCalendar – podem ser usadas apenas como calendários autônomos. Eles não são usados por nenhuma cultura como o calendário padrão ou como um calendário opcional.

Calendários e culturas

Cada cultura tem um calendário padrão, que é definido pela CultureInfo.Calendar propriedade. A CultureInfo.OptionalCalendars propriedade retorna uma matriz de Calendar objetos que especifica todos os calendários compatíveis com uma cultura específica, incluindo o calendário padrão dessa cultura.

O exemplo a seguir ilustra as propriedades CultureInfo.Calendar e CultureInfo.OptionalCalendars. Ele cria CultureInfo objetos para as culturas tailandesa (Tailândia) e japonesa (Japão) e exibe seus calendários padrão e opcionais. Observe que, em ambos os casos, o calendário padrão da cultura também é incluído na CultureInfo.OptionalCalendars coleção.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      // Create a CultureInfo for Thai in Thailand.
      CultureInfo th = CultureInfo.CreateSpecificCulture("th-TH");
      DisplayCalendars(th);

      // Create a CultureInfo for Japanese in Japan.
      CultureInfo ja = CultureInfo.CreateSpecificCulture("ja-JP");
      DisplayCalendars(ja);
   }

   static void DisplayCalendars(CultureInfo ci)
   {
      Console.WriteLine($"Calendars for the {ci.Name} culture:");

      // Get the culture's default calendar.
      Calendar defaultCalendar = ci.Calendar;
      Console.Write("   Default Calendar: {0}", GetCalendarName(defaultCalendar));

      if (defaultCalendar is GregorianCalendar)
         Console.WriteLine($" ({((GregorianCalendar) defaultCalendar).CalendarType})");
      else
         Console.WriteLine();

      // Get the culture's optional calendars.
      Console.WriteLine("   Optional Calendars:");
      foreach (var optionalCalendar in ci.OptionalCalendars) {
         Console.Write("{0,6}{1}", "", GetCalendarName(optionalCalendar));
         if (optionalCalendar is GregorianCalendar)
            Console.Write(" ({0})",
                          ((GregorianCalendar) optionalCalendar).CalendarType);

         Console.WriteLine();
      }
      Console.WriteLine();
   }

   static string GetCalendarName(Calendar cal)
   {
      return cal.ToString().Replace("System.Globalization.", "");
   }
}
// The example displays the following output:
//       Calendars for the th-TH culture:
//          Default Calendar: ThaiBuddhistCalendar
//          Optional Calendars:
//             ThaiBuddhistCalendar
//             GregorianCalendar (Localized)
//
//       Calendars for the ja-JP culture:
//          Default Calendar: GregorianCalendar (Localized)
//          Optional Calendars:
//             GregorianCalendar (Localized)
//             JapaneseCalendar
//             GregorianCalendar (USEnglish)

Imports System.Globalization

Public Module Example
    Public Sub Main()
        ' Create a CultureInfo for Thai in Thailand.
        Dim th As CultureInfo = CultureInfo.CreateSpecificCulture("th-TH")
        DisplayCalendars(th)

        ' Create a CultureInfo for Japanese in Japan.
        Dim ja As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        DisplayCalendars(ja)
    End Sub

    Sub DisplayCalendars(ci As CultureInfo)
        Console.WriteLine("Calendars for the {0} culture:", ci.Name)

        ' Get the culture's default calendar.
        Dim defaultCalendar As Calendar = ci.Calendar
        Console.Write("   Default Calendar: {0}", GetCalendarName(defaultCalendar))

        If TypeOf defaultCalendar Is GregorianCalendar Then
            Console.WriteLine(" ({0})",
                              CType(defaultCalendar, GregorianCalendar).CalendarType)
        Else
            Console.WriteLine()
        End If

        ' Get the culture's optional calendars.
        Console.WriteLine("   Optional Calendars:")
        For Each optionalCalendar In ci.OptionalCalendars
            Console.Write("{0,6}{1}", "", GetCalendarName(optionalCalendar))
            If TypeOf optionalCalendar Is GregorianCalendar Then
                Console.Write(" ({0})",
                              CType(optionalCalendar, GregorianCalendar).CalendarType)
            End If
            Console.WriteLine()
        Next
        Console.WriteLine()
    End Sub

    Function GetCalendarName(cal As Calendar) As String
        Return cal.ToString().Replace("System.Globalization.", "")
    End Function
End Module
' The example displays the following output:
'       Calendars for the th-TH culture:
'          Default Calendar: ThaiBuddhistCalendar
'          Optional Calendars:
'             ThaiBuddhistCalendar
'             GregorianCalendar (Localized)
'       
'       Calendars for the ja-JP culture:
'          Default Calendar: GregorianCalendar (Localized)
'          Optional Calendars:
'             GregorianCalendar (Localized)
'             JapaneseCalendar
'             GregorianCalendar (USEnglish)

O calendário em uso no momento por um objeto CultureInfo específico é definido pela propriedade DateTimeFormatInfo.Calendar da cultura. O objeto DateTimeFormatInfo de uma cultura é retornado pela propriedade CultureInfo.DateTimeFormat. Quando uma cultura é criada, seu valor padrão é o mesmo que o valor da CultureInfo.Calendar propriedade. No entanto, você pode alterar o calendário atual da cultura para qualquer calendário contido no array retornado pela propriedade CultureInfo.OptionalCalendars. Se você tentar definir o calendário atual como um calendário que não está incluído no valor da propriedade CultureInfo.OptionalCalendars, uma ArgumentException será gerada.

O exemplo a seguir altera o calendário usado pela cultura árabe (Arábia Saudita). Ele primeiro cria uma instância de um valor DateTime e o exibe usando a cultura atual – que, nesse caso, é Inglês (Estados Unidos) – e o calendário atual da cultura (que, nesse caso, é o calendário gregoriano). Em seguida, ele altera a cultura atual para árabe (Arábia Saudita) e exibe a data usando seu calendário padrão um Al-Qura. Em seguida, ele chama o CalendarExists método para determinar se o calendário Hijri tem suporte da cultura árabe (Arábia Saudita). Como o calendário tem suporte, ele altera o calendário atual para Hijri e exibe novamente a data. Observe que, em cada caso, a data é exibida usando o calendário atual da cultura atual.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2011, 6, 20);

      DisplayCurrentInfo();
      // Display the date using the current culture and calendar.
      Console.WriteLine(date1.ToString("d"));
      Console.WriteLine();

      CultureInfo arSA = CultureInfo.CreateSpecificCulture("ar-SA");

      // Change the current culture to Arabic (Saudi Arabia).
      Thread.CurrentThread.CurrentCulture = arSA;
      // Display date and information about the current culture.
      DisplayCurrentInfo();
      Console.WriteLine(date1.ToString("d"));
      Console.WriteLine();

      // Change the calendar to Hijri.
      Calendar hijri = new HijriCalendar();
      if (CalendarExists(arSA, hijri)) {
         arSA.DateTimeFormat.Calendar = hijri;
         // Display date and information about the current culture.
         DisplayCurrentInfo();
         Console.WriteLine(date1.ToString("d"));
      }
   }

   private static void DisplayCurrentInfo()
   {
      Console.WriteLine($"Current Culture: {CultureInfo.CurrentCulture.Name}");
      Console.WriteLine($"Current Calendar: {DateTimeFormatInfo.CurrentInfo.Calendar}");
   }

   private static bool CalendarExists(CultureInfo culture, Calendar cal)
   {
      foreach (Calendar optionalCalendar in culture.OptionalCalendars)
         if (cal.ToString().Equals(optionalCalendar.ToString()))
            return true;

      return false;
   }
}
// The example displays the following output:
//    Current Culture: en-US
//    Current Calendar: System.Globalization.GregorianCalendar
//    6/20/2011
//
//    Current Culture: ar-SA
//    Current Calendar: System.Globalization.UmAlQuraCalendar
//    18/07/32
//
//    Current Culture: ar-SA
//    Current Calendar: System.Globalization.HijriCalendar
//    19/07/32

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        Dim date1 As Date = #6/20/2011#

        DisplayCurrentInfo()
        ' Display the date using the current culture and calendar.
        Console.WriteLine(date1.ToString("d"))
        Console.WriteLine()

        Dim arSA As CultureInfo = CultureInfo.CreateSpecificCulture("ar-SA")

        ' Change the current culture to Arabic (Saudi Arabia).
        Thread.CurrentThread.CurrentCulture = arSA
        ' Display date and information about the current culture.
        DisplayCurrentInfo()
        Console.WriteLine(date1.ToString("d"))
        Console.WriteLine()

        ' Change the calendar to Hijri.
        Dim hijri As Calendar = New HijriCalendar()
        If CalendarExists(arSA, hijri) Then
            arSA.DateTimeFormat.Calendar = hijri
            ' Display date and information about the current culture.
            DisplayCurrentInfo()
            Console.WriteLine(date1.ToString("d"))
        End If
    End Sub

    Private Sub DisplayCurrentInfo()
        Console.WriteLine("Current Culture: {0}",
                          CultureInfo.CurrentCulture.Name)
        Console.WriteLine("Current Calendar: {0}",
                          DateTimeFormatInfo.CurrentInfo.Calendar)
    End Sub

    Private Function CalendarExists(ByVal culture As CultureInfo,
                                    cal As Calendar) As Boolean
        For Each optionalCalendar As Calendar In culture.OptionalCalendars
            If cal.ToString().Equals(optionalCalendar.ToString()) Then Return True
        Next
        Return False
    End Function
End Module
' The example displays the following output:
'    Current Culture: en-US
'    Current Calendar: System.Globalization.GregorianCalendar
'    6/20/2011
'    
'    Current Culture: ar-SA
'    Current Calendar: System.Globalization.UmAlQuraCalendar
'    18/07/32
'    
'    Current Culture: ar-SA
'    Current Calendar: System.Globalization.HijriCalendar
'    19/07/32

Datas e calendários

Com exceção dos construtores que incluem um parâmetro de tipo Calendar e permitem que os elementos de uma data (ou seja, o mês, o dia e o ano) reflitam valores em um calendário designado, tanto quanto DateTimeDateTimeOffset os valores são sempre baseados no calendário gregoriano. Isso significa, por exemplo, que a DateTime.Year propriedade retorna o ano no calendário gregoriano, e a DateTime.Day propriedade retorna o dia do mês no calendário gregoriano.

Importante

É importante lembrar que há uma diferença entre um valor de data e sua representação de cadeia de caracteres. O primeiro é baseado no calendário gregoriano; este último se baseia no calendário atual de uma cultura específica.

O exemplo a seguir ilustra essa diferença entre propriedades DateTime e seus métodos Calendar correspondentes. No exemplo, a cultura atual é árabe (Egito), e o calendário atual é Um Al Qura. Um DateTime valor é definido como o décimo quinto dia do sétimo mês de 2011. É claro que isso é interpretado como uma data gregoriana, pois esses mesmos valores são retornados pelo DateTime.ToString(String, IFormatProvider) método quando ele usa as convenções da cultura invariável. A representação de cadeia de caracteres da data formatada usando as convenções da cultura atual é 14/08/32, que é a data equivalente no calendário Um Al Qura. Em seguida, os membros DateTime e Calendar são usados para retornar o dia, o mês e o ano do valor DateTime. Em cada caso, os valores retornados pelos DateTime membros refletem valores no calendário gregoriano, enquanto os valores retornados pelos UmAlQuraCalendar membros refletem valores no calendário Uum al-Qura.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      // Make Arabic (Egypt) the current culture
      // and Umm al-Qura calendar the current calendar.
      CultureInfo arEG = CultureInfo.CreateSpecificCulture("ar-EG");
      Calendar cal = new UmAlQuraCalendar();
      arEG.DateTimeFormat.Calendar = cal;
      Thread.CurrentThread.CurrentCulture = arEG;

      // Display information on current culture and calendar.
      DisplayCurrentInfo();

      // Instantiate a date object.
      DateTime date1 = new DateTime(2011, 7, 15);

      // Display the string representation of the date.
      Console.WriteLine($"Date: {date1:d}");
      Console.WriteLine($"Date in the Invariant Culture: {date1.ToString("d", CultureInfo.InvariantCulture)}");
      Console.WriteLine();

      // Compare DateTime properties and Calendar methods.
      Console.WriteLine($"DateTime.Month property: {date1.Month}");
      Console.WriteLine($"UmAlQura.GetMonth: {cal.GetMonth(date1)}");
      Console.WriteLine();

      Console.WriteLine($"DateTime.Day property: {date1.Day}");
      Console.WriteLine($"UmAlQura.GetDayOfMonth: {cal.GetDayOfMonth(date1)}");
      Console.WriteLine();

      Console.WriteLine($"DateTime.Year property: {date1.Year:D4}");
      Console.WriteLine($"UmAlQura.GetYear: {cal.GetYear(date1)}");
      Console.WriteLine();
   }

   private static void DisplayCurrentInfo()
   {
      Console.WriteLine($"Current Culture: {CultureInfo.CurrentCulture.Name}");
      Console.WriteLine($"Current Calendar: {DateTimeFormatInfo.CurrentInfo.Calendar}");
   }
}
// The example displays the following output:
//    Current Culture: ar-EG
//    Current Calendar: System.Globalization.UmAlQuraCalendar
//    Date: 14/08/32
//    Date in the Invariant Culture: 07/15/2011
//
//    DateTime.Month property: 7
//    UmAlQura.GetMonth: 8
//
//    DateTime.Day property: 15
//    UmAlQura.GetDayOfMonth: 14
//
//    DateTime.Year property: 2011
//    UmAlQura.GetYear: 1432

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        ' Make Arabic (Egypt) the current culture 
        ' and Umm al-Qura calendar the current calendar. 
        Dim arEG As CultureInfo = CultureInfo.CreateSpecificCulture("ar-EG")
        Dim cal As Calendar = New UmAlQuraCalendar()
        arEG.DateTimeFormat.Calendar = cal
        Thread.CurrentThread.CurrentCulture = arEG

        ' Display information on current culture and calendar.
        DisplayCurrentInfo()

        ' Instantiate a date object.
        Dim date1 As Date = #07/15/2011#

        ' Display the string representation of the date.
        Console.WriteLine("Date: {0:d}", date1)
        Console.WriteLine("Date in the Invariant Culture: {0}",
                          date1.ToString("d", CultureInfo.InvariantCulture))
        Console.WriteLine()

        ' Compare DateTime properties and Calendar methods.
        Console.WriteLine("DateTime.Month property: {0}", date1.Month)
        Console.WriteLine("UmAlQura.GetMonth: {0}",
                          cal.GetMonth(date1))
        Console.WriteLine()

        Console.WriteLine("DateTime.Day property: {0}", date1.Day)
        Console.WriteLine("UmAlQura.GetDayOfMonth: {0}",
                          cal.GetDayOfMonth(date1))
        Console.WriteLine()

        Console.WriteLine("DateTime.Year property: {0:D4}", date1.Year)
        Console.WriteLine("UmAlQura.GetYear: {0}",
                          cal.GetYear(date1))
        Console.WriteLine()
    End Sub

    Private Sub DisplayCurrentInfo()
        Console.WriteLine("Current Culture: {0}",
                          CultureInfo.CurrentCulture.Name)
        Console.WriteLine("Current Calendar: {0}",
                          DateTimeFormatInfo.CurrentInfo.Calendar)
    End Sub
End Module
' The example displays the following output:
'    Current Culture: ar-EG
'    Current Calendar: System.Globalization.UmAlQuraCalendar
'    Date: 14/08/32
'    Date in the Invariant Culture: 07/15/2011
'    
'    DateTime.Month property: 7
'    UmAlQura.GetMonth: 8
'    
'    DateTime.Day property: 15
'    UmAlQura.GetDayOfMonth: 14
'    
'    DateTime.Year property: 2011
'    UmAlQura.GetYear: 1432

Instanciar datas com base em um calendário

Como os valores DateTime e DateTimeOffset são baseados no calendário gregoriano, você deve chamar um construtor sobrecarregado que inclui um parâmetro do tipo Calendar para criar uma instância de um valor de data, caso deseje usar os valores de dia, mês ou ano de um calendário diferente. Você também pode chamar uma das sobrecargas do método Calendar.ToDateTime de um calendário específico para instanciar um objeto DateTime com base nos valores daquele calendário.

O exemplo a seguir cria uma instância de um DateTime valor passando um HebrewCalendar objeto para um DateTime construtor e cria uma instância de um segundo DateTime valor chamando o HebrewCalendar.ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) método. Como os dois valores são criados com valores idênticos do calendário hebraico, a chamada para o DateTime.Equals método mostra que os dois DateTime valores são iguais.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      HebrewCalendar hc = new HebrewCalendar();

      DateTime date1 = new DateTime(5771, 6, 1, hc);
      DateTime date2 = hc.ToDateTime(5771, 6, 1, 0, 0, 0, 0);

      Console.WriteLine("{0:d} (Gregorian) = {1:d2}/{2:d2}/{3:d4} ({4}): {5}",
                        date1,
                        hc.GetMonth(date2),
                        hc.GetDayOfMonth(date2),
                        hc.GetYear(date2),
                        GetCalendarName(hc),
                        date1.Equals(date2));
   }

   private static string GetCalendarName(Calendar cal)
   {
      return cal.ToString().Replace("System.Globalization.", "").
                            Replace("Calendar", "");
   }
}
// The example displays the following output:
//    2/5/2011 (Gregorian) = 06/01/5771 (Hebrew): True

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim hc As New HebrewCalendar()

        Dim date1 As New Date(5771, 6, 1, hc)
        Dim date2 As Date = hc.ToDateTime(5771, 6, 1, 0, 0, 0, 0)

        Console.WriteLine("{0:d} (Gregorian) = {1:d2}/{2:d2}/{3:d4} ({4}): {5}",
                          date1,
                          hc.GetMonth(date2),
                          hc.GetDayOfMonth(date2),
                          hc.GetYear(date2),
                          GetCalendarName(hc),
                          date1.Equals(date2))
    End Sub

    Private Function GetCalendarName(cal As Calendar) As String
        Return cal.ToString().Replace("System.Globalization.", "").
                              Replace("Calendar", "")
    End Function
End Module
' The example displays the following output:
'   2/5/2011 (Gregorian) = 06/01/5771 (Hebrew): True

Represente datas no calendário atual

Os métodos de formatação de data e hora sempre usam o calendário atual ao converter datas em cadeias de caracteres. Isso significa que a representação de cadeia de caracteres do ano, o mês e o dia do mês refletem o calendário atual e não refletem necessariamente o calendário gregoriano.

O exemplo a seguir mostra como o calendário atual afeta a representação de cadeia de caracteres de uma data. Ele muda a cultura atual de Chinês (Tradicional, Taiwan) e cria uma instância de um valor de data. Em seguida, ele exibe o calendário atual e a data, altera o calendário atual para TaiwanCalendar, e exibe o calendário e a data atuais mais uma vez. A primeira vez que a data é exibida, ela é representada como uma data no calendário gregoriano. Na segunda vez em que é exibido, ele é representado como uma data no calendário de Taiwan.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      // Change the current culture to zh-TW.
      CultureInfo zhTW = CultureInfo.CreateSpecificCulture("zh-TW");
      Thread.CurrentThread.CurrentCulture = zhTW;
      // Define a date.
      DateTime date1 = new DateTime(2011, 1, 16);

      // Display the date using the default (Gregorian) calendar.
      Console.WriteLine($"Current calendar: {zhTW.DateTimeFormat.Calendar}");
      Console.WriteLine(date1.ToString("d"));

      // Change the current calendar and display the date.
      zhTW.DateTimeFormat.Calendar = new TaiwanCalendar();
      Console.WriteLine($"Current calendar: {zhTW.DateTimeFormat.Calendar}");
      Console.WriteLine(date1.ToString("d"));
   }
}
// The example displays the following output:
//    Current calendar: System.Globalization.GregorianCalendar
//    2011/1/16
//    Current calendar: System.Globalization.TaiwanCalendar
//    100/1/16

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        ' Change the current culture to zh-TW.
        Dim zhTW As CultureInfo = CultureInfo.CreateSpecificCulture("zh-TW")
        Thread.CurrentThread.CurrentCulture = zhTW
        ' Define a date.
        Dim date1 As Date = #1/16/2011#

        ' Display the date using the default (Gregorian) calendar.
        Console.WriteLine("Current calendar: {0}",
                          zhTW.DateTimeFormat.Calendar)
        Console.WriteLine(date1.ToString("d"))

        ' Change the current calendar and display the date.
        zhTW.DateTimeFormat.Calendar = New TaiwanCalendar()
        Console.WriteLine("Current calendar: {0}",
                          zhTW.DateTimeFormat.Calendar)
        Console.WriteLine(date1.ToString("d"))
    End Sub
End Module
' The example displays the following output:
'    Current calendar: System.Globalization.GregorianCalendar
'    2011/1/16
'    Current calendar: System.Globalization.TaiwanCalendar
'    100/1/16

Representar datas em um calendário não atual

Para representar uma data usando um calendário que não é o calendário atual de uma cultura específica, você deve chamar métodos desse Calendar objeto. Por exemplo, os métodos Calendar.GetYear, Calendar.GetMonth e Calendar.GetDayOfMonth convertem o ano, o mês e o dia em valores que refletem um calendário específico.

Aviso

Como alguns calendários são calendários não opcionais de qualquer cultura, representar datas nesses calendários sempre exige que você chame métodos de calendário. Isso é verdadeiro para todos os calendários que derivam das classes EastAsianLunisolarCalendar, JulianCalendar e PersianCalendar.

O exemplo a seguir usa um JulianCalendar objeto para instanciar uma data, 9 de janeiro de 1905, no calendário juliano. Quando essa data é exibida usando o calendário padrão (Gregoriano), ela é representada como 22 de janeiro de 1905. As chamadas para métodos individuais JulianCalendar permitem que a data seja representada no calendário juliano.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      JulianCalendar julian = new JulianCalendar();
      DateTime date1 = new DateTime(1905, 1, 9, julian);

      Console.WriteLine("Date ({0}): {1:d}",
                        CultureInfo.CurrentCulture.Calendar,
                        date1);
      Console.WriteLine("Date in Julian calendar: {0:d2}/{1:d2}/{2:d4}",
                        julian.GetMonth(date1),
                        julian.GetDayOfMonth(date1),
                        julian.GetYear(date1));
   }
}
// The example displays the following output:
//    Date (System.Globalization.GregorianCalendar): 1/22/1905
//    Date in Julian calendar: 01/09/1905

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim julian As New JulianCalendar()
        Dim date1 As New Date(1905, 1, 9, julian)

        Console.WriteLine("Date ({0}): {1:d}",
                          CultureInfo.CurrentCulture.Calendar,
                          date1)
        Console.WriteLine("Date in Julian calendar: {0:d2}/{1:d2}/{2:d4}",
                          julian.GetMonth(date1),
                          julian.GetDayOfMonth(date1),
                          julian.GetYear(date1))
    End Sub
End Module
' The example displays the following output:
'    Date (System.Globalization.GregorianCalendar): 1/22/1905
'    Date in Julian calendar: 01/09/1905

Calendários e intervalos de datas

A data mais antiga suportada por um calendário é indicada pela propriedade Calendar.MinSupportedDateTime desse calendário. Para a classe GregorianCalendar, essa data é 1º de janeiro de 0001 d.C. A maioria dos outros calendários em .NET suporta datas posteriores. Tentar usar um valor de data e hora que antecede a data mais antiga suportada por um calendário resulta em uma exceção ArgumentOutOfRangeException.

No entanto, há uma exceção importante. O valor padrão (não inicializado) de um DateTime objeto e um DateTimeOffset objeto é igual ao GregorianCalendar.MinSupportedDateTime valor. Se você tentar formatar essa data em um calendário que não dá suporte a 1º de janeiro de 0001 C.E. e não fornecer um especificador de formato, o método de formatação usará o especificador de formato "s" (padrão de data/hora classificável) em vez do especificador de formato "G" (padrão de data/hora geral). Como resultado, a operação de formatação não gera uma exceção ArgumentOutOfRangeException . Em vez disso, retorna a data sem suporte. Isso é ilustrado no exemplo a seguir, que exibe o valor de DateTime.MinValue quando a cultura atual é definida como japonês (Japão) com o calendário japonês e para árabe (Egito) com o calendário Um Al Qura. Ela também define a cultura atual como Inglês (Estados Unidos) e chama o método DateTime.ToString(IFormatProvider) com cada um desses objetos CultureInfo. Em cada caso, a data é exibida usando o padrão de data/hora classificável.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      DateTime dat = DateTime.MinValue;

      // Change the current culture to ja-JP with the Japanese Calendar.
      CultureInfo jaJP = CultureInfo.CreateSpecificCulture("ja-JP");
      jaJP.DateTimeFormat.Calendar = new JapaneseCalendar();
      Thread.CurrentThread.CurrentCulture = jaJP;
      Console.WriteLine($"Earliest supported date by {GetCalendarName(jaJP)} calendar: {jaJP.DateTimeFormat.Calendar.MinSupportedDateTime:d}");
      // Attempt to display the date.
      Console.WriteLine(dat.ToString());
      Console.WriteLine();

      // Change the current culture to ar-EG with the Um Al Qura calendar.
      CultureInfo arEG = CultureInfo.CreateSpecificCulture("ar-EG");
      arEG.DateTimeFormat.Calendar = new UmAlQuraCalendar();
      Thread.CurrentThread.CurrentCulture = arEG;
      Console.WriteLine($"Earliest supported date by {GetCalendarName(arEG)} calendar: {arEG.DateTimeFormat.Calendar.MinSupportedDateTime:d}");
      // Attempt to display the date.
      Console.WriteLine(dat.ToString());
      Console.WriteLine();

      // Change the current culture to en-US.
      Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("en-US");
      Console.WriteLine(dat.ToString(jaJP));
      Console.WriteLine(dat.ToString(arEG));
      Console.WriteLine(dat.ToString("d"));
   }

   private static string GetCalendarName(CultureInfo culture)
   {
      Calendar cal = culture.DateTimeFormat.Calendar;
      return cal.GetType().Name.Replace("System.Globalization.", "").Replace("Calendar", "");
   }
}
// The example displays the following output:
//       Earliest supported date by Japanese calendar: 明治 1/9/8
//       0001-01-01T00:00:00
//
//       Earliest supported date by UmAlQura calendar: 01/01/18
//       0001-01-01T00:00:00
//
//       0001-01-01T00:00:00
//       0001-01-01T00:00:00
//       1/1/0001

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        Dim dat As Date = DateTime.MinValue

        ' Change the current culture to ja-JP with the Japanese Calendar.
        Dim jaJP As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        jaJP.DateTimeFormat.Calendar = New JapaneseCalendar()
        Thread.CurrentThread.CurrentCulture = jaJP
        Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
                          jaJP.DateTimeFormat.Calendar.MinSupportedDateTime,
                          GetCalendarName(jaJP))
        ' Attempt to display the date.
        Console.WriteLine(dat.ToString())
        Console.WriteLine()

        ' Change the current culture to ar-EG with the Um Al Qura calendar.
        Dim arEG As CultureInfo = CultureInfo.CreateSpecificCulture("ar-EG")
        arEG.DateTimeFormat.Calendar = New UmAlQuraCalendar()
        Thread.CurrentThread.CurrentCulture = arEG
        Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
                          arEG.DateTimeFormat.Calendar.MinSupportedDateTime,
                          GetCalendarName(arEG))
        ' Attempt to display the date.
        Console.WRiteLine(dat.ToString())
        Console.WRiteLine()

        ' Change the current culture to en-US.
        Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("en-US")
        Console.WriteLine(dat.ToString(jaJP))
        Console.WriteLine(dat.ToString(arEG))
        Console.WriteLine(dat.ToString("d"))
    End Sub

    Private Function GetCalendarName(culture As CultureInfo) As String
        Dim cal As Calendar = culture.DateTimeFormat.Calendar
        Return cal.GetType().Name.Replace("System.Globalization.", "").Replace("Calendar", "")
    End Function
End Module
' The example displays the following output:
'       Earliest supported date by Japanese calendar: 明治 1/9/8
'       0001-01-01T00:00:00
'       
'       Earliest supported date by UmAlQura calendar: 01/01/18
'       0001-01-01T00:00:00
'       
'       0001-01-01T00:00:00
'       0001-01-01T00:00:00
'       1/1/0001

Trabalhar com eras

Os calendários normalmente dividem datas em eras. No entanto, as Calendar classes no .NET não dão suporte a todas as eras definidas por um calendário e a maioria das classes dá suporte apenas a Calendar uma única era. Somente as JapaneseCalendar e JapaneseLunisolarCalendar classes dão suporte a várias eras.

Importante

A era Reiwa, uma nova era no JapaneseCalendar e JapaneseLunisolarCalendar, começa em 1º de maio de 2019. Essa alteração afeta todos os aplicativos que usam esses calendários. Confira os artigos a seguir para saber mais:

Uma era na maioria dos calendários indica um período de tempo extremamente longo. No calendário gregoriano, por exemplo, a era atual abrange mais de dois milênios. Para o JapaneseCalendar e o JapaneseLunisolarCalendar, os dois calendários que dão suporte a várias eras, isso não é o caso. Uma era corresponde ao período do reinado de um imperador. O suporte para várias eras, especialmente quando o limite superior da era atual é desconhecido, apresenta desafios especiais.

Eras e nomes de era

No .NET, os inteiros que representam as eras compatíveis com uma implementação de calendário específica são armazenados em ordem inversa na Calendar.Eras matriz. A era atual (que é a era com o intervalo de tempo mais recente) está no índice zero e, para Calendar classes que dão suporte a várias eras, cada índice sucessivo reflete a era anterior. A propriedade estática Calendar.CurrentEra define o índice da era atual na Calendar.Eras matriz; é uma constante cujo valor é sempre zero. Classes individuais Calendar também incluem campos estáticos que retornam o valor da era atual. Eles estão listados na tabela a seguir.

Classe do calendário Campo de era atual
ChineseLunisolarCalendar ChineseEra
GregorianCalendar ADEra
HebrewCalendar HebrewEra
HijriCalendar HijriEra
JapaneseLunisolarCalendar JapaneseEra
JulianCalendar JulianEra
KoreanCalendar KoreanEra
KoreanLunisolarCalendar GregorianEra
PersianCalendar PersianEra
ThaiBuddhistCalendar ThaiBuddhistEra
UmAlQuraCalendar UmAlQuraEra

O nome que corresponde a um número de era específico pode ser recuperado passando o número de era para o método DateTimeFormatInfo.GetEraName ou DateTimeFormatInfo.GetAbbreviatedEraName. O exemplo a seguir chama esses métodos para recuperar informações sobre o suporte a eras na classe GregorianCalendar. Ele exibe a data do calendário gregoriano que corresponde a 1º de janeiro do segundo ano da era atual, bem como a data do calendário gregoriano que corresponde a 1º de janeiro do segundo ano de cada era de calendário japonês com suporte.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      int year = 2;
      int month = 1;
      int day = 1;
      Calendar cal = new JapaneseCalendar();

      Console.WriteLine("\nDate instantiated without an era:");
      DateTime date1 = new DateTime(year, month, day, 0, 0, 0, 0, cal);
      Console.WriteLine("{0}/{1}/{2} in Japanese Calendar -> {3:d} in Gregorian",
                        cal.GetMonth(date1), cal.GetDayOfMonth(date1),
                        cal.GetYear(date1), date1);

      Console.WriteLine("\nDates instantiated with eras:");
      foreach (int era in cal.Eras) {
         DateTime date2 = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era);
         Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
                           cal.GetMonth(date2), cal.GetDayOfMonth(date2),
                           cal.GetYear(date2), cal.GetEra(date2), date2);
      }
   }
}

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim year As Integer = 2
        Dim month As Integer = 1
        Dim day As Integer = 1
        Dim cal As New JapaneseCalendar()

        Console.WriteLine("Date instantiated without an era:")
        Dim date1 As New Date(year, month, day, 0, 0, 0, 0, cal)
        Console.WriteLine("{0}/{1}/{2} in Japanese Calendar -> {3:d} in Gregorian",
                          cal.GetMonth(date1), cal.GetDayOfMonth(date1),
                          cal.GetYear(date1), date1)
        Console.WriteLine()

        Console.WriteLine("Dates instantiated with eras:")
        For Each era As Integer In cal.Eras
            Dim date2 As Date = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era)
            Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
                              cal.GetMonth(date2), cal.GetDayOfMonth(date2),
                              cal.GetYear(date2), cal.GetEra(date2), date2)
        Next
    End Sub
End Module

Além disso, a cadeia de caracteres de formato de data e hora personalizado "g" inclui o nome da era na representação de cadeia de caracteres de uma data e hora. Para obter mais informações, consulte Cadeias de caracteres personalizadas de formato data e hora.

Criar uma instância de uma data com uma era

Para as duas Calendar classes que dão suporte a várias eras, uma data que consiste em um determinado ano, mês e dia do valor do mês pode ser ambígua. Por exemplo, todas as eras compatíveis com o JapaneseCalendar começam com o ano 1. Normalmente, se uma era não for especificada, os métodos de data e hora e calendário pressupõem que os valores pertencem à era atual. Isso é verdadeiro tanto para os construtores DateTime e DateTimeOffset que incluem parâmetros de tipo Calendar, quanto para os métodos JapaneseCalendar.ToDateTime e JapaneseLunisolarCalendar.ToDateTime. O exemplo a seguir cria uma data que representa 1º de janeiro do segundo ano de uma era não especificada. Se você executar o exemplo quando a era Reiwa for a era atual, a data será interpretada como o segundo ano da era Reiwa. A era, 令和, precede o ano na cadeia de caracteres retornada pelo DateTime.ToString(String, IFormatProvider) método e corresponde a 1º de janeiro de 2020, no calendário gregoriano. (A era Reiwa começa no ano de 2019 do calendário gregoriano.)

using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;

        var date = new DateTime(2, 1, 1, japaneseCal);
        Console.WriteLine($"Gregorian calendar date: {date:d}");
        Console.WriteLine($"Japanese calendar date: {date.ToString("d", jaJp)}");
    }
}

Imports System.Globalization

Public Module Example
    Public Sub Main()
        Dim japaneseCal = New JapaneseCalendar()
        Dim jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal

        Dim dat = New DateTime(2, 1, 1, japaneseCal)
        Console.WriteLine($"Gregorian calendar dat: {dat:d}")
        Console.WriteLine($"Japanese calendar dat: {dat.ToString("d", jaJp)}")
    End Sub
End Module

No entanto, se a era mudar, a intenção desse código se tornará ambígua. A data destina-se a representar o segundo ano da era atual, ou pretende-se representar o segundo ano da era Heisei? Há duas maneiras de evitar essa ambiguidade:

  • Instancie o valor de data e hora usando a classe padrão GregorianCalendar . Em seguida, você pode usar o calendário japonês ou o calendário lunisolar japonês para a representação de cadeia de caracteres de datas, como mostra o exemplo a seguir.

    using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;

        var date = new DateTime(1905, 2, 12);
        Console.WriteLine($"Gregorian calendar date: {date:d}");

        // Call the ToString(IFormatProvider) method.
        Console.WriteLine($"Japanese calendar date: {date.ToString("d", jaJp)}");

        // Use a FormattableString object.
        FormattableString fmt = $"{date:d}";
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}");

        // Use the JapaneseCalendar object.
        Console.WriteLine($"Japanese calendar date: {jaJp.DateTimeFormat.GetEraName(japaneseCal.GetEra(date))}" +
                          $"{japaneseCal.GetYear(date)}/{japaneseCal.GetMonth(date)}/{japaneseCal.GetDayOfMonth(date)}");

        // Use the current culture.
        CultureInfo.CurrentCulture = jaJp;
        Console.WriteLine($"Japanese calendar date: {date:d}");
    }
}
// The example displays the following output:
//   Gregorian calendar date: 2/12/1905
//   Japanese calendar date: 明治38/2/12
//   Japanese calendar date: 明治38/2/12
//   Japanese calendar date: 明治38/2/12
//   Japanese calendar date: 明治38/2/12

    Imports System.Globalization

Public Module Example
    Public Sub Main()
        Dim japaneseCal = New JapaneseCalendar()
        Dim jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal

        Dim dat = New DateTime(1905, 2, 12)
        Console.WriteLine($"Gregorian calendar date: {dat:d}")

        ' Call the ToString(IFormatProvider) method.
        Console.WriteLine($"Japanese calendar date: {dat.ToString("d", jaJp)}")

        ' Use a FormattableString object.
        Dim fmt As FormattableString = $"{dat:d}"
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}")

        ' Use the JapaneseCalendar object.
        Console.WriteLine($"Japanese calendar date: {jaJp.DateTimeFormat.GetEraName(japaneseCal.GetEra(dat))}" +
                          $"{japaneseCal.GetYear(dat)}/{japaneseCal.GetMonth(dat)}/{japaneseCal.GetDayOfMonth(dat)}")

        ' Use the current culture.
        CultureInfo.CurrentCulture = jaJp
        Console.WriteLine($"Japanese calendar date: {dat:d}")
    End Sub
End Module
' The example displays the following output:
'   Gregorian calendar date: 2/12/1905
'   Japanese calendar date: 明治38/2/12
'   Japanese calendar date: 明治38/2/12
'   Japanese calendar date: 明治38/2/12
'   Japanese calendar date: 明治38/2/12

  • Chame um método de data e hora que especifica explicitamente uma era. Isso inclui os seguintes métodos:

    O exemplo a seguir usa três desses métodos para instanciar uma data e hora na era Meiji, que começou em 8 de setembro de 1868 e terminou em 29 de julho de 1912.

    using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;

        // We can get the era index by calling DateTimeFormatInfo.GetEraName.
        int eraIndex = 0;

        for (int ctr = 0; ctr < jaJp.DateTimeFormat.Calendar.Eras.Length; ctr++)
           if (jaJp.DateTimeFormat.GetEraName(ctr) == "明治")
              eraIndex = ctr;
        var date1 = japaneseCal.ToDateTime(23, 9, 8, 0, 0, 0, 0, eraIndex);
        Console.WriteLine($"{date1.ToString("d", jaJp)} (Gregorian {date1:d})");

        try {
            var date2 = DateTime.Parse("明治23/9/8", jaJp);
            Console.WriteLine($"{date2.ToString("d", jaJp)} (Gregorian {date2:d})");
        }
        catch (FormatException)
        {
            Console.WriteLine("The parsing operation failed.");
        }

        try {
            var date3 = DateTime.ParseExact("明治23/9/8", "gyy/M/d", jaJp);
            Console.WriteLine($"{date3.ToString("d", jaJp)} (Gregorian {date3:d})");
        }
        catch (FormatException)
        {
            Console.WriteLine("The parsing operation failed.");
        }
    }
}
// The example displays the following output:
//   明治23/9/8 (Gregorian 9/8/1890)
//   明治23/9/8 (Gregorian 9/8/1890)
//   明治23/9/8 (Gregorian 9/8/1890)

    Imports System.Globalization

Public Module Example
    Public Sub Main()
        Dim japaneseCal = New JapaneseCalendar()
        Dim jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal

        ' We can get the era index by calling DateTimeFormatInfo.GetEraName.
        Dim eraIndex As Integer = 0

        For ctr As Integer = 0 To jaJp.DateTimeFormat.Calendar.Eras.Length - 1
            If jaJp.DateTimeFormat.GetEraName(ctr) = "明治" Then eraIndex = ctr
        Next
        Dim date1 = japaneseCal.ToDateTime(23, 9, 8, 0, 0, 0, 0, eraIndex)
        Console.WriteLine($"{date1.ToString("d", jaJp)} (Gregorian {date1:d})")

        Try
            Dim date2 = DateTime.Parse("明治23/9/8", jaJp)
            Console.WriteLine($"{date2.ToString("d", jaJp)} (Gregorian {date2:d})")
        Catch e As FormatException
            Console.WriteLine("The parsing operation failed.")
        End Try

        Try
            Dim date3 = DateTime.ParseExact("明治23/9/8", "gyy/M/d", jaJp)
            Console.WriteLine($"{date3.ToString("d", jaJp)} (Gregorian {date3:d})")
        Catch e As FormatException
            Console.WriteLine("The parsing operation failed.")
        End Try
    End Sub
End Module
' The example displays the following output:
'   明治23/9/8 (Gregorian 9/8/1890)
'   明治23/9/8 (Gregorian 9/8/1890)
'   明治23/9/8 (Gregorian 9/8/1890)

Dica

Ao trabalhar com calendários que dão suporte a várias eras, sempre use a data gregoriana para instanciar uma data ou especifique a era quando você instanciar uma data e hora com base nesse calendário.

Ao especificar uma era para o ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) método, você fornece o índice da era na propriedade do Eras calendário. Para calendários cujas eras estão sujeitas a alterações, no entanto, esses índices não são valores constantes; a era atual está no índice 0 e a era mais antiga está no índice Eras.Length - 1. Quando uma nova era é adicionada a um calendário, os índices das eras anteriores aumentam em um. É possível fornecer o índice de era apropriado da seguinte maneira:

Calendários, eras e intervalos de datas: verificações de intervalo reduzidas

Assim como os calendários individuais têm intervalos de datas suportados, as eras nas classes JapaneseCalendar e JapaneseLunisolarCalendar também têm intervalos suportados. Anteriormente, o .NET usava verificações estritas de intervalo de era para garantir que uma data específica da era estivesse no intervalo daquela época. Ou seja, se uma data estiver fora do intervalo da era especificada, o método gerará um ArgumentOutOfRangeException. Atualmente, o .NET usa a verificação de intervalo reduzida por padrão. As atualizações a todas as versões do .NET introduziram verificações reduzidas de intervalo de era; a tentativa de criar uma instância de data específica da era que está fora do intervalo da era especificada "estoura" para a era seguinte e nenhuma exceção é lançada.

O exemplo a seguir tenta instanciar uma data no 65º ano da era Showa, que começou em 25 de dezembro de 1926 e terminou em 7 de janeiro de 1989. Essa data corresponde a 9 de janeiro de 1990, que está fora do intervalo da era Showa no JapaneseCalendar. Como ilustra a saída do exemplo, a data exibida pelo exemplo é 9 de janeiro de 1990, no segundo ano da era Heisei.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      var jaJp = new CultureInfo("ja-JP");
      var cal = new JapaneseCalendar();
      jaJp.DateTimeFormat.Calendar = cal;
      string showaEra = "昭和";

      var dt = cal.ToDateTime(65, 1, 9, 15, 0, 0, 0, GetEraIndex(showaEra));
      FormattableString fmt = $"{dt:d}";

      Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}");
      Console.WriteLine($"Gregorian calendar date: {fmt}");

      int GetEraIndex(string eraName)
      {
         foreach (var ctr in cal.Eras)
            if (jaJp.DateTimeFormat.GetEraName(ctr) == eraName)
               return ctr;

         return 0;
      }
   }
}
// The example displays the following output:
//   Japanese calendar date: 平成2/1/9
//   Gregorian calendar date: 1/9/1990

Imports System.Globalization

Public Module Example
    Dim jaJp As CultureInfo
    Dim cal As Calendar

    Public Sub Main()
        jaJp = New CultureInfo("ja-JP")
        cal = New JapaneseCalendar()
        jaJp.DateTimeFormat.Calendar = cal
        Dim showaEra = "昭和"

        Dim dt = cal.ToDateTime(65, 1, 9, 15, 0, 0, 0, GetEraIndex(showaEra))
        Dim fmt As FormattableString = $"{dt:d}"
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}")
        Console.WriteLine($"Gregorian calendar date: {fmt}")
    End Sub

    Private Function GetEraIndex(eraName As String) As Integer
        For Each ctr As Integer In cal.Eras
            If jaJp.DateTimeFormat.GetEraName(ctr) = eraName Then Return ctr
        Next
        Return 0
    End Function
End Module
' The example displays the following output:
'   Japanese calendar date: 平成2/1/9
'   Gregorian calendar date: 1/9/1990

Se as verificações de intervalo descontraídas forem indesejáveis, você poderá restaurar verificações de intervalo estritas de várias maneiras, dependendo da versão do .NET na qual seu aplicativo está em execução:

  • .NET Core: Adicione o seguinte ao arquivo de configuração .netcore.runtime.json :

    "runtimeOptions": {
  "configProperties": {
      "Switch.System.Globalization.EnforceJapaneseEraYearRanges": true
  }
}

  • .NET Framework 4.6 ou posterior: Defina a seguinte opção AppContext no arquivo app.config :

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Globalization.EnforceJapaneseEraYearRanges=true" />
  </runtime>
</configuration>

  • .NET Framework 4.5.2 ou anterior: Defina o seguinte valor do Registro:

    Valor
    Chave HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
    de Entrada Switch.System.Globalization.EnforceJapaneseEraYearRanges
    Tipo REG_SZ
    Valor verdadeiro

Com verificações de intervalo estritas habilitadas, o exemplo anterior gera um ArgumentOutOfRangeException e exibe a seguinte saída:

Unhandled Exception: System.ArgumentOutOfRangeException: Valid values are between 1 and 64, inclusive.
Parameter name: year
   at System.Globalization.GregorianCalendarHelper.GetYearOffset(Int32 year, Int32 era, Boolean throwOnError)
   at System.Globalization.GregorianCalendarHelper.ToDateTime(Int32 year, Int32 month, Int32 day, Int32 hour, Int32 minute, Int32 second, Int32 millisecond, Int32 era)
   at Example.Main()

Representar datas em calendários com várias eras

Se um objeto Calendar oferece suporte a eras e é o calendário atual de um objeto CultureInfo, a era está incluída na representação de cadeia de caracteres de um valor de data e hora para os padrões de data e hora completa, data completa e data abreviada. O exemplo a seguir exibe esses padrões de data quando a cultura atual é Japão (japonês) e o calendário atual é o calendário japonês.

using System;
using System.Globalization;
using System.IO;
using System.Threading;

public class Example
{
   public static void Main()
   {
      StreamWriter sw = new StreamWriter(@".\eras.txt");
      DateTime dt = new DateTime(2012, 5, 1);

      CultureInfo culture = CultureInfo.CreateSpecificCulture("ja-JP");
      DateTimeFormatInfo dtfi = culture.DateTimeFormat;
      dtfi.Calendar = new JapaneseCalendar();
      Thread.CurrentThread.CurrentCulture = culture;

      sw.WriteLine("\n{0,-43} {1}", "Full Date and Time Pattern:", dtfi.FullDateTimePattern);
      sw.WriteLine(dt.ToString("F"));
      sw.WriteLine();

      sw.WriteLine("\n{0,-43} {1}", "Long Date Pattern:", dtfi.LongDatePattern);
      sw.WriteLine(dt.ToString("D"));

      sw.WriteLine("\n{0,-43} {1}", "Short Date Pattern:", dtfi.ShortDatePattern);
      sw.WriteLine(dt.ToString("d"));
      sw.Close();
    }
}
// The example writes the following output to a file:
//    Full Date and Time Pattern:                 gg y'年'M'月'd'日' H:mm:ss
//    平成 24年5月1日 0:00:00
//
//    Long Date Pattern:                          gg y'年'M'月'd'日'
//    平成 24年5月1日
//
//    Short Date Pattern:                         gg y/M/d
//    平成 24/5/1

Imports System.Globalization
Imports System.IO
Imports System.Threading

Module Example
    Public Sub Main()
        Dim sw As New StreamWriter(".\eras.txt")
        Dim dt As Date = #05/01/2012#

        Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        Dim dtfi As DateTimeFormatInfo = culture.DateTimeFormat
        dtfi.Calendar = New JapaneseCalendar()
        Thread.CurrentThread.CurrentCulture = culture

        sw.WriteLine("{0,-43} {1}", "Full Date and Time Pattern:", dtfi.FullDateTimePattern)
        sw.WriteLine(dt.ToString("F"))
        sw.WriteLine()

        sw.WriteLine("{0,-43} {1}", "Long Date Pattern:", dtfi.LongDatePattern)
        sw.WriteLine(dt.ToString("D"))
        sw.WriteLine()

        sw.WriteLine("{0,-43} {1}", "Short Date Pattern:", dtfi.ShortDatePattern)
        sw.WriteLine(dt.ToString("d"))
        sw.WriteLine()
        sw.Close()
    End Sub
End Module
' The example writes the following output to a file:
'    Full Date and Time Pattern:                 gg y'年'M'月'd'日' H:mm:ss
'    平成 24年5月1日 0:00:00
'    
'    Long Date Pattern:                          gg y'年'M'月'd'日'
'    平成 24年5月1日
'    
'    Short Date Pattern:                         gg y/M/d
'    平成 24/5/1

Aviso

A JapaneseCalendar classe é a única classe de calendário no .NET que dá suporte a datas em mais de uma era e que pode ser o calendário atual de um CultureInfo objeto - especificamente, de um CultureInfo objeto que representa a cultura japonesa (Japão).

Para todos os calendários, o especificador de formato personalizado "g" inclui a era na cadeia de caracteres de resultado. O exemplo a seguir usa a cadeia de caracteres de formato personalizado "MM-dd-yyyyy g" para incluir a era na cadeia de caracteres de resultado quando o calendário atual é o calendário gregoriano.

   DateTime dat = new DateTime(2012, 5, 1);
   Console.WriteLine($"{dat:MM-dd-yyyy g}");
// The example displays the following output:
//     05-01-2012 A.D.

Dim dat As Date = #05/01/2012#
Console.WriteLine("{0:MM-dd-yyyy g}", dat)
' The example displays the following output:
'     05-01-2012 A.D.

Nos casos em que a representação de cadeia de caracteres de uma data é expressa em um calendário que não é o calendário atual, a Calendar classe inclui um Calendar.GetEra método que pode ser usado junto com o Calendar.GetYear, Calendar.GetMonthe Calendar.GetDayOfMonth métodos para indicar de forma inequívoca uma data, bem como a era à qual ela pertence. O exemplo a seguir usa a JapaneseLunisolarCalendar classe para fornecer uma ilustração. No entanto, observe que incluir um nome ou abreviação significativa em vez de um número inteiro para a era na string de resultado requer que você instancie um objeto DateTimeFormatInfo e defina JapaneseCalendar como seu calendário atual. (O JapaneseLunisolarCalendar calendário não pode ser o calendário atual de nenhuma cultura, mas, nesse caso, os dois calendários compartilham as mesmas eras.)

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2011, 8, 28);
      Calendar cal = new JapaneseLunisolarCalendar();

      Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                        cal.GetEra(date1),
                        cal.GetYear(date1),
                        cal.GetMonth(date1),
                        cal.GetDayOfMonth(date1));

      // Display eras
      CultureInfo culture = CultureInfo.CreateSpecificCulture("ja-JP");
      DateTimeFormatInfo dtfi = culture.DateTimeFormat;
      dtfi.Calendar = new JapaneseCalendar();

      Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                        dtfi.GetAbbreviatedEraName(cal.GetEra(date1)),
                        cal.GetYear(date1),
                        cal.GetMonth(date1),
                        cal.GetDayOfMonth(date1));
   }
}
// The example displays the following output:
//       4 0023/07/29
//       平 0023/07/29

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim date1 As Date = #8/28/2011#
        Dim cal As New JapaneseLunisolarCalendar()
        Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                          cal.GetEra(date1),
                          cal.GetYear(date1),
                          cal.GetMonth(date1),
                          cal.GetDayOfMonth(date1))

        ' Display eras
        Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        Dim dtfi As DateTimeFormatInfo = culture.DateTimeFormat
        dtfi.Calendar = New JapaneseCalendar()

        Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                          dtfi.GetAbbreviatedEraName(cal.GetEra(date1)),
                          cal.GetYear(date1),
                          cal.GetMonth(date1),
                          cal.GetDayOfMonth(date1))
    End Sub
End Module
' The example displays the following output:
'       4 0023/07/29
'       平 0023/07/29

Nos calendários japoneses, o primeiro ano de uma era é chamado de Gannen (元年). Por exemplo, em vez de Heisei 1, o primeiro ano da era Heisei pode ser descrito como Heisei Gannen. O .NET adota essa convenção em operações de formatação para datas e horas formatadas com as seguintes cadeias de caracteres de formato de data e hora padrão ou personalizadas quando são usadas com um objeto CultureInfo que representa a cultura Japonesa-Japão ("ja-JP") com a classe JapaneseCalendar:

Por exemplo, o exemplo a seguir exibe uma data no primeiro ano da era Heisei no JapaneseCalendar.

using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
         var enUs = new CultureInfo("en-US");
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;
        string heiseiEra = "平成";

        var date = japaneseCal.ToDateTime(1, 8, 18, 0, 0, 0, 0, GetEraIndex(heiseiEra));
        FormattableString fmt = $"{date:D}";
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)} (Gregorian: {fmt.ToString(enUs)})");

        int GetEraIndex(string eraName)
        {
           foreach (var ctr in japaneseCal.Eras)
              if (jaJp.DateTimeFormat.GetEraName(ctr) == eraName)
                 return ctr;

           return 0;
        }
    }
}
// The example displays the following output:
//    Japanese calendar date: 平成元年8月18日 (Gregorian: Friday, August 18, 1989)

Imports System.Globalization

Module Program
    Dim jaJp As CultureInfo
    Dim japaneseCal As Calendar

    Sub Main()
        Dim enUs = New CultureInfo("en-US")
        japaneseCal = New JapaneseCalendar()
        jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal
        Dim heiseiEra = "平成"

        Dim dat = japaneseCal.ToDateTime(1, 8, 18, 0, 0, 0, 0, GetEraIndex(heiseiEra))
        Dim fmt As FormattableString = $"{dat:D}"
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)} (Gregorian: {fmt.ToString(enUs)})")
    End Sub

    Private Function GetEraIndex(eraName As String) As Integer
        For Each ctr In japaneseCal.Eras
            If jaJp.DateTimeFormat.GetEraName(ctr) = eraName Then
                Return ctr
            End If
        Next
        Return 0
    End Function
End Module
' The example displays the following output:
'    Japanese calendar date: 平成元年8月18日 (Gregorian: Friday, August 18, 1989)

Se esse comportamento for indesejável em operações de formatação, você poderá restaurar o comportamento anterior, que sempre representa o primeiro ano de uma era como "1" em vez de "Gannen", fazendo o seguinte, dependendo da versão do .NET:

  • .NET Core: Adicione o seguinte ao arquivo de configuração .netcore.runtime.json :

    "runtimeOptions": {
  "configProperties": {
      "Switch.System.Globalization.FormatJapaneseFirstYearAsANumber": true
  }
}

  • .NET Framework 4.6 ou posterior: Defina a seguinte opção AppContext no arquivo app.config :

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Globalization.FormatJapaneseFirstYearAsANumber=true" />
  </runtime>
</configuration>

  • .NET Framework 4.5.2 ou anterior: Defina o seguinte valor do Registro:

    Valor
    Chave HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
    de Entrada Switch.System.Globalization.FormatJapaneseFirstYearAsANumber
    Tipo REG_SZ
    Valor verdadeiro

Com o suporte de gannen em operações de formatação desabilitado, o exemplo anterior exibe a seguinte saída:

Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989)

O .NET também foi atualizado para que as operações de análise de data e hora ofereçam suporte a cadeias de caracteres que contêm o ano representado como "1" ou Gannen. Embora não seja necessário fazer isso, você pode restaurar o comportamento anterior para reconhecer apenas "1" como o primeiro ano de uma era. Você pode fazer isso da seguinte maneira, dependendo da versão do .NET:

  • .NET Core: Adicione o seguinte ao arquivo de configuração .netcore.runtime.json :

    "runtimeOptions": {
  "configProperties": {
      "Switch.System.Globalization.EnforceLegacyJapaneseDateParsing": true
  }
}

  • .NET Framework 4.6 ou posterior: Defina a seguinte opção AppContext no arquivo app.config :

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Globalization.EnforceLegacyJapaneseDateParsing=true" />
  </runtime>
</configuration>

  • .NET Framework 4.5.2 ou anterior: Defina o seguinte valor do Registro:

    Valor
    Chave HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
    de Entrada Switch.System.Globalization.EnforceLegacyJapaneseDateParsing
    Tipo REG_SZ
    Valor verdadeiro

Consulte também