System


.NET Framework 類別庫
DateTime 結構

表示時間的瞬間，通常以一天的日期和時間表示。

命名空間： System
組件： mscorlib (在 mscorlib.dll 中)

語法
Visual Basic (宣告) 
<SerializableAttribute> _
Public Structure DateTime
    Implements IComparable, IFormattable, IConvertible, ISerializable, _
    IComparable(Of DateTime), IEquatable(Of DateTime)
Visual Basic (使用方式) 
Dim instance As DateTime
C# 
[SerializableAttribute] 
public struct DateTime : IComparable, IFormattable, IConvertible, 
    ISerializable, IComparable<DateTime>, IEquatable<DateTime>
C++ 
[SerializableAttribute] 
public value class DateTime : IComparable, IFormattable, IConvertible, 
    ISerializable, IComparable<DateTime>, IEquatable<DateTime>
J# 
/** @attribute SerializableAttribute() */ 
public final class DateTime extends ValueType implements IComparable, IFormattable, 
    IConvertible, ISerializable, IComparable<DateTime>, IEquatable<DateTime>
JScript 
JScript 可以支援使用結構，但不允許宣告新的結構。
備註

DateTime 實值型別使用數值來表示日期和時間，這些數值的範圍從公元 (Common Era，C.E.) 0001 年 1 月 1 日午夜 12:00:00 到公元 9999 年 12 月 31 日 11:59:59 P.M.。

時間值是以稱為刻度的 100 奈秒單位所測量，而特定的日期則是從 GregorianCalendar 曆的公元 0001 年 1 月 1 日午夜 12:00 以來的刻度數目。例如，刻度值 31241376000000000L 表示 0100 年元月 1 日，星期五，午夜 12:00:00 這個日期。DateTime 值永遠以明確或預設日曆的內容來表示。

版本考量

在 .NET Framework 2.0 版以前，DateTime 結構包含了由未使用的 2 位元欄位 (與私用 [刻度] 欄位串連) 所組成的 64 位元欄位，此欄位是一個 62 位元不帶正負號的欄位，其中包含了表示日期和時間的刻度數目。[刻度] 欄位的值可以透過 Ticks 屬性取得。

從 .NET Framework 2.0 開始，DateTime 結構包含了由私用 [類型] 欄位 (與 [刻度] 欄位串連) 所組成的 64 位元欄位。[類型] 欄位是一個 2 位元的欄位，可指出 DateTime 結構是否表示本地時間、Coordinated Universal Time (UTC)，或者是否未指定 UTC 或本地時間。[類型] 欄位是用來處理本地時間和 UTC 時間之間的轉換，但不是處理時間的比較或算術。[類型] 欄位的值可以透過 Kind 屬性取得。

DateTime 值

DateTime 型別中的時間值描述通常是使用 Coordinated Universal Time (UTC) 標準來表示，這個標準在國際上稱為格林威治標準時間 (Greenwich Mean Time，GMT)。Coordinated Universal Time 是從經度零度 (UTC 原點) 測量的時間，日光節約時間不適用於 UTC。

本地時間則相對於特定的時區，時區與時區位移有關，這是指從 UTC 原點算起的時區所測量的時數位移。此外，本地時間也有可能受到日光節約時間的影響，將一天的長度增加一個小時或縮短一個小時。因此，本地時間的計算方式是加上對 UTC 的時區位移，然後視需要根據日光節約時間做調整。在 UTC 原點的時區位移為零。

UTC 時間適用於計算、比較日期和時間，並將之儲存於檔案中；本地時間則適用於使用者介面中的顯示。

如果 DateTime 物件的 Kind 屬性為 Unspecified，則表示它未指定所表示的時間為本地時間或 UTC 時間。個別的 DateTime 成員會適當地根據該成員來處理未指定的時間。

DateTime 運算

使用 DateTime 結構進行的計算 (例如 Add 或 Subtract) 並不會修改該結構的值。該計算反而會傳回新的 DateTime 結構，此結構的值即為計算的結果。

本地時間和 UTC 時間之間的轉換作業會將日光節約時間列入考量，但是算術和比較作業則不會。

DateTime 物件的計算和比較只有在這些物件表示相同時區的時間時才有意義。因此，如果未針對物件指定任何時區，則會假設開發人員擁有一些外部機制，例如可用來判斷 DateTime 物件建立所在的時區之明確變數或原則。

