Partilhar via

CA1068: Os parâmetros CancellationToken devem vir por último

  • Artigo
Property valor
ID da regra CA1068
Título Os parâmetros CancellationToken devem vir por último
Categoria Desenho
A correção está quebrando ou não quebrando Quebrando
Habilitado por padrão no .NET 9 Como sugestão

Motivo

Um método tem um CancellationToken parâmetro que não é o último parâmetro.

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

Descrição da regra

Os métodos que executam operações de longa duração ou operações assíncronas e são canceláveis normalmente usam um parâmetro de token de cancelamento. Cada token de cancelamento tem um CancellationTokenSource que cria o token e o usa para cálculos canceláveis. É prática comum ter uma longa cadeia de chamadas de método que passam em torno do token de cancelamento dos chamadores para os chamados. Assim, um grande número de métodos que participam de um cálculo cancelável acabam tendo um parâmetro de token de cancelamento. No entanto, o token de cancelamento em si geralmente não é relevante para a funcionalidade principal da maioria desses métodos. É considerado uma boa prática de design de API ter tais parâmetros como o último parâmetro na lista.

Casos especiais

A regra CA1068 não é acionada nos seguintes casos especiais:

  • O método tem um ou mais parâmetros opcionais (Optional no Visual Basic) seguindo um parâmetro de token de cancelamento não opcional. O compilador requer que todos os parâmetros opcionais sejam definidos após todos os parâmetros não opcionais.
  • O método tem um ou mais parâmetros ref ou out (ByRef no Visual Basic) seguindo um parâmetro de token de cancelamento. É prática comum ter ref ou out parâmetros estar no final da lista, porque eles geralmente indicam valores de saída para o método.

Como corrigir violações

Altere a assinatura do método para mover o parâmetro do token de cancelamento para o final da lista. Por exemplo, os dois trechos de código a seguir mostram uma violação da regra e como corrigi-la:

// Violates CA1068
public void LongRunningOperation(CancellationToken token, string usefulParameter)
{
    ...
}

// Does not violate CA1068
public void LongRunningOperation(string usefulParameter, CancellationToken token)
{
    ...
}

Quando suprimir avisos

Se o método for uma API pública visível externamente que já faz parte de uma biblioteca enviada, é seguro suprimir um aviso dessa regra para evitar uma alteração significativa para os consumidores da biblioteca.

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

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

[*.{cs,vb}]
dotnet_diagnostic.CA1068.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.

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 (Design) às quais ela se aplica. Para obter mais informações, consulte Opções de configuração da regra de qualidade de código.

Incluir superfícies de API específicas

Você pode configurar em quais partes da sua base de código executar essa regra, com base em sua acessibilidade. Por exemplo, para especificar que a regra deve ser executada somente na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

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:

Valor da opção Resumo
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Corresponde a todos os símbolos denominados MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Corresponde a todos os símbolos denominados ou MyType1 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 a métodos MyMethod1 específicos e MyMethod2 com as respetivas assinaturas 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 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:

Valor da 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 ou MyType1 e MyType2 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 um 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 tipos MyType1 específicos e MyType2 com os respetivos nomes totalmente qualificados, e todos os seus tipos derivados.

Consulte também