次の方法で共有

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

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

原因

メソッドに、最後に指定されていない、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_surface オプションを設定することで、アクセスの可否に基づいてこのルールを実行するコードベースの部分を構成できます。 たとえば、非パブリック API サーフェイスでのみ規則を実行するように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.api_surface = private, internal

メモ

XXXX の CAXXXX 部分を該当するルールの ID に置き換えます。

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

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

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

メモ

XXXX の CAXXXX 部分を該当するルールの ID に置き換えます。

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

  • シンボル名のみ (包含する型または名前空間に関係なく、その名前が指定されたすべてのシンボルが含まれます)。
  • そのシンボルのドキュメント 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 を検索します。

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

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

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

メモ

XXXX の CAXXXX 部分を該当するルールの ID に置き換えます。

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

  • 型の名前のみ (包含する型または名前空間に関係なく、その名前が指定されたすべての型が含まれます)。
  • そのシンボルのドキュメント 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 と、そのすべての派生型を検索します。

関連項目

  • Last updated on