DateTimeOffset.ToString 方法

定义

命名空间:

System

程序集:

System.Runtime.dll

将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。

重载

ToString()	将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。
ToString(IFormatProvider)	使用指定的区域性特定的格式设置信息将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。
ToString(String)	使用指定格式将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。
ToString(String, IFormatProvider)	使用指定的格式和区域性特定的格式信息将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。

ToString()

Source:

DateTimeOffset.cs

将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。

C#

public override string ToString ();

返回

String

包含字符串末尾追加的偏移量的 DateTimeOffset 对象的字符串表示形式。

例外

ArgumentOutOfRangeException

日期和时间超出了当前区域性使用的日历支持的日期范围。

示例

下面的示例演示了对 ToString() 方法的调用，并在当前区域性 en-us的系统上显示其输出。

C#

DateTimeOffset thisDate;

// Show output for UTC time
thisDate = DateTimeOffset.UtcNow;
Console.WriteLine(thisDate.ToString());  // Displays 3/28/2007 7:13:50 PM +00:00

// Show output for local time
thisDate = DateTimeOffset.Now;
Console.WriteLine(thisDate.ToString());  // Displays 3/28/2007 12:13:50 PM -07:00

// Show output for arbitrary time offset
thisDate = thisDate.ToOffset(new TimeSpan(-5, 0, 0));
Console.WriteLine(thisDate.ToString());  // Displays 3/28/2007 2:13:50 PM -05:00

注解

此方法的返回值与 DateTime.ToString() 方法的返回值相同，只不过它包含后跟字符串末尾追加的偏移量的空间。 换句话说，它使用短日期模式、长时间模式和 zzz 自定义格式字符串设置输出的格式，每个元素都用空格分隔与上一个元素。 例如，如果 DateTime.ToString() 返回 2008 年 1 月 12 日 6：15：50 PM 的值，ToString() 返回 2008 年 1 月 12 日 6：15：50 -08：00 的值，该值落后协调世界时（UTC）。

此方法使用派生自当前区域性的格式设置信息。 有关详细信息，请参阅 CurrentCulture。 使用 ToString 方法的其他重载可以指定要使用的格式区域性，并定义 DateTimeOffset 值的输出模式。

调用方说明

ToString() 方法返回当前区域性使用的日历中的日期和时间的字符串表示形式。 如果当前 DateTimeOffset 实例的值早于 MinSupportedDateTime 或晚于 MaxSupportedDateTime，该方法将引发 ArgumentOutOfRangeException。 以下示例提供了一个插图。 当当前区域性为阿拉伯语（叙利亚）时，它尝试设置 HijriCalendar 类范围之外的日期的格式。

C#

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

public class Example
{
   public static void Main()
   {
      DateTimeOffset date1 = new DateTimeOffset(new DateTime(550, 1, 1),
                                                TimeSpan.Zero);
      CultureInfo dft;
      CultureInfo arSY = new CultureInfo("ar-SY");
      arSY.DateTimeFormat.Calendar = new HijriCalendar();

      // Change current culture to ar-SY.
      dft = Thread.CurrentThread.CurrentCulture;
      Thread.CurrentThread.CurrentCulture = arSY;

      // Display the date using the current culture's calendar.
      try {
         Console.WriteLine(date1.ToString());
      }
      catch (ArgumentOutOfRangeException) {
         Console.WriteLine("{0} is earlier than {1} or later than {2}",
                           date1.ToString("d", CultureInfo.InvariantCulture),
                           arSY.DateTimeFormat.Calendar.MinSupportedDateTime.ToString("d", CultureInfo.InvariantCulture),
                           arSY.DateTimeFormat.Calendar.MaxSupportedDateTime.ToString("d", CultureInfo.InvariantCulture));
      }

      // Restore the default culture.
      Thread.CurrentThread.CurrentCulture = dft;
   }
}
// The example displays the following output:
//    01/01/0550 is earlier than 07/18/0622 or later than 12/31/9999

ToString(IFormatProvider)

Source:

DateTimeOffset.cs

使用指定的区域性特定的格式设置信息将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。

C#

public string ToString (IFormatProvider? formatProvider);

参数

formatProvider

IFormatProvider

提供区域性特定的格式设置信息的对象。

返回

String

由 formatProvider指定的当前 DateTimeOffset 对象的值的字符串表示形式。

例外

ArgumentOutOfRangeException

日期和时间超出了 formatProvider使用的日历所支持的日期范围。

示例

