DateTimeOffset.ParseExact Método

Definição

Converte a representação da cadeia de caracteres especificada de uma data e hora no DateTimeOffset equivalente. O formato da representação da cadeia de caracteres deve corresponder exatamente a um formato especificado.

Sobrecargas

ParseExact(String, String[], IFormatProvider, DateTimeStyles)

Converte a representação da cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato, informações do formato específico da cultura e o estilo especificados. O formato da representação da cadeia de caracteres deve corresponder exatamente a um dos formatos especificados.

ParseExact(String, String, IFormatProvider, DateTimeStyles)

Converte a representação de cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato especificado, as informações de formato específicas da cultura e o estilo. O formato de representação da cadeia de caracteres deve corresponder exatamente ao formato especificado.

ParseExact(String, String, IFormatProvider)

Converte a representação de cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato especificado e as informações de formato específicas da cultura. O formato de representação da cadeia de caracteres deve corresponder exatamente ao formato especificado.

ParseExact(ReadOnlySpan<Char>, ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles)

Converte um intervalo de caracteres que representa uma data e hora em seu equivalente DateTimeOffset usando o formato especificado, as informações de formato específicas da cultura e o estilo. O formato de representação da cadeia de caracteres deve corresponder exatamente ao formato especificado.

ParseExact(ReadOnlySpan<Char>, String[], IFormatProvider, DateTimeStyles)

Converte um intervalo de caracteres que contém a representação da cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato, informações do formato específico da cultura e o estilo especificados. O formato da representação de data e hora deve corresponder exatamente a um dos formatos especificados.

ParseExact(String, String[], IFormatProvider, DateTimeStyles)

Converte a representação da cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato, informações do formato específico da cultura e o estilo especificados. O formato da representação da cadeia de caracteres deve corresponder exatamente a um dos formatos especificados.

public static DateTimeOffset ParseExact (string input, string[] formats, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles);
public static DateTimeOffset ParseExact (string input, string[] formats, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles);

Parâmetros

input
String

Uma cadeia de caracteres que contém uma data e hora a ser convertida.

formats
String[]

Uma matriz de especificadores de formato que definem os formatos esperados de input.

formatProvider
IFormatProvider

Um objeto que fornece informações de formatação específicas da cultura sobre input.

styles
DateTimeStyles

Um combinação bit a bit de valores de enumeração que indica o formato permitido de input.

Retornos

DateTimeOffset

Um objeto equivalente à data e hora contidas no parâmetro input, conforme especificado pelos parâmetros formats, formatProvider e styles.

Exceções

O deslocamento é maior que 14 horas ou menor que -14 horas.

- ou -

styles inclui um valor sem suporte.

- ou -

O parâmetro styles contém valores DateTimeStyles que não podem ser usados juntos.

input é null.

input é uma cadeia de caracteres vazia ("").

- ou -

input não contém uma representação da cadeia de caracteres válida de uma data e hora.

- ou -

Nenhum elemento de formats contém um especificador de formato válido.

- ou -

O componente de hora e o designador AM/PM no input não concordam.

Exemplos

O exemplo a seguir define vários formatos de entrada para a representação de cadeia de caracteres de um valor de data e hora e deslocamento e, em seguida, passa a cadeia de caracteres que é inserida pelo usuário para o DateTimeOffset.ParseExact(String, String[], IFormatProvider, DateTimeStyles) método.

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 = new 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();
   try
   {
      result = DateTimeOffset.ParseExact(input, formats, provider,
                                         DateTimeStyles.AllowWhiteSpaces);
      break;
   }
   catch (FormatException)
   {
      Console.WriteLine("Unable to parse {0}.", input);
      tries++;
   }
} while (tries < 3);
if (tries >= 3)
   Console.WriteLine("Exiting application without parsing {0}", input);
else
   Console.WriteLine("{0} was converted to {1}", input, result.ToString());
// 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

Comentários

O DateTimeOffset.ParseExact(String, String[], IFormatProvider, DateTimeStyles) método analisa a representação de cadeia de caracteres de uma data que corresponde a qualquer um dos padrões atribuídos ao formats parâmetro. Se a input cadeia de caracteres não corresponder a nenhum desses padrões com qualquer uma das variações definidas pelo styles parâmetro, o método gerará um FormatException. Além de comparar com input vários padrões de formatação, essa sobrecarga se comporta de forma idêntica ao DateTimeOffset.ParseExact(String, String, IFormatProvider, DateTimeStyles) método.

