CA2241: Fornecer argumentos corretos para métodos de formatação

Artigo
11/15/2023

Property	Valor
ID da regra	CA2241
Título	Fornecer argumentos corretos para métodos de formatação
Categoria	Usage
Correção interruptiva ou sem interrupção	Sem interrupção
Habilitado por padrão no .NET 9	Como sugestão

Causa

O argumento de cadeia de caracteres format foi transmitido para um método como WriteLine, Write ou System.String.Format não contém um item de formato que corresponda a cada argumento do objeto ou vice-versa.

Por padrão, essa regra só analisa as chamadas aos três métodos mencionados anteriormente, mas isso é configurável.

Descrição da regra

Os argumentos para métodos como WriteLine, Write e Format consistem em uma cadeia de caracteres de formato seguida de várias instâncias de System.Object. A cadeia de caracteres de formato consiste em itens de texto e formato inserido do formato {index[,alignment][:formatString]}. 'index' é um inteiro baseado em zero que indica qual dos objetos será formatado. Se um objeto não tiver um índice correspondente na cadeia de caracteres de formato, o objeto será ignorado. Se o objeto especificado por 'index' não existir, uma System.FormatException será gerada em tempo de execução.

Como corrigir violações

Para corrigir uma violação dessa regra, forneça um item de formato para cada argumento de objeto e forneça um argumento de objeto para cada item de formato.

Quando suprimir avisos

Não suprima um aviso nessa regra.

Configurar código para analisar

Use as opções a seguir para configurar métodos adicionais nos quais essa regra será executada.

Métodos adicionais de formatação de cadeia de caracteres
Determinar métodos de formatação de cadeia de caracteres adicionais automaticamente

Métodos de formatação de cadeia de caracteres adicionais

Você pode configurar nomes de métodos de formatação de cadeia de caracteres adicionais que devem ser analisados por essa regra. Por exemplo, para especificar todos os métodos chamados MyFormat como métodos de formatação de cadeia de caracteres, adicione o seguinte par chave-valor a um arquivo .editorconfig no projeto:

dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat

Formatos de nome de método permitidos no valor da opção (separados por |):

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

Exemplos:

Valor de Opção	Resumo
`dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat`	Corresponde a todos os métodos chamados `MyFormat` na compilação.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat1\|MyFormat2`	Corresponde a todos os métodos chamados `MyFormat1` ou `MyFormat2` na compilação.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = NS.MyType.MyFormat(ParamType)`	Corresponde ao método `MyFormat` específico com uma assinatura totalmente qualificada especificada.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = NS1.MyType1.MyFormat1(ParamType)\|NS2.MyType2.MyFormat2(ParamType)`	Corresponde aos métodos `MyFormat1` e `MyFormat2` específicos com as respectivas assinaturas totalmente qualificadas.

Determinar métodos de formatação de cadeia de caracteres adicionais automaticamente

Em vez de especificar uma lista explícita de métodos de formatação de cadeia de caracteres adicionais, você pode configurar o analisador para tentar determinar automaticamente o método de formatação de cadeia de caracteres. Por padrão, essa opção está desabilitada. Se a opção estiver habilitada, qualquer método que tenha um parâmetro string format seguido de um parâmetro params object[] será considerado um método de formatação de cadeia de caracteres:

dotnet_code_quality.CA2241.try_determine_additional_string_formatting_methods_automatically = true

Exemplo

O exemplo a seguir mostra duas violações da regra.

Imports System

Namespace ca2241

    Class CallsStringFormat

        Sub CallFormat()

            Dim file As String = "file name"
            Dim errors As Integer = 13

            ' Violates the rule.
            Console.WriteLine(String.Format("{0}", file, errors))

            Console.WriteLine(String.Format("{0}: {1}", file, errors))

            ' Violates the rule and generates a FormatException at runtime.
            Console.WriteLine(String.Format("{0}: {1}, {2}", file, errors))

        End Sub

    End Class

End Namespace

class CallsStringFormat
{
    void CallFormat()
    {
        string file = "file name";
        int errors = 13;

        // Violates the rule.
        Console.WriteLine(string.Format("{0}", file, errors));

        Console.WriteLine(string.Format("{0}: {1}", file, errors));

        // Violates the rule and generates a FormatException at runtime.
        Console.WriteLine(string.Format("{0}: {1}, {2}", file, errors));
    }
}

Compartilhar via