CA1303: Não passe literais como parâmetros localizados

Motivo

Um método passa uma cadeia de caracteres literal como parâmetro para um construtor ou método .NET, sendo que essa cadeia de caracteres deve ser localizável.

Esse aviso é gerado quando uma cadeia de caracteres literal é passada como um valor para um parâmetro ou propriedade e uma ou mais das seguintes situações é verdadeira:

• O LocalizableAttribute atributo do parâmetro ou propriedade é definido como true.

• A cadeia de caracteres literal é passada para o parâmetro string value ou string format de uma sobrecarga de método Console.Write ou Console.WriteLine.

• A regra CA1303 está configurada para usar a heurística de nomenclatura, e um parâmetro ou nome de propriedade contém a frase Text, Messageou Caption.

Por padrão, essa regra analisa toda a base de código, mas isso é configurável.

Descrição da regra

Os literais de cadeia de caracteres incorporados no código-fonte são difíceis de localizar.

Como corrigir violações

Para corrigir uma violação dessa regra, substitua o literal de cadeia de caracteres por uma cadeia de caracteres recuperada por meio de uma instância da classe ResourceManager.

Para métodos que não exigem cadeias de caracteres localizadas, você pode eliminar avisos desnecessários do CA1303 das seguintes maneiras:

• Se a opção heurística de nomenclatura estiver habilitada, renomeie o parâmetro ou a propriedade.
• Remova o LocalizableAttribute atributo no parâmetro ou propriedade ou defina-o como false ([Localizable(false)]).

Quando suprimir avisos

É seguro suprimir um aviso desta regra se uma das seguintes afirmações se aplicar:

• A biblioteca de códigos não será localizada.
• A cadeia de caracteres não é exposta ao usuário final ou a um desenvolvedor usando a biblioteca de códigos.

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 CA1303
// The code that's violating the rule is on this line.
#pragma warning restore CA1303

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

[*.{cs,vb}]
dotnet_diagnostic.CA1303.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
• Usar heurística de nomenclatura

Além disso, as seguintes opções relacionadas à análise de fluxo de dados se aplicam a essa regra:

• interprocedural_analysis_kind
• max_interprocedural_lambda_or_local_function_call_chain
• max_interprocedural_method_call_chain
• points_to_analysis_kind
• copy_analysis
• contagem_de_iterações_suficiente_para_algoritmo_KDF_fraco

Você pode configurar essas opções apenas para esta regra, para todas as regras às quais elas se aplicam ou para todas as regras nesta categoria (Globalização) às quais elas se aplicam. 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 definindo a opção excluded_symbol_names. 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 definindo a opção excluded_type_names_with_derived_types. 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 opcional T:.

Exemplos:

Usar heurística de nomenclatura

Você pode configurar se os parâmetros ou nomes de propriedades que contenham Text, Messageou Caption acionarão essa regra.

dotnet_code_quality.CA1303.use_naming_heuristic = true

Exemplo

O exemplo a seguir mostra um método que escreve no console quando qualquer um dos seus dois argumentos está fora do intervalo. Para a verificação do argumento hour, uma string literal é passada para Console.WriteLine, o que viola essa regra. Para a verificação de minute argumento, uma cadeia de caracteres recuperada por meio de um ResourceManager é passada para Console.WriteLine, que satisfaz a regra.

<Assembly: System.Resources.NeutralResourcesLanguageAttribute("en-US")>
Namespace GlobalizationLibrary

    Public Class DoNotPassLiterals

        Dim stringManager As System.Resources.ResourceManager

        Sub New()
            stringManager = New System.Resources.ResourceManager(
                "en-US", System.Reflection.Assembly.GetExecutingAssembly())
        End Sub

        Sub TimeMethod(hour As Integer, minute As Integer)

            If (hour < 0 Or hour > 23) Then
                'CA1303 fires because a literal string
                'is passed as the 'value' parameter.
                Console.WriteLine("The valid range is 0 - 23.")
            End If

            If (minute < 0 Or minute > 59) Then
                Console.WriteLine(
                    stringManager.GetString("minuteOutOfRangeMessage",
                        System.Globalization.CultureInfo.CurrentUICulture))
            End If

        End Sub

    End Class

End Namespace

public class DoNotPassLiterals
{
    ResourceManager stringManager;
    public DoNotPassLiterals()
    {
        stringManager = new ResourceManager("en-US", Assembly.GetExecutingAssembly());
    }

    public void TimeMethod(int hour, int minute)
    {
        if (hour < 0 || hour > 23)
        {
            // CA1303 fires because a literal string
            // is passed as the 'value' parameter.
            Console.WriteLine("The valid range is 0 - 23.");
        }

        if (minute < 0 || minute > 59)
        {
            Console.WriteLine(stringManager.GetString(
            "minuteOutOfRangeMessage", CultureInfo.CurrentUICulture));
        }
    }
}

Consulte também

• Recursos em aplicativos .NET
• Pedido da comunidade para mudança de comportamento