O formats parâmetro é uma matriz de cadeia de caracteres cujos elementos contêm um único especificador de formato padrão ou um ou mais especificadores de formato personalizado que definem o padrão possível do input parâmetro. Quando o método é chamado, input deve corresponder a um desses padrões. Para obter detalhes sobre códigos de formatação válidos, consulte Cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas. Se o elemento correspondente incluir formats os zespecificadores de formato personalizado ou zzz , zzpara indicar que um deslocamento deve estar presenteinput, esse deslocamento deve incluir um sinal negativo ou um sinal positivo. Se o sinal estiver ausente, o método lançará um FormatException.

Importante

Usar o formats parâmetro dessa sobrecarga para especificar vários formatos pode ajudar a reduzir a frustração que muitos usuários experimentam ao inserir datas e horas. Em particular, a capacidade de definir vários padrões de entrada permite que um aplicativo manipule representações de data e hora que podem incluir ou não zeros à esquerda em meses, dias, horas, minutos e segundos. O exemplo fornece uma ilustração disso.

Se o elemento correspondente exigir formats que input contenha uma data, mas não uma hora, o objeto resultante DateTimeOffset recebe uma hora da meia-noite (0:00:00). Se o elemento correspondente exigir formats que input contenha uma hora, mas não uma data, o objeto resultante DateTimeOffset recebe a data atual no sistema local. Se o elemento formats correspondente não exigir que input contenha um deslocamento, o deslocamento do objeto resultante DateTimeOffset dependerá do valor do styles parâmetro. Caso styles inclua AssumeLocal, o deslocamento do fuso horário local é atribuído ao objeto DateTimeOffset. Caso styles inclua AssumeUniversal, o deslocamento de Tempo Universal Coordenado (UTC), ou +00:00, é atribuído ao objeto DateTimeOffset. Caso nenhum valor seja especificado, o deslocamento do fuso horário local é usado.

Os símbolos de data e hora específicos e as cadeias de caracteres usadas em input são definidos pelo parâmetro formatProvider. O mesmo vale para o formato preciso de input, se o elemento correspondente for uma cadeia de caracteres do especificador de formats formato padrão. O parâmetro formatProvider pode ser qualquer um dos seguintes:

Caso formatprovider seja null, o objeto CultureInfo que corresponde à cultura atual é usado.

O styles parâmetro define se o espaço em branco é permitido na cadeia de caracteres de entrada, indica como as cadeias de caracteres sem um componente de deslocamento explícito são analisadas e dá suporte à conversão UTC como parte da operação de análise. Todos os membros da enumeração DateTimeStyles são suportados, exceto NoCurrentDateDefault. A tabela a seguir lista o efeito de cada membro suportado.

Membro do DateTimeStyles Comportamento
AdjustToUniversal Analisa input e, caso necessário, converte-o em UTC. Ele é equivalente à análise de uma cadeia de caracteres e, em seguida, à chamada do método DateTimeOffset.ToUniversalTime do objeto DateTimeOffset retornado.
AssumeLocal Se o elemento formats correspondente não exigir que input contenha um valor de deslocamento, o objeto retornado DateTimeOffset recebe o deslocamento do fuso horário local. Este é o valor padrão.
AssumeUniversal Se o elemento formats correspondente não exigir que input contenha um valor de deslocamento, o objeto retornado DateTimeOffset recebe o deslocamento UTC (+00:00).
AllowInnerWhite input Permite incluir espaço em branco interno não especificado por format. O espaço em branco extra pode aparecer entre componentes de data e hora e dentro de componentes individuais (exceto o deslocamento) e é ignorado ao analisar a cadeia de caracteres.
AllowLeadingWhite Permite incluir espaços à esquerda não especificados input por formats. Eles são ignorados durante a análise da cadeia de caracteres.
AllowTrailingWhite Permite incluir espaços à direita não especificados input por formats. Eles são ignorados durante a análise da cadeia de caracteres.
AllowWhiteSpaces Permite incluir espaços à esquerda, à direita e internos não especificados input por formats. Todos os caracteres de espaço em branco extras não especificados no elemento formats correspondente são ignorados ao analisar a cadeia de caracteres.
None Indica que o espaço em branco adicional não é permitido em input. O espaço em branco deve aparecer exatamente como especificado em um elemento específico para formats que uma correspondência ocorra. Esse é o comportamento padrão.
RoundtripKind Não tem efeito porque a DateTimeOffset estrutura não inclui uma Kind propriedade.

Notas aos Chamadores

