• Artigo

DateTimeOffset.TryParseExact Method (String, array<String[], IFormatProvider, DateTimeStyles, DateTimeOffset%)

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified array of formats, culture-specific format information, and style. The format of the string representation must match one of the specified formats exactly.

Namespace:  System
Assembly:  mscorlib (in mscorlib.dll)

Syntax

'Declaration
Public Shared Function TryParseExact ( _
    input As String, _
    formats As String(), _
    formatProvider As IFormatProvider, _
    styles As DateTimeStyles, _
    <OutAttribute> ByRef result As DateTimeOffset _
) As Boolean

public static bool TryParseExact(
    string input,
    string[] formats,
    IFormatProvider formatProvider,
    DateTimeStyles styles,
    out DateTimeOffset result
)

Parameters

  • input
    Type: System.String
    A string that contains a date and time to convert.
  • formats
    Type: array<System.String[]
    An array that defines the expected formats of input.
  • formatProvider
    Type: System.IFormatProvider
    An object that supplies culture-specific formatting information about input.
  • styles
    Type: System.Globalization.DateTimeStyles
    A bitwise combination of enumeration values that indicates the permitted format of input. A typical value to specify is None.
  • result
    Type: System.DateTimeOffset%
    When the method returns, contains the DateTimeOffset equivalent to the date and time of input, if the conversion succeeded, or MinValue, if the conversion failed. The conversion fails if the input does not contain a valid string representation of a date and time, or does not contain the date and time in the expected format defined by format, or if formats is nulla null reference (Nothing in Visual Basic). This parameter is passed uninitialized.

Return Value

Type: System.Boolean
true if the input parameter is successfully converted; otherwise, false.

Exceptions

Exception Condition
ArgumentException

styles includes an undefined DateTimeStyles value.

-or-

DateTimeStyles.NoCurrentDateDefault is not supported.

-or-

styles includes mutually exclusive DateTimeStyles values.

Remarks

The TryParseExact(String, array<String[], IFormatProvider, DateTimeStyles, DateTimeOffset%) method parses the string representation of a date that matches any one of the patterns assigned to the formats array. If the input string does not match any one of these patterns with any variations defined by the styles parameter, the parsing operation fails and the method returns false. Aside from comparing input to multiple strings that contain format specifiers, this overload behaves identically to the DateTimeOffset.ParseExact(String, array<String[], IFormatProvider, DateTimeStyles) method.

The formats parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of input. For details about valid formatting codes, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. If the matched element in formats includes the z, zz, or zzz custom format specifiers to indicate that an offset must be present in input, that offset must include either a negative sign or a positive sign. If the sign is missing, the parse operation fails and the method returns false.

Important noteImportant Note:

Using the formats parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this.

If the matched element in formats requires that input contain a date but not a time, the resulting DateTimeOffset object is assigned a time of midnight (0:00:00). If the matched element in formats requires that input contain a time but not a date, the resulting DateTimeOffset object is assigned the current date on the local system. If the matched element in formats does not require that input contain an offset, the offset of the resulting DateTimeOffset object depends on the value of the styles parameter. If styles includes AssumeLocal, the offset of the local time zone is assigned to the DateTimeOffset object. If styles includes AssumeUniversal, the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the DateTimeOffset object. If neither value is specified, the offset of the local time zone is used.

The particular date and time symbols and strings used in input are defined by the formatProvider parameter. The same is true for the precise pattern of input if the matching element of formats is a standard format specifier string. The formatProvider parameter can be either of the following:

If formatprovider is nulla null reference (Nothing in Visual Basic), the CultureInfo object that corresponds to the current culture is used.

The styles parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the DateTimeStyles enumeration are supported except NoCurrentDateDefault. The following table lists the effect of each supported member.

DateTimeStyles member

Behavior

AdjustToUniversal

Parses input and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the DateTimeOffset.ToUniversalTime method of the returned DateTimeOffset object.

