CA1305: Especificar IFormatProvider

Causa

Uma chamada é feita para um método com uma sobrecarga que aceita um argumento System.IFormatProvider e essa sobrecarga não é chamada.

Essa regra ignora chamadas para métodos .NET documentados como ignorando o parâmetro IFormatProvider. A regra também ignora os seguintes métodos:

• Activator.CreateInstance
• ResourceManager.GetObject
• ResourceManager.GetString
• Boolean.ToString
• Char.ToString
• Guid.ToString

Descrição da regra

Quando um objeto System.Globalization.CultureInfo ou IFormatProvider não for fornecido, o valor padrão fornecido pelo membro sobrecarregado poderá não ter o efeito desejado em todas as localidades. Além disso, os membros do .NET escolhem a cultura e a formatação padrão com base em suposições que poderão ser incorretas para o código. Para garantir que o código funcione conforme o esperado nos cenários, será necessário fornecer as informações específicas da cultura de acordo com as seguintes diretrizes:

• Se o valor for exibido ao usuário, use a cultura atual. Consulte CultureInfo.CurrentCulture.

• Se o valor for armazenado e acessado por software (persistente em um arquivo ou banco de dados), use a cultura invariável. Consulte CultureInfo.InvariantCulture.

• Se você não souber o destino do valor, solicite ao provedor ou consumidor de dados que especifique a cultura.

Mesmo que o comportamento padrão do membro sobrecarregado seja apropriado às suas necessidades, é recomendável chamar explicitamente a sobrecarga específica à cultura para que o código seja autodocumentado e de fácil manutenção.

Como corrigir violações

Para corrigir uma violação dessa regra, use a sobrecarga que usa um argumento IFormatProvider. Ou, para usar a cultura invariável, use uma cadeia de caracteres interpolada em C# e passe-a para String.Create(IFormatProvider, DefaultInterpolatedStringHandler) junto com CultureInfo.InvariantCulture, por exemplo:

string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}.{build}.{revision}");

Quando suprimir avisos

É seguro suprimir um aviso dessa regra quando tiver certeza de que o formato padrão é a escolha correta e onde a manutenção do código não é uma prioridade de desenvolvimento importante.

Suprimir um aviso

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar a regra.

#pragma warning disable CA1305
// The code that's violating the rule is on this line.
#pragma warning restore CA1305

Para desabilitar a regra em um arquivo, uma pasta ou um projeto, defina a severidade como none no arquivo de configuração.

[*.{cs,vb}]
dotnet_diagnostic.CA1305.severity = none

Para obter mais informações, confira Como suprimir avisos de análise de código.

Configurar código para analisar

Use as opções a seguir para configurar em quais partes da base de código essa regra deve ser executada.

• Excluir símbolos específicos
• Excluir tipos específicos e seus tipos derivados

Você pode configurar essas opções apenas para essa regra, para todas as regras às quais ela se aplica ou para todas as regras nessa categoria (Globalização) às quais ela se aplica. Para saber mais, confira Opções de configuração de regra de qualidade de código.

Excluir símbolos específicos

Você pode excluir da análise símbolos específicos, como tipos e métodos. Por exemplo, para especificar que a regra não deve ser executada em nenhum código dentro de tipos nomeados MyType, adicione o seguinte par chave-valor a um arquivo .editorconfig no seu projeto:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formatos de nome de símbolo permitidos no valor da opção (separados por |):

• Somente nome do símbolo (inclui todos os símbolos com o nome, independentemente do tipo ou namespace que contém).
• Nomes totalmente qualificados no formato de ID de documentação do símbolo. Cada nome de símbolo requer um prefixo do tipo símbolo, como M: para métodos, T: para tipos e N: para namespaces.
• .ctor para construtores e .cctor para construtores estáticos.

Exemplos:

Excluir tipos específicos e seus tipos derivados

Você pode excluir tipos específicos e seus tipos derivados da análise. Por exemplo, para especificar que a regra não deve ser executada em nenhum método dentro de tipos nomeados MyType e seus tipos derivados, adicione o seguinte par chave-valor a um arquivo .editorconfig no seu projeto:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formatos de nome de símbolo permitidos no valor da opção (separados por |):

• Somente nome do tipo (inclui todos os tipos com o nome, independentemente do tipo ou namespace que contém).
• Nomes totalmente qualificados no formato de ID de documentação do símbolo, com um prefixo opcional T:.

Exemplos:

Exemplo

No código a seguir, a cadeia de caracteres example1 viola a regra CA1305. A cadeia de caracteres example2 satisfaz a regra CA1305 passando CultureInfo.CurrentCulture, que implementa IFormatProvider, para String.Format(IFormatProvider, String, Object). A cadeia de caracteres example3 satisfaz a regra CA1305 passando uma cadeia de caracteres interpolada para String.Create(IFormatProvider, DefaultInterpolatedStringHandler) junto com CultureInfo.InvariantCulture.

string name = "Georgette";

// Violates CA1305
string example1 = string.Format("Hello {0}", name);

// Satisfies CA1305
string example2 = string.Format(CultureInfo.CurrentCulture, "Hello {0}", name);

// Satisfies CA1305
string example3 = string.Create(CultureInfo.InvariantCulture, $"Hello {name}");

Regras relacionadas

• CA1304: Especificar CultureInfo

Confira também

• Usar a classe CultureInfo