CA1068: Los parámetros CancellationToken deben aparecer en último lugar

  • Artículo
Propiedad Value
Identificador de la regla CA1068
Título Los parámetros CancellationToken deben aparecer en último lugar
Categoría Diseño
La corrección es problemática o no problemática Problemático
Habilitado de forma predeterminada en .NET 8 Como sugerencia

Causa

Un método tiene un parámetro CancellationToken que no es el último parámetro.

De forma predeterminada, esta regla analiza todo el código base, pero esto es configurable.

Descripción de la regla

Los métodos que realizan operaciones de larga duración u operaciones asincrónicas y que se pueden cancelar suelen tomar un parámetro de token de cancelación. Cada token de cancelación tiene un objeto CancellationTokenSource que crea el token y lo usa para los cálculos cancelables. Es habitual tener una cadena larga de llamadas a métodos que pasan el token de cancelación de los llamadores a los destinatarios. Por lo tanto, un gran número de métodos que forman parte de un cálculo cancelable acaban teniendo un parámetro de token de cancelación. Aun así, el token de cancelación no suele ser importante para la funcionalidad básica de una mayoría de estos métodos. Se considera una buena práctica de diseño de API hacer que estos parámetros sean los últimos de la lista.

Casos especiales

La regla CA1068 no se activa en los siguientes casos especiales:

  • El método tiene uno o varios parámetros opcionales (Optional en Visual Basic) después de un parámetro de token de cancelación no opcional. El compilador requiere que todos los parámetros opcionales se definan después de todos los parámetros no opcionales.
  • El método tiene uno o varios parámetros ref o out (ByRef en Visual Basic) después de un parámetro de token de cancelación. Es habitual que los parámetros ref o out estén al final de la lista, ya que suelen indicar valores de salida para el método.

Cómo corregir infracciones

Cambie la firma del método para que mueva el parámetro de token de cancelación al final de la lista. Por ejemplo, en los dos fragmentos de código siguientes se muestra una infracción de la regla y cómo corregirla:

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

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

Cuándo suprimir las advertencias

Si el método es una API pública externamente visible que ya forma parte de una biblioteca enviada, es seguro suprimir una advertencia de esta regla a fin de evitar un cambio importante para los consumidores de la biblioteca.

Supresión de una advertencia

Si solo quiere suprimir una única infracción, agregue directivas de preprocesador al archivo de origen para deshabilitar y volver a habilitar la regla.

#pragma warning disable CA1068
// The code that's violating the rule is on this line.
#pragma warning restore CA1068

Para deshabilitar la regla de un archivo, una carpeta o un proyecto, establezca su gravedad en none del archivo de configuración.

[*.{cs,vb}]
dotnet_diagnostic.CA1068.severity = none

Para obtener más información, consulte Procedimiento para suprimir advertencias de análisis de código.

Configuración del código para analizar

Use las opciones siguientes para configurar en qué partes del código base se va a ejecutar esta regla.

Puede configurar estas opciones solo para esta regla, para todas las reglas a las que se aplica o para todas las reglas de esta categoría (Diseño) a las que se aplica. Para más información, vea Opciones de configuración de reglas de calidad de código.

Incluir superficies de API específicas

Puede configurar en qué partes del código base ejecutar esta regla, en función de su accesibilidad. Por ejemplo, para especificar que la regla solo se debe ejecutar en la superficie de API no públicas, agregue el siguiente par clave-valor a un archivo .editorconfig en el proyecto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exclusión de símbolos específicos

Puede excluir símbolos específicos, como tipos y métodos, del análisis. Por ejemplo, para especificar que la regla no se debe ejecutar en ningún código dentro de los tipos con el nombre MyType, agregue el siguiente par clave-valor a un archivo .editorconfig en el proyecto:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formatos de nombre de símbolo permitidos en el valor de opción (separados por |):

  • Solo nombre de símbolo (incluye todos los símbolos con el nombre, con independencia del tipo contenedor o el espacio de nombres).
  • Nombres completos en el formato de id. de documentación del símbolo. Cada nombre de símbolo necesita un prefijo de tipo símbolo, como M: para los métodos, T: para los tipos y N: para los espacios de nombres.
  • .ctor para los constructores y .cctor para los constructores estáticos.

Ejemplos:

Valor de la opción Resumen
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Coincide con todos los símbolos denominados MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Coincide con todos los símbolos denominados MyType1 o MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Coincide con un método MyMethod concreto con la signatura completa especificada.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Coincide con los métodos MyMethod1 y MyMethod2 concretos con las signaturas completas especificadas.

Exclusión de tipos específicos y sus tipos derivados

Puede excluir tipos específicos y sus tipos derivados del análisis. Por ejemplo, para especificar que la regla no se debe ejecutar en ningún método dentro de los tipos con el nombre MyType y sus tipos derivados, agregue el siguiente par clave-valor a un archivo .editorconfig en el proyecto:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formatos de nombre de símbolo permitidos en el valor de opción (separados por |):

  • Solo nombre de tipo (incluye todos los tipos con el nombre, con independencia del tipo contenedor o el espacio de nombres).
  • Nombres completos en el formato de identificador de documentación del símbolo, con un prefijo T: opcional.

Ejemplos:

Valor de la opción Resumen
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Coincide con todos los tipos denominados MyType y todos sus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Coincide con todos los tipos denominados MyType1 o MyType2, y todos sus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Coincide con un tipo MyType específico con el nombre completo dado y todos sus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Coincide con los tipos MyType1 y MyType2 específicos con los correspondientes nombres completos y todos sus tipos derivados.

Consulte también