AssumeLocal

If the matched element in formats does not require that input contain an offset value, the returned DateTimeOffset object is given the offset of the local time zone. This is the default value.

AssumeUniversal

If the matched element in formats does not require that input contain an offset value, the returned DateTimeOffset object is given the UTC offset (+00:00).

AllowInnerWhite

Allows input to include inner white space not specified by the elements in formats. Extra white space can appear between date and time components and within individual components (except for the offset) and is ignored when parsing the string.

AllowLeadingWhite

Allows input to include leading spaces not specified by the elements in formats. These are ignored when parsing the string.

AllowTrailingWhite

Allows input to include trailing spaces not specified by the elements in formats. These are ignored when parsing the string.

AllowWhiteSpaces

Allows input to include leading, trailing, and inner spaces not specified by the elements in formats. All extra white-space characters not specified in the matched element in formats are ignored when parsing the string.

None

Indicates that additional white space is not permitted in input. White space must appear exactly as specified in a particular element in formats for a successful match to occur. This is the default behavior.

RoundtripKind

Has no effect because the DateTimeOffset structure does not include a Kind property.

Examples

The following example defines multiple input formats for the string representation of a date and time and offset value, and then passes the string that is entered by the user to the TryParseExact(String, array<String[], IFormatProvider, DateTimeStyles, DateTimeOffset%) method.

Dim conIn As TextReader = Console.In
Dim conOut As TextWriter = Console.Out
Dim tries As Integer = 0
Dim input As String = String.Empty
Dim formats() As String = {"M/dd/yyyy HH:m zzz", "MM/dd/yyyy HH:m zzz", _
                           "M/d/yyyy HH:m zzz", "MM/d/yyyy HH:m zzz", _
                           "M/dd/yy HH:m zzz", "MM/dd/yy HH:m zzz", _
                           "M/d/yy HH:m zzz", "MM/d/yy HH:m zzz", _
                           "M/dd/yyyy H:m zzz", "MM/dd/yyyy H:m zzz", _
                           "M/d/yyyy H:m zzz", "MM/d/yyyy H:m zzz", _
                           "M/dd/yy H:m zzz", "MM/dd/yy H:m zzz", _
                           "M/d/yy H:m zzz", "MM/d/yy H:m zzz", _
                           "M/dd/yyyy HH:mm zzz", "MM/dd/yyyy HH:mm zzz", _
                           "M/d/yyyy HH:mm zzz", "MM/d/yyyy HH:mm zzz", _
                           "M/dd/yy HH:mm zzz", "MM/dd/yy HH:mm zzz", _
                           "M/d/yy HH:mm zzz", "MM/d/yy HH:mm zzz", _
                           "M/dd/yyyy H:mm zzz", "MM/dd/yyyy H:mm zzz", _
                           "M/d/yyyy H:mm zzz", "MM/d/yyyy H:mm zzz", _
                           "M/dd/yy H:mm zzz", "MM/dd/yy H:mm zzz", _
                           "M/d/yy H:mm zzz", "MM/d/yy H:mm zzz"}
Dim provider As IFormatProvider = CultureInfo.InvariantCulture.DateTimeFormat
Dim result As DateTimeOffset

Do
   conOut.WriteLine("Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),")
   conOut.Write("Then press Enter: ")
   input = conIn.ReadLine()
   conOut.WriteLine()
   If DateTimeOffset.TryParseExact(input, formats, provider, _
                                   DateTimeStyles.AllowWhiteSpaces, _
                                   result) Then
      Exit Do
   Else
      outputBlock.Text &= String.Format("Unable to parse {0}.", input) & vbCrLf
      tries += 1
   End If
Loop While tries < 3
If tries >= 3 Then
   outputBlock.Text &= String.Format("Exiting application without parsing {0}", input) & vbCrLf
Else
   outputBlock.Text &= String.Format("{0} was converted to {1}", input, result.ToString()) & vbCrLf
