[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Represents an instant in time, typically expressed as a date and time of day.
Assembly: mscorlib (in mscorlib.dll)
Thetype exposes the following members.
|DateTime(Int64)||Initializes a new instance of the structure to a specified number of ticks.|
|DateTime(Int64, DateTimeKind)||Initializes a new instance of the structure to a specified number of ticks and to Coordinated Universal Time (UTC) or local time.|
|DateTime(Int32, Int32, Int32)||Initializes a new instance of the structure to the specified year, month, and day.|
|DateTime(Int32, Int32, Int32, Int32, Int32, Int32)||Initializes a new instance of the structure to the specified year, month, day, hour, minute, and second.|
|DateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32)||Initializes a new instance of the structure to the specified year, month, day, hour, minute, second, and millisecond.|
|Date||Gets the date component of this instance.|
|Day||Gets the day of the month represented by this instance.|
|DayOfWeek||Gets the day of the week represented by this instance.|
|DayOfYear||Gets the day of the year represented by this instance.|
|Hour||Gets the hour component of the date represented by this instance.|
|Kind||Gets a value that indicates whether the time represented by this instance is based on local time, Coordinated Universal Time (UTC), or neither.|
|Millisecond||Gets the milliseconds component of the date represented by this instance.|
|Minute||Gets the minute component of the date represented by this instance.|
|Month||Gets the month component of the date represented by this instance.|
|Now||Gets a object that is set to the current date and time on this computer, expressed as the local time.|
|Second||Gets the seconds component of the date represented by this instance.|
|Ticks||Gets the number of ticks that represent the date and time of this instance.|
|TimeOfDay||Gets the time of day for this instance.|
|Today||Gets the current date.|
|UtcNow||Gets a object that is set to the current date and time on this computer, expressed as the Coordinated Universal Time (UTC).|
|Year||Gets the year component of the date represented by this instance.|
|Add||Returns a new that adds the value of the specified TimeSpan to the value of this instance.|
|AddDays||Returns a new that adds the specified number of days to the value of this instance.|
|AddHours||Returns a new that adds the specified number of hours to the value of this instance.|
|AddMilliseconds||Returns a new that adds the specified number of milliseconds to the value of this instance.|
|AddMinutes||Returns a new that adds the specified number of minutes to the value of this instance.|
|AddSeconds||Returns a new that adds the specified number of seconds to the value of this instance.|
|AddTicks||Returns a new that adds the specified number of ticks to the value of this instance.|
|Compare||Compares two instances of and returns an integer that indicates whether the first instance is earlier than, the same as, or later than the second instance.|
|CompareTo||Compares the value of this instance to a specified object that contains a specified value, and returns an integer that indicates whether this instance is earlier than, the same as, or later than the specified value.|
|DaysInMonth||Returns the number of days in the specified month and year.|
|Equals(Object)||Returns a value indicating whether this instance is equal to a specified object. (Overrides ValueType..::..Equals(Object).)|
|Equals(DateTime, DateTime)||Returns a value indicating whether two instances have the same date and time value.|
|GetHashCode||Serves as a hash function for a particular type. (Inherited from Object.)|
|GetType||Gets the Type of the current instance. (Inherited from Object.)|
|SpecifyKind||Creates a new object that has the same number of ticks as the specified , but is designated as either local time, Coordinated Universal Time (UTC), or neither, as indicated by the specified DateTimeKind value.|
|Subtract(DateTime)||Subtracts the specified date and time from this instance.|
|Subtract(TimeSpan)||Subtracts the specified duration from this instance.|
|ToLocalTime||Converts the value of the current object to local time.|
|ToString()()()()||Converts the value of the current object to its equivalent string representation. (Overrides Object..::..ToString()()()().)|
|ToString(String)||Converts the value of the current object to its equivalent string representation using the specified format.|
|ToUniversalTime||Converts the value of the current object to Coordinated Universal Time (UTC).|
|Addition||Adds a specified time interval to a specified date and time, yielding a new date and time.|
|Equality||Determines whether two specified instances of are equal.|
|GreaterThan||Determines whether one specified is greater than another specified .|
|GreaterThanOrEqual||Determines whether one specified is greater than or equal to another specified .|
|Inequality||Determines whether two specified instances of are not equal.|
|LessThan||Determines whether one specified is less than another specified .|
|LessThanOrEqual||Determines whether one specified is less than or equal to another specified .|
|Subtraction(DateTime, DateTime)||Subtracts a specified date and time from another specified date and time and returns a time interval.|
|Subtraction(DateTime, TimeSpan)||Subtracts a specified time interval from a specified date and time and returns a new date and time.|
The value type represents dates and times with values ranging from 00:00:00.0, January 1, 1601 Anno Domini, or A.D. (also known as Common Era, or C.E.) through 11:59:59 P.M., December 31, 9999 A.D. (C.E.) These limits are stored as read-only values in the MinValue and MaxValue fields.
Time values are measured in 100-nanosecond units called ticks, and a particular date is expressed as the number of ticks that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) in the Gregorian calendar. For example, a tick value of 31241376000000000L represents Friday, January 01, 0100 12:00:00 midnight.
Descriptions of time values in the type are often expressed using the Coordinated Universal Time (UTC) standard, which is the internationally recognized name for Greenwich Mean Time (GMT). Coordinated Universal Time is the time as measured at zero degrees longitude, the UTC origin point. Daylight saving time is not applicable to UTC.
Local time is relative to a particular time zone. A time zone is associated with a time zone offset, which is the displacement of the time zone measured in hours from the UTC origin point. In addition, local time is optionally affected by daylight saving time, which adds or subtracts an hour from the length of a day. Consequently, local time is calculated by adding the time zone offset to UTC and adjusting for daylight saving time if necessary. The time zone offset at the UTC origin point is zero.
UTC time is suitable for calculations, comparisons, and storing dates and time in files. Local time is appropriate for display in user interfaces of desktop applications. Time zone-aware applications (such as many Web applications) also need to work with a number of other time zones.
If the Kind property of a object is , it is unspecified whether the time represented is local time, UTC time, or a time in some other time zone.
Conversion operations between time zones (such as between UTC and local time, or between one time zone and another) take daylight saving time into account, but arithmetic and comparison operations do not.
Calculations and comparisons of objects are meaningful only if the objects represent times in the same time zone. You can use a object to represent a value's time zone, although the two are loosely coupled. (That is, a object does not have a property that returns an object that represents that date and time value's time zone other than the Kind property.) For this reason, in a time zone-aware application, you must rely on some external mechanism to determine the time zone in which a object was created. For example, you could use a structure that wraps both the value and the object that represents the value's time zone. For details on using UTC in calculations and comparisons with values, see Performing Arithmetic Operations with Dates and Times.
DateTime vs. TimeSpan
The and TimeSpan value types differ in that a represents an instant in time whereas a TimeSpan represents a time interval. This means, for example, that you can subtract one instance of from another to obtain a TimeSpan object that represents the time interval between them. Or you could add a positive TimeSpan to the current to obtain a value that represents a future date.
You can add or subtract a time interval from a object. Time intervals can be negative or positive, can be expressed in units such as ticks or seconds, or can be expressed as a TimeSpan object.
COM Interop Considerations
A value that is transferred to a COM application, then is transferred back to a managed application, is said to round-trip. However, a value that specifies only a time does not round-trip as you might expect.
If you round-trip only a time, such as 3 P.M., the final date and time is December 30, 1899 C.E. at 3:00 P.M., instead of January, 1, 0001 C.E. at 3:00 P.M. This happens because the .NET Framework and COM assume a default date when only a time is specified. However, the COM system assumes a base date of December 30, 1899 C.E. while the .NET Framework assumes a base date of January, 1, 0001 C.E.
When only a time is passed from the .NET Framework to COM, special processing is performed that converts the time to the format used by COM. When only a time is passed from COM to the .NET Framework, no special processing is performed because that would corrupt legitimate dates and times on or before December 30, 1899. This also means if a date starts its round-trip from COM, the .NET Framework and COM preserve the date.
The behavior of the .NET Framework and COM means that if your application round-trips a that only specifies a time, your application must remember to modify or ignore the erroneous date from the final object.