No .NET Framework 4, o ParseExact método gerará um FormatException se a cadeia de caracteres a ser analisada contiver um componente de hora e um designador AM/PM que não estejam de acordo. No .NET Framework 3.5 e versões anteriores, o designador AM/PM é ignorado.

Confira também

Aplica-se a

.NET 7 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

ParseExact(String, String, IFormatProvider, DateTimeStyles)

Converte a representação de cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato especificado, as informações de formato específicas da cultura e o estilo. O formato de representação da cadeia de caracteres deve corresponder exatamente ao formato especificado.

public static DateTimeOffset ParseExact (string input, string format, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles);
public static DateTimeOffset ParseExact (string input, string format, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles);

Parâmetros

input
String

Uma cadeia de caracteres que contém uma data e hora a ser convertida.

format
String

Um especificador de formato que define o formato esperado de input.

formatProvider
IFormatProvider

Um objeto que fornece informações de formatação específicas da cultura sobre input.

styles
DateTimeStyles

Um combinação bit a bit de valores de enumeração que indica o formato permitido de input.

Retornos

DateTimeOffset

Um objeto equivalente à data e hora contidas no parâmetro input, conforme especificado pelos parâmetros format, formatProvider e styles.

Exceções

O deslocamento é maior que 14 horas ou menor que -14 horas.

- ou -

O parâmetro styles inclui um valor sem suporte.

- ou -

O parâmetro styles contém valores DateTimeStyles que não podem ser usados juntos.

input é null.

- ou -

format é null.

input é uma cadeia de caracteres vazia ("").

- ou -

input não contém uma representação da cadeia de caracteres válida de uma data e hora.

- ou -

format é uma cadeia de caracteres vazia.

- ou -

O componente de hora e o designador AM/PM no input não concordam.

Exemplos

O exemplo a seguir usa o DateTimeOffset.ParseExact(String, String, IFormatProvider, DateTimeStyles) método com especificadores de formato padrão e personalizado, a cultura invariável e vários DateTimeStyles valores para analisar várias cadeias de caracteres de data e hora.

string dateString, format;
DateTimeOffset result;
CultureInfo provider = CultureInfo.InvariantCulture;

// Parse date-only value with invariant culture and assume time is UTC.
dateString = "06/15/2008";
format = "d";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AssumeUniversal);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}

// Parse date-only value with leading white space.
// Should throw a FormatException because only trailing white space is
// specified in method call.
dateString = " 06/15/2008";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AllowTrailingWhite);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}

// Parse date and time value, and allow all white space.
dateString = " 06/15/   2008  15:15    -05:00";
format = "MM/dd/yyyy H:mm zzz";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AllowWhiteSpaces);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}

// Parse date and time and convert to UTC.
dateString = "  06/15/2008 15:15:30 -05:00";
format = "MM/dd/yyyy H:mm:ss zzz";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AllowWhiteSpaces |
                                      DateTimeStyles.AdjustToUniversal);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}
// The example displays the following output:
//    '06/15/2008' converts to 6/15/2008 12:00:00 AM +00:00.
//    ' 06/15/2008' is not in the correct format.
//    ' 06/15/   2008  15:15    -05:00' converts to 6/15/2008 3:15:00 PM -05:00.
//    '  06/15/2008 15:15:30 -05:00' converts to 6/15/2008 8:15:30 PM +00:00.

O exemplo a seguir usa uma variedade de DateTimeStyles valores para analisar uma matriz de cadeias de caracteres que devem estar em conformidade com o ISO 8601. Como mostra a saída do exemplo, as cadeias de caracteres que estão no formato adequado não conseguem analisar se:

As cadeias de caracteres que não especificam um deslocamento UTC devem ter o deslocamento do fuso horário local (neste caso, -07:00), a menos que o DateTimeStyles.AssumeUniversal sinalizador seja fornecido na chamada de método. Nesse caso, eles são considerados tempo coordenado universal.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      string[] dateStrings = { "2018-08-18T12:45:16.0000000Z",
                               "2018/08/18T12:45:16.0000000Z",
                               "2018-18-08T12:45:16.0000000Z",
                               "2018-08-18T12:45:16.0000000",                               
                               " 2018-08-18T12:45:16.0000000Z ",
                               "2018-08-18T12:45:16.0000000+02:00",
                               "2018-08-18T12:45:16.0000000-07:00" }; 
      
      ParseWithISO8601(dateStrings, DateTimeStyles.None);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AllowWhiteSpaces);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AdjustToUniversal);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AssumeLocal);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AssumeUniversal);   }

   private static void ParseWithISO8601(string[] dateStrings, DateTimeStyles styles)
   {   
      Console.WriteLine($"Parsing with {styles}:");
      foreach (var dateString in dateStrings)
      {
         try {
            var date = DateTimeOffset.ParseExact(dateString, "O", null, styles);
            Console.WriteLine($"   {dateString,-35} --> {date:yyyy-MM-dd HH:mm:ss.FF zzz}");
         }
         catch (FormatException)
         {
            Console.WriteLine($"   FormatException: Unable to convert '{dateString}'");
         }   
      } 
   }
}
// The example displays the following output:
//      Parsing with None:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 -07:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00
//
//      -----
//
//      Parsing with AllowWhiteSpaces:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 -07:00
//         2018-08-18T12:45:16.0000000Z       --> 2018-08-18 12:45:16 +00:00
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00
//
//      -----
//
//      Parsing with AdjustToUniversal:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 19:45:16 +00:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 10:45:16 +00:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 19:45:16 +00:00
//
//      -----
//
//      Parsing with AssumeLocal:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 -07:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00
//
//      -----
//
//      Parsing with AssumeUniversal:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00

Comentários

O DateTimeOffset.ParseExact(String, String, IFormatProvider, DateTimeStyles) método analisa a representação de cadeia de caracteres de uma data, que deve estar no formato definido pelo format parâmetro. Também requer que os elementos e <Offset> a <Date><Time>representação da cadeia de caracteres de uma data e hora apareçam na ordem especificada por format. Se a input cadeia de caracteres não corresponder ao padrão do format parâmetro, com quaisquer variações definidas pelo styles parâmetro, o método gerará um FormatException. Por outro lado, o DateTimeOffset.Parse(String, IFormatProvider, DateTimeStyles) método analisa a representação de cadeia de caracteres de uma data em qualquer um dos formatos reconhecidos pelo objeto do provedor de DateTimeFormatInfo formato. Parsetambém permite que os <Date><Time>elementos e <Offset> a representação da cadeia de caracteres de uma data e hora apareçam em qualquer ordem.

O format parâmetro é uma cadeia de caracteres que contém um único especificador de formato padrão ou um ou mais especificadores de formato personalizado que definem o padrão necessário do input parâmetro. Para obter detalhes sobre códigos de formatação válidos, consulte Cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas. Se format incluir os zespecificadores de formato personalizado ou zzz , zzpara indicar que um deslocamento deve estar presenteinput, esse deslocamento deve incluir um sinal negativo ou um sinal positivo. Se o sinal estiver ausente, o método lançará um FormatException.

Se format for necessário que input contenha uma data, mas não uma hora, o objeto resultante DateTimeOffset recebe uma hora da meia-noite (0:00:00). Se format for necessário que input contenha uma hora, mas não uma data, o objeto resultante DateTimeOffset recebe a data atual no sistema local. Se format não exigir que input contenha um deslocamento, o deslocamento do objeto resultante DateTimeOffset dependerá do valor do styles parâmetro. Caso styles inclua AssumeLocal, o deslocamento do fuso horário local é atribuído ao objeto DateTimeOffset. Caso styles inclua AssumeUniversal, o deslocamento de Tempo Universal Coordenado (UTC), ou +00:00, é atribuído ao objeto DateTimeOffset. Caso nenhum valor seja especificado, o deslocamento do fuso horário local é usado.

Os símbolos de data e hora específicos e as cadeias de caracteres usadas em input são definidos pelo parâmetro formatProvider. O mesmo vale para o formato preciso de input, se format for uma cadeia de caracteres do especificador de formato padrão. O parâmetro formatProvider pode ser qualquer um dos seguintes:

Caso formatprovider seja null, o objeto CultureInfo que corresponde à cultura atual é usado.

O styles parâmetro define se o espaço em branco é permitido na cadeia de caracteres de entrada, indica como as cadeias de caracteres sem um componente de deslocamento explícito são analisadas e dá suporte à conversão UTC como parte da operação de análise. Todos os membros da enumeração DateTimeStyles são suportados, exceto NoCurrentDateDefault. A tabela a seguir lista o efeito de cada membro suportado.

