CA1305: Especificar IFormatProvider

Motivo

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

Esta regra ignora chamadas para métodos .NET documentados como ignorando o IFormatProvider parâmetro. 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 System.Globalization.CultureInfo objeto ou IFormatProvider não é fornecido, o valor padrão fornecido pelo membro sobrecarregado pode 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 podem não estar corretas para seu código. Para garantir que o código funcione conforme o esperado para seus cenários, você deve fornecer informações específicas da cultura de acordo com as seguintes diretrizes:

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

• Se o valor será armazenado e acessado por software (persistido para um arquivo ou banco de dados), use a cultura invariante. Consulte CultureInfo.InvariantCulture.

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

Mesmo que o comportamento padrão do membro sobrecarregado seja apropriado para suas necessidades, é melhor chamar explicitamente a sobrecarga específica da cultura para que seu código seja autodocumentável e mais facilmente mantido.

Como corrigir violações

Para corrigir uma violação dessa regra, use a sobrecarga que usa um IFormatProvider argumento. Ou, para usar a cultura invariante, 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 é certo que o formato padrão é a escolha correta e quando a manutenção do código não é uma prioridade de desenvolvimento importante.

Suprimir um aviso

Se você quiser apenas suprimir uma única violação, adicione diretivas de pré-processador ao seu arquivo de origem para desativar e, em seguida, reativar 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 de um arquivo, pasta ou projeto, defina sua gravidade como none no arquivo de configuração.

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

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

Configurar código para análise

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

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

Você pode configurar essas opções apenas para esta regra, para todas as regras às quais ela se aplica ou para todas as regras nesta categoria (Globalização) às quais ela se aplica. Para obter mais informações, consulte Opções de configuração da regra de qualidade de código.

Excluir símbolos específicos

Você pode excluir símbolos específicos, como tipos e métodos, da análise. 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 em 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 o contém).
• Nomes totalmente qualificados no formato de ID de documentação do símbolo. Cada nome de símbolo requer um prefixo de tipo de 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 em 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 o contém).
• Nomes totalmente qualificados no formato de ID de documentação do símbolo, com um prefixo opcionalT:.

Exemplos:

Exemplo

No código a seguir, a cadeia de caracteres viola a example1 regra CA1305. A example2 cadeia de caracteres satisfaz a regra CA1305 passando CultureInfo.CurrentCulture, que implementa IFormatProvider, para String.Format(IFormatProvider, String, Object). A example3 cadeia de caracteres 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 conexas

• CA1304: Especificar CultureInfo

Consulte também

• Use a CultureInfo classe