每一個 DateTime 成員會以隱含方式使用西曆來執行其作業，但以下除外：用以指定日曆的建構函式，以及具有衍生自 IFormatProvider 的參數之方法 (例如 System.Globalization.DateTimeFormatInfo)，這些方法可以隱含方式指定日曆。

根據 DateTime 型別的成員所進行的作業會考量類似閏年和每月天數等細節。

DateTime 與 TimeSpan 的比較

DateTime 和 TimeSpan 實值型別的差別在於 DateTime 表示時間的一瞬間，而 TimeSpan 則表示時間間隔。例如，這表示您可以將 DateTime 的另一個執行個體 (Instance) 減去某一個執行個體來取得它們之間的時間間隔。或者您可以將正的 TimeSpan 加上目前的 DateTime 來計算未來的日期。

您可以從 DateTime 物件中加入或減去時間間隔。時間間隔可以是正數或負數、可以用類似刻度或秒數的單位來表示，也可以表示為 TimeSpan 物件。

COM Interop 考量

傳輸給 COM 應用程式，然後再傳回 Managed 應用程式的 DateTime 值，這樣稱為往返作業。但是，只有指定一個時間的 DateTime 值，可能不會如您預期般地進行往返作業。

如果往返作業只有指定一個時間 (假設是 3 P.M.)，則最終的日期和時間會是公元 1899 年 12 月 30 日 3:00 P.M.，而不是公元 0001 年 1 月 1 日 3:00 P.M，這是因為 .NET Framework 和 COM 在只有指定一個時間時，會假設使用預設日期。但是，COM 系統會假設使用公元 1899 年 12 月 30 日當做基準日期，而 .NET Framework 則假設使用公元 0001 年 1 月 1 日當做基準日期。

當只有將一個時間從 .NET Framework 傳遞到 COM 時，會執行特殊的處理，將時間轉換成 COM 使用的格式。當只有將一個時間從 COM 傳遞到 .NET Framework 時，不會執行特殊的處理，因為這樣將會損壞 1899 年 12 月 30 日以前 (含) 的有效日期和時間；這也表示，如果某個日期從 COM 開始進行往返作業，則 .NET Framework 和 COM 都會保留該日期。

.NET Framework 和 COM 的行為表示，如果應用程式針對只有指定一個時間的 DateTime 進行往返作業，則應用程式一定要修改或忽略從最終 DateTime 物件傳回的錯誤日期。

已實作的介面

這個型別會實作 IComparable、IComparable、IFormattable 和 IConvertible 等介面。使用 Convert 類別來進行轉換，以替代這個型別的明確介面成員的 IConvertible 實作。
範例

下列程式碼範例將示範如何比較近似的 DateTime 值，在宣告它們相等時接受小的差異值。

Visual Basic 
Class DateTimeTester
   
   Shared Function RoughlyEquals(time As DateTime, timeWithWindow As DateTime, windowInSeconds As Integer, frequencyInSeconds As Integer) As Boolean
      
      Dim delta As Long = (timeWithWindow.Subtract(time)).TotalSeconds Mod frequencyInSeconds
      
      If delta > windowInSeconds Then 
    delta = frequencyInSeconds - delta 
      End If
   
      
      Return Math.Abs(delta) < windowInSeconds

   End Function 'RoughlyEquals
    
   
   Public Shared Sub Main()

      Dim window As Integer = 10
      Dim freq As Integer = 60 * 60 * 2 ' 2 hours;
      Dim d1 As DateTime = DateTime.Now
      
      Dim d2 As DateTime = d1.AddSeconds((2 * window))
      Dim d3 As DateTime = d1.AddSeconds((- 2 * window))
      Dim d4 As DateTime = d1.AddSeconds((window / 2))
      Dim d5 As DateTime = d1.AddSeconds((- window / 2))
      
      Dim d6 As DateTime = d1.AddHours(2).AddSeconds((2 * window))
      Dim d7 As DateTime = d1.AddHours(2).AddSeconds((- 2 * window))
      Dim d8 As DateTime = d1.AddHours(2).AddSeconds((window / 2))
      Dim d9 As DateTime = d1.AddHours(2).AddSeconds((- window / 2))
      
      Console.WriteLine("d1 ~= d1 [true]: " + CStr(RoughlyEquals(d1, d1, window, freq)))
      Console.WriteLine("d1 ~= d2 [false]: " + CStr(RoughlyEquals(d1, d2, window, freq)))
      Console.WriteLine("d1 ~= d3 [false]: " + CStr(RoughlyEquals(d1, d3, window, freq)))
      Console.WriteLine("d1 ~= d4 [true]: " + CStr(RoughlyEquals(d1, d4, window, freq)))
      Console.WriteLine("d1 ~= d5 [true]: " + CStr(RoughlyEquals(d1, d5, window, freq)))
      
      Console.WriteLine("d1 ~= d6 [false]: " + CStr(RoughlyEquals(d1, d6, window, freq)))
      Console.WriteLine("d1 ~= d7 [false]: " + CStr(RoughlyEquals(d1, d7, window, freq)))
      Console.WriteLine("d1 ~= d8 [true]: " + CStr(RoughlyEquals(d1, d8, window, freq)))
      Console.WriteLine("d1 ~= d9 [true]: " + CStr(RoughlyEquals(d1, d9, window, freq)))

   End Sub 'Main 