Membro do DateTimeStyles Comportamento
AdjustToUniversal Analisa input e, caso necessário, converte-o em UTC. Ele é equivalente à análise de uma cadeia de caracteres e, em seguida, à chamada do método DateTimeOffset.ToUniversalTime do objeto DateTimeOffset retornado.
AssumeLocal Se format não exigir que input contenha um valor de deslocamento, o objeto retornado DateTimeOffset recebe o deslocamento do fuso horário local. Este é o valor padrão.
AssumeUniversal Se format não exigir que input contenha um valor de deslocamento, o objeto retornado DateTimeOffset recebe o deslocamento UTC (+00:00).
AllowInnerWhite input Permite incluir espaço em branco interno não especificado por format. O espaço em branco extra pode aparecer entre componentes de data e hora e dentro de componentes individuais e é ignorado ao analisar a cadeia de caracteres.
AllowLeadingWhite Permite incluir espaços à esquerda não especificados input por format. Eles são ignorados durante a análise da cadeia de caracteres.
AllowTrailingWhite Permite incluir espaços à direita não especificados input por format. Eles são ignorados durante a análise da cadeia de caracteres.
AllowWhiteSpaces Permite incluir espaços à esquerda, à direita e internos não especificados input por format. Todos os caracteres de espaço em branco extras não especificados format são ignorados ao analisar a cadeia de caracteres.
None Indica que o espaço em branco adicional não é permitido em input. O espaço em branco deve aparecer exatamente como especificado em format. Esse é o comportamento padrão.
RoundtripKind Não tem efeito porque a DateTimeOffset estrutura não inclui uma Kind propriedade.

Notas aos Chamadores

No .NET Framework 4, o ParseExact método gerará um FormatException se a cadeia de caracteres a ser analisada contiver um componente de hora e um designador AM/PM que não estejam de acordo. No .NET Framework 3.5 e versões anteriores, o designador AM/PM é ignorado.

Confira também

Aplica-se a

.NET 7 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

ParseExact(String, String, IFormatProvider)

Converte a representação de cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato especificado e as informações de formato específicas da cultura. O formato de representação da cadeia de caracteres deve corresponder exatamente ao formato especificado.

public static DateTimeOffset ParseExact (string input, string format, IFormatProvider formatProvider);
public static DateTimeOffset ParseExact (string input, string format, IFormatProvider? formatProvider);

Parâmetros

input
String

Uma cadeia de caracteres que contém uma data e hora a ser convertida.

format
String

Um especificador de formato que define o formato esperado de input.

formatProvider
IFormatProvider

Um objeto que fornece informações de formatação específicas da cultura sobre input.

Retornos

DateTimeOffset

Um objeto equivalente à data e hora contida no input, conforme especificado por format e formatProvider.

Exceções

O deslocamento é maior que 14 horas ou menor que -14 horas.

input é null.

- ou -

format é null.

input é uma cadeia de caracteres vazia ("").

- ou -

input não contém uma representação da cadeia de caracteres válida de uma data e hora.

- ou -

format é uma cadeia de caracteres vazia.

- ou -

O componente de hora e o designador AM/PM no input não concordam.

Exemplos

O exemplo a seguir usa o DateTimeOffset.ParseExact(String, String, IFormatProvider) método com especificadores de formato padrão e personalizado e a cultura invariável para analisar várias cadeias de caracteres de data e hora.

string dateString, format;
DateTimeOffset result;
CultureInfo provider = CultureInfo.InvariantCulture;

// Parse date-only value with invariant culture.
dateString = "06/15/2008";
format = "d";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}

// Parse date-only value without leading zero in month using "d" format.
// Should throw a FormatException because standard short date pattern of
// invariant culture requires two-digit month.
dateString = "6/15/2008";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}

// Parse date and time with custom specifier.
dateString = "Sun 15 Jun 2008 8:30 AM -06:00";
format = "ddd dd MMM yyyy h:mm tt zzz";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}

// Parse date and time with offset without offset//s minutes.
// Should throw a FormatException because "zzz" specifier requires leading
// zero in hours.
dateString = "Sun 15 Jun 2008 8:30 AM -06";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}
// The example displays the following output:
//    06/15/2008 converts to 6/15/2008 12:00:00 AM -07:00.
//    6/15/2008 is not in the correct format.
//    Sun 15 Jun 2008 8:30 AM -06:00 converts to 6/15/2008 8:30:00 AM -06:00.
//    Sun 15 Jun 2008 8:30 AM -06 is not in the correct format.

O exemplo a seguir analisa uma matriz de cadeias de caracteres que devem estar em conformidade com o ISO 8601. Como mostra a saída do exemplo, cadeias de caracteres com espaços à esquerda ou à direita não conseguem analisar com êxito, assim como cadeias de caracteres com elementos de data e hora que estão fora do intervalo.