以下示例使用表示固定区域性的 CultureInfo 对象以及其他四种区域性显示 DateTimeOffset 对象。

C#

CultureInfo[] cultures = new CultureInfo[] {CultureInfo.InvariantCulture,
                                           new CultureInfo("en-us"),
                                           new CultureInfo("fr-fr"),
                                           new CultureInfo("de-DE"),
                                           new CultureInfo("es-ES")};

DateTimeOffset thisDate = new DateTimeOffset(2007, 5, 1, 9, 0, 0,
                                             TimeSpan.Zero);

foreach (CultureInfo culture in cultures)
{
   string cultureName;
   if (string.IsNullOrEmpty(culture.Name))
      cultureName = culture.NativeName;
   else
      cultureName = culture.Name;

   Console.WriteLine("In {0}, {1}",
                     cultureName, thisDate.ToString(culture));
}
// The example produces the following output:
//    In Invariant Language (Invariant Country), 05/01/2007 09:00:00 +00:00
//    In en-US, 5/1/2007 9:00:00 AM +00:00
//    In fr-FR, 01/05/2007 09:00:00 +00:00
//    In de-DE, 01.05.2007 09:00:00 +00:00
//    In es-ES, 01/05/2007 9:00:00 +00:00

注解

此方法的返回值与其等效的 DateTime.ToString 方法重载的返回值相同，只不过它包含后跟字符串末尾追加的偏移量的空间。 换句话说，它使用短日期模式、长时间模式和 zzz 自定义格式字符串设置输出的格式，每个元素都用空格分隔与上一个元素。

这三个元素的格式由 formatProvider 参数定义。 formatProvider 参数可以是以下任一参数：

• 一个 CultureInfo 对象，该对象表示其格式设置约定应用于返回的字符串的区域性。 CultureInfo.DateTimeFormat 属性返回的 DateTimeFormatInfo 对象定义返回字符串的格式。

• 定义日期和时间数据格式的 DateTimeFormatInfo 对象。

如果 formatProvidernull，则使用与当前区域性关联的 DateTimeFormatInfo 对象（请参阅 CurrentCulture）。

调用方说明

ToString(IFormatProvider) 方法返回由 formatProvider 参数表示的区域性使用的日历中的日期和时间的字符串表示形式。 其日历由 Calendar 属性定义。 如果当前 DateTimeOffset 实例的值早于 MinSupportedDateTime 或晚于 MaxSupportedDateTime，该方法将引发 ArgumentOutOfRangeException。 以下示例提供了一个插图。 它尝试设置 JapaneseCalendar 类范围之外的日期的格式。

C#

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      CultureInfo jaJP = new CultureInfo("ja-JP");
      jaJP.DateTimeFormat.Calendar = new JapaneseCalendar();
      DateTimeOffset date1 = new DateTimeOffset(new DateTime(1867, 1, 1),
                                                TimeSpan.Zero);

      try {
         Console.WriteLine(date1.ToString(jaJP));
      }
      catch (ArgumentOutOfRangeException) {
         Console.WriteLine("{0:d} is earlier than {1:d} or later than {2:d}",
                           date1,
                           jaJP.DateTimeFormat.Calendar.MinSupportedDateTime,
                           jaJP.DateTimeFormat.Calendar.MaxSupportedDateTime);
      }
   }
}
// The example displays the following output:
//    1/1/1867 is earlier than 9/8/1868 or later than 12/31/9999

ToString(String)

Source:

DateTimeOffset.cs

使用指定格式将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。

C#

public string ToString (string? format);

参数

format

String

格式字符串。

返回

String

由 format指定的当前 DateTimeOffset 对象的值的字符串表示形式。

例外

FormatException

format 的长度是一个，它不是为 DateTimeFormatInfo定义的标准格式说明符字符之一。

-或-

format 不包含有效的自定义格式模式。

ArgumentOutOfRangeException

日期和时间超出了当前区域性使用的日历支持的日期范围。

示例

以下示例使用每个标准日期和时间格式说明符向控制台显示一个 DateTimeOffset 对象。 使用 en-us 区域性设置输出的格式。

C#

DateTimeOffset outputDate = new DateTimeOffset(2007, 10, 31, 21, 0, 0,
                                     new TimeSpan(-8, 0, 0));
string specifier;

