Analisando Cadeias de Caracteres de Data e Hora no .NETParsing Date and Time Strings in .NET

A análise de cadeias de caracteres para convertê-las em objetos DateTime exige que você especifique as informações de como as datas e horas são representadas como texto.Parsing strings to convert them to DateTime objects requires you to specify information about how the dates and times are represented as text. Diferentes culturas usam ordens diferentes para dia, mês e ano.Different cultures use different orders for day, month, and year. Algumas representações usam o relógio de 24 horas, outras especificam "AM" e "PM".Some time representations use a 24-hour clock, others specify "AM" and "PM." Alguns aplicativos precisam apenas da data.Some applications need only the date. Outros precisam apenas da hora.Others need only the time. Há também outros que precisam especificar tanto a data quanto a hora.Still others need to specify both the date and the time. Os métodos que convertem cadeias de caracteres em objetos DateTime permitem que você forneça informações detalhadas sobre os formatos esperados e os elementos de uma data e hora que seu aplicativo precisa.The methods that convert strings to DateTime objects enable you to provide detailed information about the formats you expect and the elements of a date and time your application needs. Há três subtarefas para converter corretamente o texto em um DateTime:There are three subtasks to correctly converting text into a DateTime:

  1. Você deve especificar o formato esperado do texto que representa a data e hora.You must specify the expected format of the text representing a date and time.
  2. Você pode especificar a cultura para o formato de data hora.You may specify the culture for the format of a date time.
  3. Você pode especificar como os componentes ausentes na representação de texto serão definidos na data e hora.You may specify how missing components in the text representation are set in the date and time.

Os métodos Parse e TryParse convertem muitas representações comuns de data e hora.The Parse and TryParse methods convert many common representations of a date and time. Os métodos ParseExact e TryParseExact convertem uma representação em cadeia de caracteres que cumpra o padrão especificado por uma cadeia de caracteres de formato de data e hora.The ParseExact and TryParseExact methods convert a string representation that conforms to the pattern specified by a date and time format string. (Consulte os artigos sobre cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas para maiores detalhes).(See the articles on standard date and time format strings and custom date and time format strings for details.)

O objeto DateTimeFormatInfo atual fornece mais controle sobre como o texto deve ser interpretado como data e hora.The current DateTimeFormatInfo object provides more control over how text should be interpreted as a date and time. As propriedades de um DateTimeFormatInfo descrevem os separadores de data e hora e os nomes dos meses, dias e eras, bem como o formato das designações "AM" e "PM".Properties of a DateTimeFormatInfo describe the date and time separators, and the names of months, days, and eras, and the format for the "AM" and "PM" designations. A cultura do thread atual fornece um DateTimeFormatInfo que representa a cultura atual.The current thread culture provides a DateTimeFormatInfo that represents the current culture. Se você quer uma cultura específica ou configurações personalizadas, é necessário especificar o parâmetro IFormatProvider de um método de análise.If you want a specific culture or custom settings, you specify the IFormatProvider parameter of a parsing method. Para o parâmetro IFormatProvider, especifique um objeto CultureInfo, o qual representa uma cultura ou um objeto DateTimeFormatInfo.For the IFormatProvider parameter, specify a CultureInfo object, which represents a culture, or a DateTimeFormatInfo object.

O texto que representa uma data ou hora pode ter algumas informações ausentes.The text representing a date or time may be missing some information. Por exemplo, a maioria das pessoas supõe que a data "12 de março" representa o ano atual.For example, most people would assume the date "March 12" represents the current year. Da mesma forma, "Março de 2018" representa o mês de março do ano 2018.Similarly, "March 2018" represents the month of March in the year 2018. O texto que representa a hora geralmente só inclui horas, minutos e uma designação de AM/PM.Text representing time often does only includes hours, minutes, and an AM/PM designation. Os métodos de análise lidam com essas informações ausentes usando alguns padrões razoáveis:Parsing methods handle this missing information by using reasonable defaults:

  • Quando apenas a hora estiver presente, a parte de data usará a data atual.When only the time is present, the date portion uses the current date.
  • Quando houver apenas uma data, a parte das horas será meia-noite.When only the date is present, the time portion is midnight.
  • Quando o ano não for especificado em uma data, o ano atual será usado.When the year isn't specified in a date, the current year is used.
  • Quando o dia do mês não for especificado, o primeiro dia do mês será usado.When the day of the month isn't specified, the first of the month is used.

Se a data estiver presente na cadeia de caracteres, ele deverá incluir o mês e, pelo menos, o dia ou o ano.If the date is present in the string, it must include the month and one of the day or year. Se a hora estiver presente, ela deverá incluir a hora e os minutos ou o designador AM/PM.If the time is present, it must include the hour, and either the minutes or the AM/PM designator.

Você pode especificar a constante NoCurrentDateDefault para substituir esses padrões.You can specify the NoCurrentDateDefault constant to override these defaults. Ao usar essa constante, as propriedades ausentes de ano, mês ou dia serão definidas com o valor 1.When you use that constant, any missing year, month, or day properties are set to the value 1. O último exemplo usando Parse demonstra esse comportamento.The last example using Parse demonstrates this behavior.