End Class 'DateTimeTester
C# 
class DateTimeTester {

    static bool RoughlyEquals(DateTime time, DateTime timeWithWindow, int windowInSeconds, int frequencyInSeconds)
    {

            long delta = (long)((TimeSpan)(timeWithWindow - time)).TotalSeconds % frequencyInSeconds;

            delta = delta > windowInSeconds ? frequencyInSeconds - delta : delta;

            return Math.Abs(delta) < windowInSeconds;

    }

    public static void Main() 
    {
            int window = 10;
            int freq = 60 * 60 * 2; // 2 hours;

            DateTime d1 = DateTime.Now;

            DateTime d2 = d1.AddSeconds(2 * window);
            DateTime d3 = d1.AddSeconds(-2 * window);
            DateTime d4 = d1.AddSeconds(window / 2);
            DateTime d5 = d1.AddSeconds(-window / 2);

            DateTime d6 = (d1.AddHours(2)).AddSeconds(2 * window);
            DateTime d7 = (d1.AddHours(2)).AddSeconds(-2 * window);
            DateTime d8 = (d1.AddHours(2)).AddSeconds(window / 2);
            DateTime d9 = (d1.AddHours(2)).AddSeconds(-window / 2);

            Console.WriteLine("d1 ~= d1 [true]: " + RoughlyEquals(d1, d1, window, freq));
            Console.WriteLine("d1 ~= d2 [false]: " + RoughlyEquals(d1, d2, window, freq));
            Console.WriteLine("d1 ~= d3 [false]: " + RoughlyEquals(d1, d3, window, freq));
            Console.WriteLine("d1 ~= d4 [true]: " + RoughlyEquals(d1, d4, window, freq));
            Console.WriteLine("d1 ~= d5 [true]: " + RoughlyEquals(d1, d5, window, freq));

            Console.WriteLine("d1 ~= d6 [false]: " + RoughlyEquals(d1, d6, window, freq));
            Console.WriteLine("d1 ~= d7 [false]: " + RoughlyEquals(d1, d7, window, freq));
            Console.WriteLine("d1 ~= d8 [true]: " + RoughlyEquals(d1, d8, window, freq));
            Console.WriteLine("d1 ~= d9 [true]: " + RoughlyEquals(d1, d9, window, freq));


    }
}
C++ 
bool RoughlyEquals( DateTime time, DateTime timeWithWindow, int windowInSeconds, int frequencyInSeconds )
{
   long delta = (long)((TimeSpan)(timeWithWindow - time)).TotalSeconds % frequencyInSeconds;
   delta = delta > windowInSeconds ? frequencyInSeconds - delta : delta;
   return Math::Abs( delta ) < windowInSeconds;
}