// Output date using each standard date/time format specifier
specifier = "d";
// Displays   d: 10/31/2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "D";
// Displays   D: Wednesday, October 31, 2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "t";
// Displays   t: 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "T";
// Displays   T: 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "f";
// Displays   f: Wednesday, October 31, 2007 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "F";
// Displays   F: Wednesday, October 31, 2007 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "g";
// Displays   g: 10/31/2007 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "G";
// Displays   G: 10/31/2007 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "M";           // 'm' is identical
// Displays   M: October 31
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "R";           // 'r' is identical
// Displays   R: Thu, 01 Nov 2007 05:00:00 GMT
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "s";
// Displays   s: 2007-10-31T21:00:00
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

specifier = "u";
// Displays   u: 2007-11-01 05:00:00Z
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

// Specifier is not supported
specifier = "U";
try
{
   Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
}
catch (FormatException)
{
   Console.WriteLine("{0}: Not supported.", specifier);
}

specifier = "Y";         // 'y' is identical
// Displays   Y: October, 2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));

注解

format 参数应包含单个格式说明符（请参阅 标准日期和时间格式字符串）或自定义格式模式（请参阅 自定义日期和时间格式字符串），用于定义返回字符串的格式。 如果 format 为 null 或空字符串（“），则使用默认格式输出 DateTimeOffset 值。

下表显示了与 DateTimeOffset一起使用时特定格式说明符的确切操作，这与与 DateTime一起使用时的行为不同。

现有格式说明符	新行为
“K”	设计为往返日期和时间。 使用 DateTimeOffset，映射到“zzz”（偏移量始终以小时和分钟为单位显示）。 请注意，“K”是自定义格式说明符;它不能显示为 format中的单个字符。
“U”	不支持。
“r”	将 DateTimeOffset 对象转换为协调世界时（UTC），并使用自定义格式字符串 ddd, dd MMM yyyy HH:mm:ss GMT输出它。
“u”	将 DateTimeOffset 对象转换为 UTC，并使用格式 yyyy-MM-dd HH:mm:ssZ输出它。

其余标准日期和时间格式说明符的行为方式与 ToString(String) 方法的行为方式相同，与 ToString 方法相同。

此方法使用派生自当前区域性的格式设置信息。 有关详细信息，请参阅 CurrentCulture。

调用方说明

ToString(String) 方法返回当前区域性使用的日历中的日期和时间的字符串表示形式。 如果当前 DateTimeOffset 实例的值早于 MinSupportedDateTime 或晚于 MaxSupportedDateTime，该方法将引发 ArgumentOutOfRangeException。 以下示例提供了一个插图。 当当前文化为希伯来语（以色列）时，它尝试设置 HebrewCalendar 类范围之外日期的格式。

C#

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

public class Example
{
   public static void Main()
   {
      DateTimeOffset date1 = new DateTimeOffset(new DateTime(1550, 7, 21),
                                                TimeSpan.Zero);
      CultureInfo dft;
      CultureInfo heIL = new CultureInfo("he-IL");
      heIL.DateTimeFormat.Calendar = new HebrewCalendar();

      // Change current culture to he-IL.
      dft = Thread.CurrentThread.CurrentCulture;
      Thread.CurrentThread.CurrentCulture = heIL;

      // Display the date using the current culture's calendar.
      try {
         Console.WriteLine(date1.ToString("G"));
      }
      catch (ArgumentOutOfRangeException) {
         Console.WriteLine("{0} is earlier than {1} or later than {2}",
                           date1.ToString("d", CultureInfo.InvariantCulture),
                           heIL.DateTimeFormat.Calendar.MinSupportedDateTime.ToString("d", CultureInfo.InvariantCulture),
                           heIL.DateTimeFormat.Calendar.MaxSupportedDateTime.ToString("d", CultureInfo.InvariantCulture));
      }

      // Restore the default culture.
      Thread.CurrentThread.CurrentCulture = dft;
   }
}
// The example displays the following output:
//    07/21/1550 is earlier than 01/01/1583 or later than 09/29/2239

另请参阅

• 标准日期和时间格式字符串
• 自定义日期和时间格式字符串

ToString(String, IFormatProvider)

Source:

DateTimeOffset.cs

使用指定的格式和区域性特定的格式信息将当前 DateTimeOffset 对象的值转换为其等效的字符串表示形式。

C#

public string ToString (string? format, IFormatProvider? formatProvider);

参数

format

String

格式字符串。

formatProvider

IFormatProvider

提供区域性特定的格式设置信息的对象。

返回

String

由 format 和 formatProvider指定的当前 DateTimeOffset 对象的值的字符串表示形式。

实现

ToString(String, IFormatProvider)

例外

FormatException

format 的长度是一个，它不是为 DateTimeFormatInfo定义的标准格式说明符字符之一。