using System;

public class Example2
{
   public static void Main()
   {
      string[] dateStrings = { "2018-08-18T12:45:16.0000000Z",
                               "2018/08/18T12:45:16.0000000Z",
                               "2018-18-08T12:45:16.0000000Z",
                               " 2018-08-18T12:45:16.0000000Z ",
                               "2018-08-18T12:45:16.0000000+02:00",
                               "2018-08-18T12:45:16.0000000-07:00" }; 
      
      foreach (var dateString in dateStrings)
      {
         try {
            var date = DateTimeOffset.ParseExact(dateString, "O", null);
            Console.WriteLine($"{dateString,-35} --> {date:yyyy-MM-dd HH:mm:ss.FF zzz}");
         }
         catch (FormatException)
         {
            Console.WriteLine($"FormatException: Unable to convert '{dateString}'");
         }   
      } 
   }
}
// The example displays the following output:
//      2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//      FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//      FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//      FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//      2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//      2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00

Comentários

O ParseExact(String, String, IFormatProvider) método analisa a representação de cadeia de caracteres de uma data, que deve estar no formato definido pelo format parâmetro. Ele também requer que os <Date>elementos e <Offset> a <Time>representação de cadeia de caracteres de uma data e hora apareçam na ordem especificada por format. Se a input cadeia de caracteres não corresponder a esse format parâmetro, o método gerará um FormatException. Por outro lado, o DateTimeOffset.Parse(String, IFormatProvider) método analisa a representação de cadeia de caracteres de uma data em qualquer um dos formatos reconhecidos pelo objeto do provedor de DateTimeFormatInfo formato. Parsetambém permite que os <Date><Time>elementos e <Offset> a representação da cadeia de caracteres de uma data e hora apareçam em qualquer ordem.

O format parâmetro é uma cadeia de caracteres que contém um único especificador de formato padrão ou um ou mais especificadores de formato personalizado que definem o formato necessário do input parâmetro. Para obter detalhes sobre códigos de formatação válidos, consulte Cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas. Se format incluir os zespecificadores de formato personalizado ou zzz , zzpara indicar que um deslocamento deve estar presenteinput, esse deslocamento deve incluir um sinal negativo ou um sinal positivo. Se o sinal estiver ausente, o método lançará um FormatException.

Se format for necessário que input contenha uma data, mas não uma hora, o objeto resultante DateTimeOffset recebe uma hora da meia-noite (0:00:00). Se format for necessário que input contenha uma hora, mas não uma data, o objeto resultante DateTimeOffset recebe a data atual no sistema local. Se format não exigir que input contenha um deslocamento, o objeto resultante DateTimeOffset recebe o deslocamento de fuso horário do sistema local.

Os símbolos e cadeias de caracteres de data e hora específicos usados input são definidos pelo formatProvider parâmetro, assim como o formato preciso de se format for uma cadeia de caracteres do especificador de input formato padrão. O parâmetro formatProvider pode ser qualquer um dos seguintes:

Caso formatprovider seja null, o objeto CultureInfo que corresponde à cultura atual é usado.

Notas aos Chamadores

No .NET Framework 4, o ParseExact método gerará um FormatException se a cadeia de caracteres a ser analisada contiver um componente de hora e um designador AM/PM que não estejam de acordo. No .NET Framework 3.5 e versões anteriores, o designador AM/PM é ignorado.

Confira também

Aplica-se a

.NET 7 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

ParseExact(ReadOnlySpan<Char>, ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles)

Converte um intervalo de caracteres que representa uma data e hora em seu equivalente DateTimeOffset usando o formato especificado, as informações de formato específicas da cultura e o estilo. O formato de representação da cadeia de caracteres deve corresponder exatamente ao formato especificado.

public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, ReadOnlySpan<char> format, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);
public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, ReadOnlySpan<char> format, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);

Parâmetros

input
ReadOnlySpan<Char>

Um intervalo de caracteres que representa uma data e hora.

format
ReadOnlySpan<Char>

Um intervalo de caracteres que contém um especificador de formato que define o formato esperado de input.

formatProvider
IFormatProvider

Um objeto que fornece informações de formatação específicas à cultura sobre input.

styles
DateTimeStyles

Um combinação bit a bit de valores de enumeração que indica o formato permitido de input.

Retornos

DateTimeOffset

Um objeto equivalente à data e hora contidas no parâmetro input, conforme especificado pelos parâmetros format, formatProvider e styles.

Exceções