int main()
{
   int window = 10;
   int freq = 60 * 60 * 2; // 2 hours;

   DateTime d1 = DateTime::Now;
   DateTime d2 = d1.AddSeconds( 2 * window );
   DateTime d3 = d1.AddSeconds(  -2 * window );
   DateTime d4 = d1.AddSeconds( window / 2 );
   DateTime d5 = d1.AddSeconds(  -window / 2 );
   DateTime d6 = (d1.AddHours( 2 )).AddSeconds( 2 * window );
   DateTime d7 = (d1.AddHours( 2 )).AddSeconds(  -2 * window );
   DateTime d8 = (d1.AddHours( 2 )).AddSeconds( window / 2 );
   DateTime d9 = (d1.AddHours( 2 )).AddSeconds(  -window / 2 );
   Console::WriteLine( "d1 ~= d1 [true]: {0}", RoughlyEquals( d1, d1, window, freq ) );
   Console::WriteLine( "d1 ~= d2 [false]: {0}", RoughlyEquals( d1, d2, window, freq ) );
   Console::WriteLine( "d1 ~= d3 [false]: {0}", RoughlyEquals( d1, d3, window, freq ) );
   Console::WriteLine( "d1 ~= d4 [true]: {0}", RoughlyEquals( d1, d4, window, freq ) );
   Console::WriteLine( "d1 ~= d5 [true]: {0}", RoughlyEquals( d1, d5, window, freq ) );
   Console::WriteLine( "d1 ~= d6 [false]: {0}", RoughlyEquals( d1, d6, window, freq ) );
   Console::WriteLine( "d1 ~= d7 [false]: {0}", RoughlyEquals( d1, d7, window, freq ) );
   Console::WriteLine( "d1 ~= d8 [true]: {0}", RoughlyEquals( d1, d8, window, freq ) );
   Console::WriteLine( "d1 ~= d9 [true]: {0}", RoughlyEquals( d1, d9, window, freq ) );
}
J# 
class DateTimeTester
{
    public static boolean RoughlyEquals(DateTime time, 
        DateTime timeWithWindow, int windowInSeconds, int frequencyInSeconds)
    {
        long delta = (long)((TimeSpan)timeWithWindow.Subtract(time)).
            get_TotalSeconds() % frequencyInSeconds;
        delta = delta > windowInSeconds ? frequencyInSeconds - delta : delta;
        return (System.Convert.ToBoolean(System.Math.Abs(delta) 
            < windowInSeconds));
    } //RoughlyEquals

    public static void main(String[] args)
    {
        int window = 10;
        int freq = 60 * 60 * 2; // 2 hours;
        DateTime d1 = DateTime.get_Now();
        DateTime d2 = d1.AddSeconds(2 * window);
        DateTime d3 = d1.AddSeconds(-2 * window);
        DateTime d4 = d1.AddSeconds(window / 2);
        DateTime d5 = d1.AddSeconds(-window / 2);

        DateTime d6 = d1.AddHours(2).AddSeconds(2 * window);
        DateTime d7 = d1.AddHours(2).AddSeconds(-2 * window);
        DateTime d8 = d1.AddHours(2).AddSeconds(window / 2);
        DateTime d9 = d1.AddHours(2).AddSeconds(-window / 2);

        Console.WriteLine("d1 ~= d1 [true]: " 
            + RoughlyEquals(d1, d1, window, freq));
        Console.WriteLine("d1 ~= d2 [false]: " 
            + RoughlyEquals(d1, d2, window, freq));
        Console.WriteLine("d1 ~= d3 [false]: " 
            + RoughlyEquals(d1, d3, window, freq));
        Console.WriteLine("d1 ~= d4 [true]: " 
            + RoughlyEquals(d1, d4, window, freq));
        Console.WriteLine("d1 ~= d5 [true]: " 
            + RoughlyEquals(d1, d5, window, freq));
        Console.WriteLine("d1 ~= d6 [false]: " 
            + RoughlyEquals(d1, d6, window, freq));
        Console.WriteLine("d1 ~= d7 [false]: " 
            + RoughlyEquals(d1, d7, window, freq));
        Console.WriteLine("d1 ~= d8 [true]: " 
            + RoughlyEquals(d1, d8, window, freq));
        Console.WriteLine("d1 ~= d9 [true]: " 
            + RoughlyEquals(d1, d9, window, freq));
    } //main 
} //DateTimeTester
執行緒安全
這個型別的所有公用靜態成員 (即 Visual Basic 中的 Shared 成員) 都是安全執行緒。並非所有的執行個體成員均為安全執行緒。
平台

Windows 98、 Windows 2000 SP4、 Windows CE、 Windows Millennium Edition、 Windows Mobile for Pocket PC、 Windows Mobile for Smartphone、 Windows Server 2003、 Windows XP Media Center Edition、 Windows XP Professional x64 Edition、 Windows XP SP2、 Windows XP Starter Edition

.NET Framework 並不支援各種平台的所有版本。如需支援平台版本的相關資訊，請參閱系統需求一節的內容。
版本資訊

.NET Framework

支援版本：2.0、1.1、1.0

.NET Compact Framework

支援版本：2.0、1.0
請參閱
標記 :


Page view tracker