-或-

format 不包含有效的自定义格式模式。

ArgumentOutOfRangeException

日期和时间超出了 formatProvider使用的日历所支持的日期范围。

示例

以下示例使用 ToString(String, IFormatProvider) 方法，使用多个不同区域性的自定义格式字符串显示 DateTimeOffset 对象。

C#

DateTimeOffset outputDate = new DateTimeOffset(2007, 11, 1, 9, 0, 0,
                                     new TimeSpan(-7, 0, 0));
string format = "dddd, MMM dd yyyy HH:mm:ss zzz";

// Output date and time using custom format specification
Console.WriteLine(outputDate.ToString(format, null as DateTimeFormatInfo));
Console.WriteLine(outputDate.ToString(format, CultureInfo.InvariantCulture));
Console.WriteLine(outputDate.ToString(format,
                                      new CultureInfo("fr-FR")));
Console.WriteLine(outputDate.ToString(format,
                                      new CultureInfo("es-ES")));
// The example displays the following output to the console:
//    Thursday, Nov 01 2007 09:00:00 -07:00
//    Thursday, Nov 01 2007 09:00:00 -07:00
//    jeudi, nov. 01 2007 09:00:00 -07:00
//    jueves, nov 01 2007 09:00:00 -07:00

注解

format 参数应包含单个格式说明符（请参阅 标准日期和时间格式字符串）或自定义格式模式（请参阅 自定义日期和时间格式字符串）。 如果 format 为 null 或空字符串（“），则 DateTimeOffset 对象使用默认格式输出。

下表显示了与 DateTimeOffset一起使用时特定格式说明符的确切操作，这与与 DateTime一起使用时的行为不同。

现有格式说明符	新行为
“K”	设计为往返日期和时间。 使用 DateTimeOffset，映射到“zzz”（偏移量始终以小时和分钟为单位显示）。 请注意，“K”是自定义格式说明符;它不能显示为 format中的单个字符。
“U”	不支持。
“r”	将 DateTimeOffset 对象转换为协调世界时（UTC），并使用自定义格式字符串 ddd, dd MMM yyyy HH:mm:ss GMT输出它。
“u”	将 DateTimeOffset 值转换为 UTC，并使用格式 yyyy-MM-dd HH:mm:ssZ输出它。

其余标准日期和时间格式说明符的行为方式与 ToString(String) 方法的行为方式相同，与 ToString 方法相同。

对应于标准格式说明符以及日期和时间组件的符号和名称的模式由 formatProvider 参数定义。 formatProvider 参数可以是以下任一参数：

• 一个 CultureInfo 对象，该对象表示 input中使用的格式设置的区域性。 CultureInfo.DateTimeFormat 属性返回的 DateTimeFormatInfo 对象定义 input中使用的格式。

• 定义日期和时间数据格式的 DateTimeFormatInfo 对象。

如果 formatProvidernull，则使用与当前区域性关联的 DateTimeFormatInfo 对象（请参阅 CurrentCulture）。

调用方说明

ToString(String, IFormatProvider) 方法返回 formatProvider 参数使用的日历中的日期和时间的字符串表示形式。 其日历由 Calendar 属性定义。 如果当前 DateTimeOffset 实例的值早于 MinSupportedDateTime 或晚于 MaxSupportedDateTime，该方法将引发 ArgumentOutOfRangeException。 以下示例提供了一个插图。 它尝试设置 UmAlQuraCalendar 类范围之外的日期的格式。

C#

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      CultureInfo arSA = new CultureInfo("ar-SA");
      arSA.DateTimeFormat.Calendar = new UmAlQuraCalendar();
      DateTimeOffset date1 = new DateTimeOffset(new DateTime(1890, 9, 10),
                                                TimeSpan.Zero);

      try {
         Console.WriteLine(date1.ToString("d", arSA));
      }
      catch (ArgumentOutOfRangeException) {
         Console.WriteLine("{0:d} is earlier than {1:d} or later than {2:d}",
                           date1,
                           arSA.DateTimeFormat.Calendar.MinSupportedDateTime,
                           arSA.DateTimeFormat.Calendar.MaxSupportedDateTime);
      }
   }
}
// The example displays the following output:
//    9/10/1890 is earlier than 4/30/1900 or later than 5/13/2029

另请参阅

• 标准日期和时间格式字符串
• 自定义日期和时间格式字符串
• 示例：.NET Core WinForms 格式设置实用工具 （C#）
• 示例：.NET Core WinForms 格式设置实用工具 （Visual Basic）