Share via

CA1068:CancellationToken パラメーターは最後に指定する必要があります

  • [アーティクル]
プロパティ 値
ルール ID CA1068
Title CancellationToken パラメーターは最後に指定する必要があります
[カテゴリ] デザイン
修正が中断ありか中断なしか あり
.NET 8 では既定で有効 提案として

原因

メソッドに、最後に指定されていない、CancellationToken パラメーターがあります。

既定で、このルールではコードベース全体を分析しますが、これは構成可能です。

規則の説明

通常、実行時間の長い操作や、非同期操作を実行する取り消し可能なメソッドでは、キャンセル トークン パラメーターを取ります。 各キャンセル トークンには、トークンを作成し、それをキャンセルできる計算に使用する CancellationTokenSource があります。 一般的な方法は、呼び出し元から呼び出し先にキャンセル トークンを渡す、メソッド呼び出しの長いチェーンを用意します。 したがって、キャンセル可能な計算の一部に含まれる多数のメソッドが、キャンセル トークン パラメーターを持つことになります。 ただし、キャンセル トークン自体は、通常、これらのメソッドの大部分の中心機能には関連していません。 API を設計する場合、このようなパラメーターは、一覧の最後のパラメーターとして指定することをお勧めします。

特殊なケース

規則 CA1068 は、次の特殊な場合には起動されません。

  • メソッドの省略可能でないキャンセル トークン パラメーターの後に、省略可能なパラメーター (Visual Basic で省略可能) が 1 つ以上ある場合。 コンパイラでは、すべての省略可能でないパラメーターの後に、すべての省略可能なパラメーターを定義する必要があります。
  • メソッドのキャンセル トークン パラメーターの後に、ref または out パラメーター (Visual Basic で ByRef) が 1 つ以上ある場合。 ref または out パラメーターは、通常メソッドの出力値を示すため、一般的に一覧の末尾に配置します。

違反の修正方法

メソッド シグネチャを変更して、キャンセル トークン パラメーターを一覧の末尾に移動します。 たとえば、次の 2 つのコード スニペットは、規則違反とその修正方法を示しています。

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

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

どのようなときに警告を抑制するか

メソッドが、既に出荷済みライブラリの、外部から参照可能なパブリック API である場合、ライブラリ使用者に対する破壊的変更を回避するために、この規則の警告を表示しないようにしても問題ありません。

警告を抑制する

単一の違反を抑制するだけの場合は、ソース ファイルにプリプロセッサ ディレクティブを追加して無効にしてから、規則をもう一度有効にします。

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

ファイル、フォルダー、またはプロジェクトの規則を無効にするには、構成ファイルでその重要度を none に設定します。

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

詳細については、「コード分析の警告を抑制する方法」を参照してください。

分析するコードを構成する

次のオプションを使用して、コードベースのどの部分に対してこの規則を実行するかを構成します。

これらのオプションを構成できる対象は、この規則だけ、それを適用するすべての規則、それを適用するこのカテゴリ (デザイン) のすべての規則のいずれかです。 詳細については、「コード品質規則の構成オプション」を参照してください。

特定の API サーフェイスを含める

ユーザー補助に基づいて、この規則を実行するコードベースの部分を構成できます。 たとえば、非パブリック API サーフェイスでのみ規則を実行するように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.api_surface = private, internal

特定のシンボルを除外する

型やメソッドなど、特定のシンボルを分析から除外することができます。 たとえば、MyType という名前の型のコードで規則を実行しないように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

オプションの値で使用できるシンボル名の形式 (| で区切ります):

  • シンボル名のみ (包含する型または名前空間に関係なく、その名前が指定されたすべてのシンボルが含まれます)。
  • そのシンボルのドキュメント ID 形式の完全修飾名。 各シンボル名には、メソッドには M:、型には T:、名前空間には N: のように、シンボルの種類のプレフィックスが必要です。
  • コンストラクターには .ctor、静的コンストラクターには .cctor。

例 :

オプション値 まとめ
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType MyType という名前のすべてのシンボルを検索します。
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 MyType1 または MyType2 という名前のすべてのシンボルを検索します。
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) 指定された完全修飾シグネチャを持つ特定のメソッド MyMethod を検索します。
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) それぞれの完全修飾シグネチャを持つ特定のメソッド MyMethod1 または MyMethod2 を検索します。

特定の型とその派生型を除外する

分析から特定の型とその派生型を除外できます。 たとえば、MyType という名前の型のメソッドとその派生型で規則を実行しないように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

オプションの値で使用できるシンボル名の形式 (| で区切ります):

  • 型の名前のみ (包含する型または名前空間に関係なく、その名前が指定されたすべての型が含まれます)。
  • そのシンボルのドキュメント ID 形式の完全修飾名 (オプションで T: プレフィックスも使用可)。

例 :

オプション値 まとめ
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType MyType という名前のすべての型と、そのすべての派生型を検索します。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 MyType1 または MyType2 という名前のすべての型と、そのすべての派生型を検索します。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType 指定された完全修飾名を持つ特定の型 MyType と、そのすべての派生型を検索します。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 それぞれの完全修飾名を持つ特定の型 MyType1 または MyType2 と、そのすべての派生型を検索します。

関連項目