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

Artigo
09/06/2023

Property	valor
ID da regra	CA2241
Título	Fornecer argumentos corretos para métodos de formatação
Categoria	Utilização
A correção está quebrando ou não quebrando	Sem quebra
Habilitado por padrão no .NET 9	Como sugestão

Motivo

O format argumento string passado para um método como WriteLine, Writeou System.String.Format não contém um item de formato que corresponde a cada argumento de objeto, ou vice-versa.

Por padrão, essa regra analisa apenas chamadas para os três métodos mencionados anteriormente, mas isso é configurável.

Descrição da regra

Os argumentos para métodos como WriteLine, Writee Format consistem em uma cadeia de caracteres de formato seguida por várias System.Object instâncias. A cadeia de caracteres de formato consiste em texto e itens de formato incorporado do formulário {index[,alignment][:formatString]}. 'index' é um inteiro baseado em zero que indica qual dos objetos deve 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, um System.FormatException é lançado 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 desta regra.

Configurar código para análise

Use as opções a seguir para configurar métodos adicionais para executar esta regra.

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

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

Você pode configurar nomes de métodos de formatação de cadeia de caracteres adicionais que devem ser analisados por esta regra. Por exemplo, para especificar todos os métodos nomeados MyFormat como métodos de formatação de cadeia de caracteres, você pode adicionar o seguinte par chave-valor a um arquivo .editorconfig em seu 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 nome do método (inclui todos os métodos 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 opcionalM:.

Exemplos:

Valor da opção	Resumo
`dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat`	Corresponde a todos os métodos nomeados `MyFormat` na compilação.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat1\|MyFormat2`	Corresponde a todos os métodos nomeados ou `MyFormat1` `MyFormat2` na compilação.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = NS.MyType.MyFormat(ParamType)`	Corresponde a um método `MyFormat` específico com uma determinada assinatura totalmente qualificada.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = NS1.MyType1.MyFormat1(ParamType)\|NS2.MyType2.MyFormat2(ParamType)`	Corresponde a métodos `MyFormat1` específicos e `MyFormat2` com a respetiva assinatura totalmente qualificada.

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

Em vez de especificar uma lista explícita de métodos adicionais de formatação de cadeia de caracteres, 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á desativada. Se a opção estiver habilitada, qualquer método que tenha um string format parâmetro seguido por um params object[] parâmetro 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));
    }
}

Partilhar via