Além de um componente de data e hora, a representação de cadeia de caracteres de data e hora pode incluir um deslocamento que indique a diferença de tempo em relação ao UTC (Tempo Universal Coordenado).In addition to a date and a time component, the string representation of a date and time can include an offset that indicates how much the time differs from Coordinated Universal Time (UTC). Por exemplo, a cadeia de caracteres “2/14/2007 5:32:00 -7:00” define um horário sete horas antes do UTC.For example, the string "2/14/2007 5:32:00 -7:00" defines a time that is seven hours earlier than UTC. Se um deslocamento for omitido da representação de cadeia de caracteres de um horário, a análise retornará um DateTime do objeto com a propriedade Kind definida como DateTimeKind.Unspecified.If an offset is omitted from the string representation of a time, parsing returns a DateTime object with its Kind property set to DateTimeKind.Unspecified. Se um deslocamento for especificado, a análise retorna um objeto DateTime com a propriedade Kind definida como DateTimeKind.Local e seu valor ajustado de acordo com o fuso horário local do seu computador.If an offset is specified, parsing returns a DateTime object with its Kind property set to DateTimeKind.Local and its value adjusted to the local time zone of your machine. É possível modificar esse comportamento usando um valor DateTimeStyles com o método de análise.You can modify this behavior by using a DateTimeStyles value with the parsing method.

O provedor de formato também é usado para interpretar uma data numérica ambígua.The format provider is also used to interpret an ambiguous numeric date. Não está claro quais componentes da data representada pela cadeia de caracteres "02/03/04" são o mês, o dia e o ano.It is not clear which components of the date represented by the string "02/03/04" are the month, day, and year. Os componentes são interpretados de acordo com a ordem dos formatos de data semelhantes no provedor de formato.The components are interpreted according to the order of similar date formats in the format provider.

ParseParse

O exemplo a seguir ilustra o uso do método DateTime.Parse para converter uma string em um DateTime.The following example illustrates the use of the DateTime.Parse method to convert a string into a DateTime. Este exemplo usa a cultura associada com o thread atual.This example uses the culture associated with the current thread. Se o CultureInfo associado à cultura atual não puder analisar a cadeia de caracteres de entrada, um FormatException será gerado.If the CultureInfo associated with the current culture cannot parse the input string, a FormatException is thrown.

Dica

Todos os exemplos de C# neste artigo são executados no navegador.All the C# samples in this article run in your browser. Pressione o botão Executar para ver a saída.Press the Run button to see the output. Você também pode editá-los para experimentar como quiser.You can also edit them to experiment yourself.

Observação

Esses exemplos estão disponíveis no repositório de documentos do GitHub para C# e VB.These examples are available in the GitHub docs repo for both C# and VB. Ou você pode baixar o projeto como um arquivo zip para C# ou VB.Or you can download the project as a zipfile for C# or VB.

string dateInput = "Jan 1, 2009";
DateTime parsedDate = DateTime.Parse(dateInput);
Console.WriteLine(parsedDate);
// Displays the following output on a system whose culture is en-US:
//       1/1/2009 12:00:00 AM
Dim MyString As String = "Jan 1, 2009"
Dim MyDateTime As DateTime = DateTime.Parse(MyString)
Console.WriteLine(MyDateTime)
' Displays the following output on a system whose culture is en-US:
'       1/1/2009 12:00:00 AM

É possível definir explicitamente a cultura cujas convenções de formatação serão usadas ao analisar uma cadeia de caracteres.You can also explicitly define the culture whose formatting conventions are used when you parse a string. Você especifica um dos objetos DateTimeFormatInfo padrão retornados pela propriedade CultureInfo.DateTimeFormat.You specify one of the standard DateTimeFormatInfo objects returned by the CultureInfo.DateTimeFormat property. O exemplo seguir usa um provedor de formato para analisar uma cadeia de caracteres em alemão em um DateTime.The following example uses a format provider to parse a German string into a DateTime. Ele cria um CultureInfo que representa a cultura de-DE.It creates a CultureInfo representing the de-DE culture. Esse objeto CultureInfo garante o sucesso da análise dessa cadeia de caracteres específica.That CultureInfo object ensures successful parsing of this particular string. Isso impede qualquer configuração que está no CurrentCulture do CurrentThread.This precludes whatever setting is in the CurrentCulture of the CurrentThread.

CultureInfo MyCultureInfo = new CultureInfo("de-DE");
string MyString = "12 Juni 2008";
DateTime MyDateTime = DateTime.Parse(MyString, MyCultureInfo);
Console.WriteLine(MyDateTime);
// The example displays the following output:
//       6/12/2008 12:00:00 AM
Dim MyCultureInfo As CultureInfo = New CultureInfo("de-DE")
Dim MyString As String = "12 Juni 2008"
Dim MyDateTime As DateTime = DateTime.Parse(MyString, MyCultureInfo)
Console.WriteLine(MyDateTime)
' The example displays the following output:
'       6/12/2008 12:00:00 AM