O deslocamento é maior que 14 horas ou menor que -14 horas. -ou- O styles parâmetro inclui um valor sem suporte. -ou- O styles parâmetro contém DateTimeStyles valores que não podem ser usados juntos.

input é um intervalo de caracteres vazio.

  • ou - input não contém uma representação da cadeia de caracteres válida de uma data e hora.
  • ou - format é um intervalo de caracteres vazio. -ou- O componente de hora e o designador AM/PM não input concordam.

Comentários

Esse método analisa um intervalo de caracteres que representa uma data, que deve estar no formato definido pelo format parâmetro. Também requer que os elementos e <Offset> a <Date><Time>representação da cadeia de caracteres de uma data e hora apareçam na ordem especificada por format. Se input não corresponder ao format padrão, o método lançará um FormatException. Por outro lado, o DateTimeOffset.Parse(ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles) método analisa a representação de cadeia de caracteres de uma data em qualquer um dos formatos reconhecidos pelo objeto do provedor de DateTimeFormatInfo formato. Parsetambém permite que os <Date><Time>elementos e <Offset> a representação da cadeia de caracteres de uma data e hora apareçam em qualquer ordem.

O format parâmetro é um intervalo de caracteres que contém um especificador de formato padrão de caractere único ou um ou mais especificadores de formato personalizado que definem o formato necessário do input parâmetro. Para obter detalhes sobre códigos de formatação válidos, consulte Cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas. Se format incluir os zespecificadores de formato personalizado ou zzz , zzpara indicar que um deslocamento deve estar presenteinput, esse deslocamento deve incluir um sinal negativo ou um sinal positivo. Se o sinal estiver ausente, o método lançará um FormatException.

Se format for necessário que input contenha uma data, mas não uma hora, o objeto resultante DateTimeOffset recebe uma hora da meia-noite (0:00:00). Se format for necessário que input contenha uma hora, mas não uma data, o objeto resultante DateTimeOffset recebe a data atual no sistema local. Se format não exigir que input contenha um deslocamento, o objeto resultante DateTimeOffset recebe o deslocamento de fuso horário do sistema local.

Os símbolos e cadeias de caracteres de data e hora específicos usados input são definidos pelo formatProvider parâmetro, assim como o formato preciso de se format for um especificador de input formato padrão. O parâmetro formatProvider pode ser qualquer um dos seguintes:

Caso formatprovider seja null, o objeto CultureInfo que corresponde à cultura atual é usado.

Aplica-se a

.NET 7 e outras versões
Produto Versões
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7
.NET Standard 2.1

ParseExact(ReadOnlySpan<Char>, String[], IFormatProvider, DateTimeStyles)

Converte um intervalo de caracteres que contém a representação da cadeia de caracteres especificada de data e hora em seu equivalente DateTimeOffset usando o formato, informações do formato específico da cultura e o estilo especificados. O formato da representação de data e hora deve corresponder exatamente a um dos formatos especificados.

public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, string[] formats, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);
public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, string[] formats, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);

Parâmetros

input
ReadOnlySpan<Char>

Um intervalo de caracteres que contém uma data e hora a serem convertidas.

formats
String[]

Uma matriz de especificadores de formato que definem os formatos esperados de input.

formatProvider
IFormatProvider

Um objeto que fornece informações de formatação específicas da cultura sobre input.

styles
DateTimeStyles

Um combinação bit a bit de valores de enumeração que indica o formato permitido de input.

Retornos

DateTimeOffset

Um objeto equivalente à data e hora contidas no parâmetro input, conforme especificado pelos parâmetros formats, formatProvider e styles.

Exceções

O deslocamento é maior que 14 horas ou menor que -14 horas. -ou- styles inclui um valor sem suporte. -ou- O styles parâmetro contém DateTimeStyles valores que não podem ser usados juntos.

input é um intervalo de caracteres vazio.

  • ou - input não contém uma representação da cadeia de caracteres válida de uma data e hora. -ou- Nenhum elemento contém um especificador de formats formato válido. -ou- O componente de hora e o designador AM/PM não input concordam.

Comentários

Esse método analisa um intervalo de caracteres que representa uma data que corresponde a qualquer um dos padrões atribuídos ao formats parâmetro. Se input não corresponder a nenhum desses padrões com qualquer uma das variações definidas pelo styles parâmetro, o método gerará um FormatException. Além de comparar com input vários padrões de formatação, essa sobrecarga se comporta de forma idêntica ao DateTimeOffset.ParseExact(ReadOnlySpan<Char>, ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles) método.

