使用行事曆

2025-04-03

雖然日期和時間值表示一個特定的時刻，但其字串表示與文化相關，會根據特定文化用來顯示日期和時間值的慣例，以及該文化使用的行事曆而有所不同。本主題探討 .NET 中行事曆的支援，並討論使用日期值時行事曆類別的使用方式。

.NET 中的行事曆

.NET 中的所有行事曆都衍生自 System.Globalization.Calendar 類別，其提供基準行事歷實作。繼承自 Calendar 類別的其中一個類別是 EastAsianLunisolarCalendar 類別，這是所有 lunisolar 行事曆的基類。 .NET 包含下列行事曆實作：

ChineseLunisolarCalendar，代表中國陰陰曆。
GregorianCalendar，表示公曆。此日曆會進一步地依據System.Globalization.GregorianCalendarTypes列舉定義分為不同的子類型（例如阿拉伯文和中東法文）。屬性 GregorianCalendar.CalendarType 會指定公曆的子類型。
HebrewCalendar，表示希伯來歷。
HijriCalendar，表示Hijri行事曆。
JapaneseCalendar，表示日本曆。
JapaneseLunisolarCalendar，表示日本的陰陰曆。
JulianCalendar，表示朱利安曆。
KoreanCalendar，表示韓曆。
KoreanLunisolarCalendar，代表韓國陰曆。
PersianCalendar，表示波斯曆法。
TaiwanCalendar，代表台灣日曆。
TaiwanLunisolarCalendar，代表臺灣陰陰曆。
ThaiBuddhistCalendar，代表泰國佛教歷法。
UmAlQuraCalendar，表示 Um Al Qura 行事曆。

行事曆可透過下列兩種方式之一使用：

作為特定文化所使用的曆法。每個 CultureInfo 物件都有一個目前的行事曆，這是物件目前使用的行事曆。所有日期和時間值的字串表示會自動反映目前的文化特性及其目前的行事曆。一般而言，目前的行事曆是文化特性的預設行事曆。 CultureInfo 物件也有選擇性的行事曆，其中包括文化特性可以使用的其他行事曆。
作為一個獨立於特定文化的行事曆。在此情況下， Calendar 方法會用來將日期表示為反映行事曆的值。

請注意，六個行事歷類別 – ChineseLunisolarCalendar、、JapaneseLunisolarCalendar、JulianCalendar KoreanLunisolarCalendar、 PersianCalendar和 TaiwanLunisolarCalendar – 只能當做獨立行事曆使用。任何文化都不會使用它們作為預設行事曆或可選行事曆。

行事曆與文化

每個文化特性都有預設行事曆，由 CultureInfo.Calendar 屬性定義。屬性 CultureInfo.OptionalCalendars 會傳回物件的陣列 Calendar ，指定特定文化特性支援的所有行事曆，包括該文化特性的預設行事曆。

下列範例說明 CultureInfo.Calendar 和 CultureInfo.OptionalCalendars 屬性。它為 CultureInfo 泰國（泰國）和日本（日本）文化建立物件，並顯示其預設和選擇性行事曆。請注意，在這兩種情況下，文化的預設行事曆也會包含在集合中CultureInfo.OptionalCalendars。

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)

特定 CultureInfo 物件目前使用的行事曆是由文化特性的 DateTimeFormatInfo.Calendar 屬性所定義。 DateTimeFormatInfo 物件是由 CultureInfo.DateTimeFormat 屬性返回的。當建立文化時，其預設值會與CultureInfo.Calendar屬性的值相同。不過，您可以將目前文化使用的行事曆更改為 CultureInfo.OptionalCalendars 屬性傳回的陣列中包含的任何行事曆。如果您試著將目前的行事曆設定為屬性值中未包含的 CultureInfo.OptionalCalendars 行事曆， ArgumentException 則會擲回。

下列範例會變更阿拉伯語（沙烏地阿拉伯）文化所使用的曆法。它會先具現化 DateTime 值，並使用目前的文化特性來顯示它，在此案例中為英文（美國）和目前文化特性的行事曆（在此案例中為公曆）。接下來，它會將目前的文化特性變更為阿拉伯文（沙烏地阿拉伯），並使用預設的 Um Al-Qura 行事歷來顯示日期。然後， CalendarExists 它會呼叫方法來判斷阿拉伯文（沙烏地阿拉伯）文化是否支持回歷。因為支援行事曆，所以會將目前的行事曆變更為 Hijri，然後再次顯示日期。請注意，在每個案例中，日期會使用目前文化特性的目前行事歷來顯示。

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