No entanto, apesar de ser possível usar sobrecargas do método Parse para especificar provedores de formato personalizados, o método não é compatível com a análise de formatos não padrão.However, although you can use overloads of the Parse method to specify custom format providers, the method does not support parsing non-standard formats. Para analisar data e hora expressadas em um formato não padrão, use o método ParseExact.To parse a date and time expressed in a non-standard format, use the ParseExact method instead.

O exemplo a seguir usa a enumeração DateTimeStyles para especificar que as informações de data e hora atuais não devem ser adicionadas ao DateTime nos campos não especificados.The following example uses the DateTimeStyles enumeration to specify that the current date and time information should not be added to the DateTime for unspecified fields.

CultureInfo MyCultureInfo = new CultureInfo("de-DE");
string MyString = "12 Juni 2008";
DateTime MyDateTime = DateTime.Parse(MyString, MyCultureInfo,
                                     DateTimeStyles.NoCurrentDateDefault);
Console.WriteLine(MyDateTime);
// The example displays the following output if the current culture is en-US:
//      6/12/2008 12:00:00 AM
Dim MyCultureInfo As CultureInfo = New CultureInfo("de-DE")
Dim MyString As String = "12 Juni 2008"
Dim MyDateTime As DateTime = DateTime.Parse(MyString, MyCultureInfo,
                           DateTimeStyles.NoCurrentDateDefault)
Console.WriteLine(MyDateTime)
' The example displays the following output if the current culture is en-US:
'       6/12/2008 12:00:00 AM

ParseExactParseExact

O método DateTime.ParseExact converte uma cadeia de caracteres em um objeto DateTime se ele estiver em conformidade com um dos padrões da cadeia de caracteres especificada.The DateTime.ParseExact method converts a string to a DateTime object if it conforms to one of the specified string patterns. Quando uma cadeia de caracteres que não é de uma das formas especificadas é passada para esse método, é lançada uma FormatException.When a string that is not one of the forms specified is passed to this method, a FormatException is thrown. Você pode especificar um dos especificadores de formato de data e hora padrão ou uma combinação dos especificadores de formato personalizados.You can specify one of the standard date and time format specifiers or a combination of the custom format specifiers. Usando os especificadores de formato personalizados, é possível construir uma cadeia de caracteres de reconhecimento personalizada.Using the custom format specifiers, it is possible for you to construct a custom recognition string. Para ver uma explicação dos especificadores, consulte os tópicos cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas.For an explanation of the specifiers, see the topics on standard date and time format strings and custom date and time format strings.

No exemplo a seguir, o método DateTime.ParseExact recebe um objeto de cadeia de caracteres para analisar, seguido por um especificador de formato, seguido por um objeto CultureInfo.In the following example, the DateTime.ParseExact method is passed a string object to parse, followed by a format specifier, followed by a CultureInfo object. Esse método ParseExact só consegue analisar cadeias de caracteres que seguem o padrão de data por extenso na cultura en-US.This ParseExact method can only parse strings that follow the long date pattern in the en-US culture.

CultureInfo MyCultureInfo = new CultureInfo("en-US");
string[] MyString = { " Friday, April 10, 2009", "Friday, April 10, 2009" };
foreach (string dateString in MyString)
{
    try
    {
        DateTime MyDateTime = DateTime.ParseExact(dateString, "D", MyCultureInfo);
        Console.WriteLine(MyDateTime);
    }
    catch (FormatException)
    {
        Console.WriteLine("Unable to parse '{0}'", dateString);
    }
}
// The example displays the following output:
//       Unable to parse ' Friday, April 10, 2009'
//       4/10/2009 12:00:00 AM
Dim MyCultureInfo As CultureInfo = New CultureInfo("en-US")
Dim MyString() As String = {" Friday, April 10, 2009", "Friday, April 10, 2009"}
For Each dateString As String In MyString
    Try
        Dim MyDateTime As DateTime = DateTime.ParseExact(dateString, "D",
                                                     MyCultureInfo)
        Console.WriteLine(MyDateTime)
    Catch e As FormatException
        Console.WriteLine("Unable to parse '{0}'", dateString)
    End Try
Next
' The example displays the following output:
'       Unable to parse ' Friday, April 10, 2009'
'       4/10/2009 12:00:00 AM

Cada sobrecarga dos métodos Parse e ParseExact também tem um parâmetro IFormatProvider que oferece informações específicas da cultura sobre a formatação da cadeia de caracteres.Each overload of the Parse and ParseExact methods also has an IFormatProvider parameter that provides culture-specific information about the formatting of the string. Esse objeto IFormatProvider é um objeto CultureInfo que representa uma cultura padrão ou um objeto DateTimeFormatInfo que é retornado pela propriedade CultureInfo.DateTimeFormat.This IFormatProvider object is a CultureInfo object that represents a standard culture or a DateTimeFormatInfo object that is returned by the CultureInfo.DateTimeFormat property. O ParseExact também usa uma cadeia de caracteres adicional ou um argumento de matriz de cadeia de caracteres que define um ou mais formatos de data e hora personalizados.ParseExact also uses an additional string or string array argument that defines one or more custom date and time formats.

Consulte tambémSee also