Compartilhar via

CA1304: Especificar CultureInfo

  • Artigo
Property Valor
ID da regra CA1304
Título Especificar CultureInfo
Categoria Globalização
Correção interruptiva ou sem interrupção Sem interrupção
Habilitado por padrão no .NET 8 Não

Causa

Um método ou um construtor chama um membro que tem uma sobrecarga que aceita um parâmetro System.Globalization.CultureInfo, e o método ou o construtor não chama a sobrecarga que utiliza o parâmetro CultureInfo. Essa regra ignora as chamadas aos seguintes métodos:

Você também pode configurar mais símbolos a serem excluídos por essa regra.

Descrição da regra

Quando um objeto CultureInfo ou System.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 à 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, ou seja, 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.

Observação

CultureInfo.CurrentUICulture é utilizado apenas para recuperar recursos localizados ao usar uma instância da classe System.Resources.ResourceManager.

Como corrigir violações

Para corrigir uma violação dessa regra, use a sobrecarga que usa um argumento CultureInfo.

Quando suprimir avisos

É seguro suprimir um aviso dessa regra quando tiver certeza de que a cultura 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 CA1304
// The code that's violating the rule is on this line.
#pragma warning restore CA1304

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.CA1304.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.

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:

Valor de Opção Resumo
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Corresponde a todos os símbolos nomeados MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Corresponde a todos os símbolos nomeados MyType1 ou MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Corresponde ao método MyMethod específico com a assinatura totalmente qualificada especificada.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Corresponde aos métodos MyMethod1 e MyMethod2 específico com as assinaturas respectivas totalmente qualificadas.

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:

Valor de Opção Resumo
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Corresponde a todos os tipos nomeados MyType e todos os seus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Corresponde a todos os tipos nomeados MyType1 ou MyType2 e todos os seus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Corresponde a um tipo MyType específico com determinado nome totalmente qualificado e todos os seus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Corresponde a um tipo MyType1 e MyType2 específico com determinado nome totalmente qualificado e todos os seus tipos derivados.

Exemplo mostrando como corrigir violações

No exemplo a seguir, BadMethod causa duas violações dessa regra. GoodMethod corrige a primeira violação passando a cultura invariável para String.Compare e corrige a segunda violação passando a cultura atual para String.ToLower, porque string3 é exibida para o usuário.

public class CultureInfoTest
{
    public void BadMethod(String string1, String string2, String string3)
    {
        if (string.Compare(string1, string2, false) == 0)
        {
            Console.WriteLine(string3.ToLower());
        }
    }

    public void GoodMethod(String string1, String string2, String string3)
    {
        if (string.Compare(string1, string2, false,
                          CultureInfo.InvariantCulture) == 0)
        {
            Console.WriteLine(string3.ToLower(CultureInfo.CurrentCulture));
        }
    }
}

Exemplo mostrando a saída formatada

O exemplo a seguir mostra o efeito da cultura atual no IFormatProvider padrão que é selecionado pelo tipo DateTime.

public class IFormatProviderTest
{
    public static void Main1304()
    {
        string dt = "6/4/1900 12:15:12";

        // The default behavior of DateTime.Parse is to use
        // the current culture.

        // Violates rule: SpecifyIFormatProvider.
        DateTime myDateTime = DateTime.Parse(dt);
        Console.WriteLine(myDateTime);

        // Change the current culture to the French culture,
        // and parsing the same string yields a different value.

        Thread.CurrentThread.CurrentCulture = new CultureInfo("Fr-fr", true);
        myDateTime = DateTime.Parse(dt);

        Console.WriteLine(myDateTime);
    }
}

Esse exemplo gera a saída a seguir:

6/4/1900 12:15:12 PM
06/04/1900 12:15:12

Confira também