日期和行事曆

除了包含型 Calendar 別參數的建構函式，並允許日期的元素（也就是月、日和年）反映指定行事曆中的值， DateTime 和 DateTimeOffset 值一律以公曆為基礎。例如， DateTime.Year 這表示屬性會傳回公曆中的年份，而 DateTime.Day 屬性會傳回公曆月的日期。

這很重要

請務必記住，日期值與其字串表示之間有差異。前者以公曆為基礎：後者是以特定文化特性的目前行事歷為基礎。

下列範例說明DateTime屬性與其對應Calendar方法之間的差異。在此範例中，目前的文化特性是阿拉伯文（埃及），而目前的行事歷是 Um Al Qura。值 DateTime 會設定為 2011 年第七個月的第十五天。很明顯，這解釋為公曆日期，因為 DateTime.ToString(String, IFormatProvider) 方法在使用不變文化的慣例時會傳回相同的值。使用目前文化特性慣例格式化的日期字串表示是 14/08/32，這是 Um Al Qura 行事曆中的對等日期。接下來，DateTime 和 Calendar 的成員會用來傳回 DateTime 值的日期、月份和年份。在每個案例中，成員傳 DateTime 回的值會反映公曆中的值，而成員傳 UmAlQuraCalendar 回的值則反映 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

根據行事歷建立日期

由於 DateTime 和 DateTimeOffset 值是以公曆為基礎，因此，如果您想要使用不同行事曆中的日、月或年值，您必須呼叫包含類型的 Calendar 多載建構函式，以具現化日期值。您也可以呼叫特定行事曆方法的 Calendar.ToDateTime 其中一個多載，根據特定行事曆的值來具現化 DateTime 物件。

下列範例會藉由將對象傳遞DateTime至建構函式來具現化一個HebrewCalendar值，並藉由呼叫 DateTime 方法具現化第二DateTime個HebrewCalendar.ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32)值。由於兩個值都是以希伯來歷相同的值所建立，因此對方法的 DateTime.Equals 呼叫會顯示這兩 DateTime 個值相等。

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

顯示當前日曆的日期

將日期轉換成字串時，日期和時間格式方法一律使用目前的行事曆。這表示年份、月份和每月日期的字串表示會反映目前的行事曆，而且不一定反映公曆。

下列範例顯示目前行事曆如何影響日期的字串表示。它會將目前的文化變更為中文（傳統、臺灣），並具現化日期值。然後，它會顯示目前的行事曆和日期、將目前的行事曆變更為 TaiwanCalendar，並再次顯示目前的行事曆和日期。第一次顯示日期時，它會以公曆中的日期表示。第二次顯示時，它會以台灣日曆中的日期表示。

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

代表非目前行事曆中的日期

若要使用非當前特定文化的行事曆來表示日期，您必須呼叫該 Calendar 物件的方法。例如， Calendar.GetYear、 Calendar.GetMonth和 Calendar.GetDayOfMonth 方法會將年份、月和日轉換成反映特定行事曆的值。

警告

由於某些行事曆不屬於任何文化的選擇行事曆，因此在這些行事曆中表示日期時，您一律需要呼叫行事曆的方法。所有衍生自EastAsianLunisolarCalendar、JulianCalendar和PersianCalendar類別的行事曆都是如此。

下列範例會使用 JulianCalendar 物件在 Julian 日曆中具現化日期 1905 年 1 月 9 日。當這個日期使用預設值（公曆）顯示時，它會以 1905 年 1 月 22 日表示。對個別 JulianCalendar 方法的呼叫可讓日期顯示在 Julian 行事曆中。

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

行事曆和日期範圍

行事曆所支援的最早日期是由該行事曆的 Calendar.MinSupportedDateTime 屬性所指示。針對類別 GregorianCalendar ，該日期為 0001 年 1 月 1 日 C.E。.NET 中大部分的其他行事歷都支援較晚的日期。嘗試處理早於行事曆支援的最早日期的日期和時間值會拋出ArgumentOutOfRangeException例外狀況。