O formats parâmetro é uma matriz de cadeia de caracteres cujos elementos contêm um único especificador de formato padrão ou um ou mais especificadores de formato personalizado que definem o padrão possível do input parâmetro. Quando o método é chamado, input deve corresponder a um desses padrões. Para obter detalhes sobre códigos de formatação válidos, consulte Cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas. Se o elemento correspondente incluir formats os zespecificadores de formato personalizado ou zzz , zzpara indicar que um deslocamento deve estar presenteinput, esse deslocamento deve incluir um sinal negativo ou um sinal positivo. Se o sinal estiver ausente, o método lançará um FormatException.

Importante

Usar o formats parâmetro dessa sobrecarga para especificar vários formatos pode ajudar a reduzir a frustração que muitos usuários experimentam ao inserir datas e horas. Em particular, a capacidade de definir vários padrões de entrada permite que um aplicativo manipule representações de data e hora que podem incluir ou não zeros à esquerda em meses, dias, horas, minutos e segundos.

Se o elemento correspondente exigir formats que input contenha uma data, mas não uma hora, o objeto resultante DateTimeOffset recebe uma hora da meia-noite (0:00:00). Se o elemento correspondente exigir formats que input contenha uma hora, mas não uma data, o objeto resultante DateTimeOffset recebe a data atual no sistema local. Se o elemento formats correspondente não exigir que input contenha um deslocamento, o deslocamento do objeto resultante DateTimeOffset dependerá do valor do styles parâmetro. Caso styles inclua AssumeLocal, o deslocamento do fuso horário local é atribuído ao objeto DateTimeOffset. Caso styles inclua AssumeUniversal, o deslocamento de Tempo Universal Coordenado (UTC), ou +00:00, é atribuído ao objeto DateTimeOffset. Caso nenhum valor seja especificado, o deslocamento do fuso horário local é usado.

Os símbolos de data e hora específicos e as cadeias de caracteres usadas em input são definidos pelo parâmetro formatProvider. O mesmo vale para o formato preciso de input, se o elemento correspondente for uma cadeia de caracteres do especificador de formats formato padrão. O parâmetro formatProvider pode ser qualquer um dos seguintes:

Caso formatprovider seja null, o objeto CultureInfo que corresponde à cultura atual é usado.

O styles parâmetro define se o espaço em branco é permitido na cadeia de caracteres de entrada, indica como as cadeias de caracteres sem um componente de deslocamento explícito são analisadas e dá suporte à conversão UTC como parte da operação de análise. Todos os membros da enumeração DateTimeStyles são suportados, exceto NoCurrentDateDefault. A tabela a seguir lista o efeito de cada membro suportado.

Membro do DateTimeStyles Comportamento
AdjustToUniversal Analisa input e, caso necessário, converte-o em UTC. Ele é equivalente à análise de uma cadeia de caracteres e, em seguida, à chamada do método DateTimeOffset.ToUniversalTime do objeto DateTimeOffset retornado.
AssumeLocal Se o elemento formats correspondente não exigir que input contenha um valor de deslocamento, o objeto retornado DateTimeOffset recebe o deslocamento do fuso horário local. Este é o valor padrão.
AssumeUniversal Se o elemento formats correspondente não exigir que input contenha um valor de deslocamento, o objeto retornado DateTimeOffset recebe o deslocamento UTC (+00:00).
AllowInnerWhite input Permite incluir espaço em branco interno não especificado por format. O espaço em branco extra pode aparecer entre componentes de data e hora e dentro de componentes individuais (exceto o deslocamento) e é ignorado ao analisar a cadeia de caracteres.
AllowLeadingWhite Permite incluir espaços à esquerda não especificados input por formats. Eles são ignorados durante a análise da cadeia de caracteres.
AllowTrailingWhite Permite incluir espaços à direita não especificados input por formats. Eles são ignorados durante a análise da cadeia de caracteres.
AllowWhiteSpaces Permite incluir espaços à esquerda, à direita e internos não especificados input por formats. Todos os caracteres de espaço em branco extras não especificados no elemento formats correspondente são ignorados ao analisar a cadeia de caracteres.
None Indica que o espaço em branco adicional não é permitido em input. O espaço em branco deve aparecer exatamente como especificado em um elemento específico para formats que uma correspondência ocorra. Esse é o comportamento padrão.
RoundtripKind Não tem efeito porque a DateTimeOffset estrutura não inclui uma Kind propriedade.

Aplica-se a

.NET 7 e outras versões
Produto Versões
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7
.NET Standard 2.1