End If
' Some successful sample interactions with the user might appear as follows:
'    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
'    Then press Enter: 12/08/2007 6:54 -6:00
'    
'    12/08/2007 6:54 -6:00 was converted to 12/8/2007 6:54:00 AM -06:00         
'    
'    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
'    Then press Enter: 12/8/2007 06:54 -06:00
'    
'    12/8/2007 06:54 -06:00 was converted to 12/8/2007 6:54:00 AM -06:00
'    
'    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
'    Then press Enter: 12/5/07 6:54 -6:00
'    
'    12/5/07 6:54 -6:00 was converted to 12/5/2007 6:54:00 AM -06:00 

TextReader conIn = Console.In;
TextWriter conOut = Console.Out;
int tries = 0;
string input = String.Empty;

string[] formats = new string[] {"M/dd/yyyy HH:m zzz", "MM/dd/yyyy HH:m zzz", 
                                 "M/d/yyyy HH:m zzz", "MM/d/yyyy HH:m zzz", 
                                 "M/dd/yy HH:m zzz", "MM/dd/yy HH:m zzz", 
                                 "M/d/yy HH:m zzz", "MM/d/yy HH:m zzz",                                 
                                 "M/dd/yyyy H:m zzz", "MM/dd/yyyy H:m zzz", 
                                 "M/d/yyyy H:m zzz", "MM/d/yyyy H:m zzz", 
                                 "M/dd/yy H:m zzz", "MM/dd/yy H:m zzz", 
                                 "M/d/yy H:m zzz", "MM/d/yy H:m zzz",                               
                                 "M/dd/yyyy HH:mm zzz", "MM/dd/yyyy HH:mm zzz", 
                                 "M/d/yyyy HH:mm zzz", "MM/d/yyyy HH:mm zzz", 
                                 "M/dd/yy HH:mm zzz", "MM/dd/yy HH:mm zzz", 
                                 "M/d/yy HH:mm zzz", "MM/d/yy HH:mm zzz",                                 
                                 "M/dd/yyyy H:mm zzz", "MM/dd/yyyy H:mm zzz", 
                                 "M/d/yyyy H:mm zzz", "MM/d/yyyy H:mm zzz", 
                                 "M/dd/yy H:mm zzz", "MM/dd/yy H:mm zzz", 
                                 "M/d/yy H:mm zzz", "MM/d/yy H:mm zzz"};
IFormatProvider provider = CultureInfo.InvariantCulture.DateTimeFormat;
DateTimeOffset result;

do
{
   conOut.WriteLine("Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),");
   conOut.Write("Then press Enter: ");
   input = conIn.ReadLine();
   conOut.WriteLine();
   if (DateTimeOffset.TryParseExact(input, formats, provider,
                                   DateTimeStyles.AllowWhiteSpaces,
                                   out result))
   {
      break;
   }
   else
   {
      outputBlock.Text += String.Format("Unable to parse {0}.", input) + "\n";
      tries++;
   }
} while (tries < 3);
if (tries >= 3)
   outputBlock.Text += String.Format("Exiting application without parsing {0}", input) + "\n";
else
   outputBlock.Text += String.Format("{0} was converted to {1}", input, result.ToString()) + "\n";
// Some successful sample interactions with the user might appear as follows:
//    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
//    Then press Enter: 12/08/2007 6:54 -6:00
//    
//    12/08/2007 6:54 -6:00 was converted to 12/8/2007 6:54:00 AM -06:00         
//    
//    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
//    Then press Enter: 12/8/2007 06:54 -06:00
//    
//    12/8/2007 06:54 -06:00 was converted to 12/8/2007 6:54:00 AM -06:00
//    
//    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
//    Then press Enter: 12/5/07 6:54 -6:00
//    
//    12/5/07 6:54 -6:00 was converted to 12/5/2007 6:54:00 AM -06:00

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.