不過，有一個重要的例外狀況。對象的預設 DateTime （未初始化）值，而 DateTimeOffset 物件等於 GregorianCalendar.MinSupportedDateTime 值。如果您嘗試在不支援 0001 年 1 月 1 日 C.E. 的行事曆中格式化此日期，而且您未提供格式規範，則格式化方法會使用 “s” （可排序的日期/時間模式）格式規範，而不是 “G” （一般日期/時間模式）格式規範。因此，格式設定作業不會擲回 ArgumentOutOfRangeException 例外狀況。相反，它會返回不支持的日期。下列範例說明當目前文化特性設定為日語（日本）並使用日本行事曆，以及設定為阿拉伯語（埃及）並使用 Umm al-Qura 行事曆時，DateTime.MinValue 的值。它也會將目前的文化特性設定為英文（美國），並使用這些 DateTime.ToString(IFormatProvider) 物件呼叫 CultureInfo 方法。在每個案例中，都會使用可排序的日期/時間模式來顯示日期。

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

使用紀元

行事曆通常會將日期分割成紀元。不過， Calendar .NET 中的類別不支持日曆所定義的每個紀元，而且大部分 Calendar 的類別只支援單一紀元。 JapaneseCalendar只有和 JapaneseLunisolarCalendar 類別支援多個紀元。

這很重要

令和時代是一個JapaneseCalendar和JapaneseLunisolarCalendar的新時代，於2019年5月1日開始。這項變更會影響使用這些行事曆的所有應用程式。如需詳細資訊，請參閱下列文章：

處理 .NET 中日曆的新紀元，其中包含新增至 .NET 的功能，以支援具有多個紀元的行事曆，並討論處理多紀元行事歷時要使用的最佳做法。
為日文時代變更準備您的應用程式，其提供有關在 Windows 上測試應用程式的資訊，以確保其準備好進行時代變更。
與新日文時代相關的 .NET Framework 更新摘要，其中列出針對與新日曆時代相關的各個 Windows 版本的 .NET Framework 更新，記錄適用於支持多個年代的 .NET Framework 新功能，還包含測試應用程式時應注意的事項。

大多數日曆中的紀元代表一段極其漫長的時間週期。例如，在公曆中，目前的紀元跨越了兩千多年。在JapaneseCalendar和JapaneseLunisolarCalendar這兩個支援多個紀元的行事曆中，情況並非如此。一個時代對應於皇帝統治時期。支援多個紀元，特別是當目前時代的上限未知時，會產生特殊挑戰。

紀元和紀元名稱

在 .NET 中，代表特定行事歷實作所支持紀元的整數會以反向順序儲存在陣列中 Calendar.Eras 。目前紀元（這是具有最新時間範圍的紀元）為索引零，而對於 Calendar 支援多個紀元的類別，每個後續索引都會反映上一個紀元。靜態 Calendar.CurrentEra 屬性會定義陣列中目前紀元的 Calendar.Eras 索引;它是常數，其值一律為零。個別 Calendar 類別也包含傳回目前紀元值的靜態欄位。下表列出它們。

行事曆類別	目前紀元欄位
ChineseLunisolarCalendar	ChineseEra
GregorianCalendar	ADEra
HebrewCalendar	HebrewEra
HijriCalendar	HijriEra
JapaneseLunisolarCalendar	JapaneseEra
JulianCalendar	JulianEra
KoreanCalendar	KoreanEra
KoreanLunisolarCalendar	GregorianEra
PersianCalendar	PersianEra
ThaiBuddhistCalendar	ThaiBuddhistEra
UmAlQuraCalendar	UmAlQuraEra

將紀元編號傳遞至DateTimeFormatInfo.GetEraName或DateTimeFormatInfo.GetAbbreviatedEraName方法，即可擷取與該紀元編號對應的名稱。下列範例會呼叫這些方法，以擷取 GregorianCalendar 類別中關於紀元支援的資訊。它會顯示對應至目前時代第二年 1 月 1 日的公曆日期，以及對應至每個受支援日曆紀元第二年第二年之 1 月 1 日的公曆日期。

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

此外，「g」自訂日期和時間格式字串會在日期和時間的字串表示中包含行事曆的紀元名稱。如需詳細資訊，請參閱自訂日期和時間格式字串。

使用紀元具現化日期

針對支援多個紀元的兩 Calendar 個類別，包含特定年份、月和日值的日期可能會模棱兩可。例如，JapaneseCalendar 支援的所有紀元，其年份編號皆為1。一般而言，如果未指定紀元，日期和時間和行事歷方法都會假設值屬於目前紀元。這同樣適用於包含類型 DateTime 參數的 DateTimeOffset 和 Calendar 建構函式，以及 JapaneseCalendar.ToDateTime 和 JapaneseLunisolarCalendar.ToDateTime 方法。下列範例會建立一個日期，代表未指定紀元的第二年 1 月 1 日。如果您在 Reiwa 時代是目前紀元時執行範例，日期會解譯為 Reiwa 時代的第二年。在方法 DateTime.ToString(String, IFormatProvider) 傳回的字串中，時代名稱「令和」位於年份之前，並對應於公曆的 2020 年 1 月 1 日。（雷瓦時代始於公曆2019年。

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

不過，如果紀元變更，此程式碼的意圖就會變得模棱兩可。日期是要代表目前時代的第二年，還是代表海西時代的第二年？有兩種方式可以避免這種模棱兩可：

使用預設 GregorianCalendar 類別具現化日期和時間值。接著，您可以使用日曆或日文 Lunisolar 行事曆來表示日期的字串，如下列範例所示。

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

呼叫明確指定紀元的日期和時間方法。這包括下列方法：

ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32)或 JapaneseCalendar 類別的 JapaneseLunisolarCalendar 方法。
DateTime或 DateTimeOffset 的剖析方法，例如 Parse、TryParse、ParseExact 或 TryParseExact，這些方法包含要剖析的字串，並可選擇性地加入DateTimeStyles 自變數，若目前文化特性是 Japanese-Japan（“ja-JP”），且該文化特性的歷法為 JapaneseCalendar。要剖析的字串必須包含紀元。
DateTime或 DateTimeOffset 剖析方法，其中包含 provider 型別 IFormatProvider的參數。 provider必須是表示 Japanese-Japan（“ja-JP”）文化特性且目前行事曆為CultureInfo的JapaneseCalendar物件，或是其DateTimeFormatInfo屬性為Calendar的JapaneseCalendar物件。要剖析的字串必須包含紀元。

下列範例會使用其中三種方法，在1868年9月8日開始的Meiji時代具現化日期和時間，並在1912年7月29日結束。

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)

小提示

使用支援多個紀元的行事歷時， 請一律 使用公曆日期來具現化日期，或根據該行事歷來具現化日期和時間時指定紀元。

在指定ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) 方法的紀元時，您需要在行事曆的Eras 屬性中提供該紀元的索引。不過，對於紀元可能會變更的行事曆，這些索引不是常數值;目前的紀元位於索引 0，而最舊的紀元則位於索引 Eras.Length - 1。當新的紀元加入行事歷時，前一個紀元的索引就會增加一個。您可以提供適當的紀元索引，如下所示：

對於目前紀元中的日期，請一律使用行事曆的 CurrentEra 屬性。
對於指定紀元中的日期，請使用 DateTimeFormatInfo.GetEraName 方法來擷取對應至指定紀元名稱的索引。這需要 JapaneseCalendar 成為代表 ja-JP 文化特性之 CultureInfo 物件的目前行事曆。（這項技術也適用於 JapaneseLunisolarCalendar ，因為它支援與 JapaneseCalendar相同的時代。上述範例說明此方法。

行事曆、紀元和日期範圍：寬鬆的範圍檢查

非常類似於個別行事曆支援日期範圍，JapaneseCalendar 和 JapaneseLunisolarCalendar 類別中的紀元也支援範圍。先前，.NET 會使用嚴格的紀元範圍檢查，以確保特定紀元日期在該紀元範圍內。也就是說，如果日期超出指定紀元的範圍，該方法會拋出ArgumentOutOfRangeException。目前，.NET 預設會使用寬鬆的範圍檢查。所有 .NET 版本的更新都引入了放寬的紀元範圍檢查；如果嘗試實例化一個超出指定紀元範圍的紀元特定日期，它會被推移至下一個紀元，而不會拋出例外。

下列範例嘗試具現化 Showa 時代第 65 年的日期，該日期始於 1926 年 12 月 25 日，於 1989 年 1 月 7 日結束。此日期對應於 1990 年 1 月 9 日，該日期不在 Showa 時代的 JapaneseCalendar範圍內。如範例的輸出所說明，此範例所顯示的日期為 1990 年 1 月 9 日，在 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

如果不想要寬鬆的範圍檢查，您可以根據應用程式執行所在的 .NET 版本，以多種方式還原嚴格的範圍檢查：

.NET Core： 將下列內容新增至 .netcore.runtime.json 組態檔：

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

.NET Framework 4.6 或更新版本： 在 app.config 檔案中設定下列 AppContext 參數：

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

.NET Framework 4.5.2 或更早版本： 設定下列登入值：

	價值
金鑰	HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
入口	Switch.System.Globalization.EnforceJapaneseEraYearRanges
型別	REG_SZ
價值	是

啟用嚴格範圍檢查後，上一個範例會拋出ArgumentOutOfRangeException，並顯示下列輸出：

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()

代表具有多個紀元的行事曆中的日期

如果Calendar物件支援紀元且是CultureInfo物件的目前行事曆，則在完整日期和時間、長日期以及短日期模式的日期和時間值的字串表示中會包含紀元。下列範例會在目前的文化特性是日本（日文）且目前的行事曆是日曆時，顯示這些日期模式。

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

警告

類別 JapaneseCalendar 是 .NET 中唯一的行事曆類別，兩者都支援多個紀元中的日期，而且可以是物件的目前行事曆 CultureInfo ，特別是 CultureInfo 代表日本（日本）文化特性的物件。

對於所有行事曆，“g” 自定義格式規範會在結果字串中包含紀元。下列範例會使用「MM-dd-yyyy g」自定義格式字串，在目前的行事曆是公曆時，將紀元包含在結果字串中。

   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.

在日期的字串表示形式屬於非當前行事曆的情況下，類別 Calendar 包含 Calendar.GetEra 方法，該方法可以與 Calendar.GetYear、Calendar.GetMonth 及 Calendar.GetDayOfMonth 方法一起使用，以清楚地指明日期及其所屬的紀元。下列範例使用 JapaneseLunisolarCalendar 類別來提供示例。不過請注意，若要在結果字串中顯示有意義的名稱或縮寫來取代紀元的整數，您需要具現化一個 DateTimeFormatInfo 物件，並將 JapaneseCalendar 設定為其目前的行事曆。（JapaneseLunisolarCalendar 行事曆不能是任何文化的當前行事曆，但在此情況下，兩個行事曆共用相同的紀元。）

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

在日本日曆中，一個時代的第一年被稱為甘寧（元年）。例如，平成時代的第一年可以描述為平成元年，而不是Heisei 1。 .NET 採用這種慣例，當以下標準或自定義的日期和時間格式字串與表示 Japanese-Japan（“ja-JP”）文化的 CultureInfo 物件搭配 JapaneseCalendar 類別使用時，進行日期和時間格式化作業。

長日期模式，以「D」標準日期和時間格式字串表示。
完整日期長時間模式，以「F」標準日期和時間格式字串表示。
完整日期短時間模式，以「f」標準日期和時間格式字串表示。
年/月模式，以 “Y” 或 “y” 標準日期和時間格式字串表示。
“ggy'年'” 或 “ggy 年” 自定義日期和時間格式字串。

例如，下列範例會在JapaneseCalendar中顯示Heisei時代的第一年日期。

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)

如果格式化作業中不想要此行為，您可以根據 .NET 的版本，還原先前的行為，此行為一律代表紀元的第一年為 “1”，而不是 “Gannen” ：

.NET Core： 將下列內容新增至 .netcore.runtime.json 組態檔：

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

.NET Framework 4.6 或更新版本： 在 app.config 檔案中設定下列 AppContext 參數：

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

.NET Framework 4.5.2 或更早版本： 設定下列登入值：

	價值
金鑰	HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
入口	切換系統全球化功能將日本第一年格式化為數字
型別	REG_SZ
價值	是

在格式化作業停用 gannen 支援功能後，上一個範例會顯示以下輸出：

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

.NET 也已更新，以便日期和時間剖析作業支援包含表示為 “1” 或 Gannen 年份的字串。雖然您不應該這樣做，但您可以還原先前的行為，只將 “1” 辨識為時代的第一年。視 .NET 版本而定，您可以依照下列方式執行此動作：

.NET Core： 將下列內容新增至 .netcore.runtime.json 組態檔：

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

.NET Framework 4.6 或更新版本： 在 app.config 檔案中設定下列 AppContext 參數：

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

.NET Framework 4.5.2 或更早版本： 設定下列登入值：

	價值
金鑰	HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
入口	Switch.System.Globalization.EnforceLegacyJapaneseDateParsing
型別	REG_SZ
價值	是

共用方式為

使用行事曆

.NET 中的行事曆

行事曆與文化

日期和行事曆

根據行事歷建立日期

顯示當前日曆的日期

代表非目前行事曆中的日期

行事曆和日期範圍

使用紀元

紀元和紀元名稱

使用紀元具現化日期

行事曆、紀元和日期範圍：寬鬆的範圍檢查

代表具有多個紀元的行事曆中的日期

另請參閱

意見反應

其他資源