CodeGym /コース /C# SELF /操作のキャンセル: CancellationToken

操作のキャンセル: CancellationToken

C# SELF
レベル 60, レッスン 4
使用可能

1. CancellationToken の紹介

状況を想像してみてください: 長時間かかるファイルのダウンロードを始めたけど、後で通信量が気になってやっぱり止めたいとか。あるいはユーザーが計算を始めたけど途中で不要になった。ユーザーは 「キャンセル」 を押して終了を待ちたくない。モダンなアプリは応答性が必要なので、いつでも停止シグナルを渡して非同期操作を正しく中断できる必要があります。

そのために .NET にはキャンセル用のインフラが用意されており、それが CancellationToken です。

CancellationToken(直訳すると「キャンセルトークン」)は、長時間実行される操作に渡す特別なオブジェクトです。いつでも CancellationTokenSource を通じてキャンセルを通知でき、操作側は定期的にトークンをチェック(例: IsCancellationRequested)して必要なら ThrowIfCancellationRequested() を呼んで正しく終了します。

仕組み(簡潔に)

  • まず CancellationTokenSource というオブジェクトがあり、トークンを生成してそれをキャンセルする(メソッド Cancel())能力があります。
  • CancellationToken 自体は「信号フラグ」で、ソースの Token プロパティを通じて複数の操作に配布できます。
  • 操作は定期的にトークンをチェックし、もしキャンセルが要求されていれば動作を終了するか(または OperationCanceledException を投げます)。

例え話: あなたが上司(あなたが CancellationTokenSource)。部下にバッジを配る(それが CancellationToken)。「もう中止」の合図を出すと、バッジを持っている人はすぐに撤収します。

2. CancellationToken の使い方

キャンセルトークンソースを作る(CancellationTokenSource)

var cts = new CancellationTokenSource();

トークン本体を取得する(CancellationToken)

CancellationToken token = cts.Token;

トークンを非同期メソッドに渡す

ほとんどの標準的な非同期メソッドは CancellationToken 型のパラメータを受け取ります。例: HttpClient.GetAsync、Stream.ReadAsync、Task.Delay など。

例 — キャンセル可能な遅延:

await Task.Delay(10000, token); // 10秒待つ — でもキャンセルできる!

キャンセルを要求する(ボタンやタイマーから)

cts.Cancel(); // このトークンを受け取っている全ての操作がキャンセルを知る 

メソッド内でトークンをチェックする

自分のメソッド内(特に長時間ループする処理)では定期的にキャンセルフラグをチェックして、要求されていれば OperationCanceledException を投げる必要があります:

token.ThrowIfCancellationRequested();

あるいは単純にプロパティをチェックして:

if (token.IsCancellationRequested)
{
    // リソースを解放してメソッドを抜ける
}

3. 例: 学習用アプリにキャンセルを追加する

仮にウェブからデータをダウンロードするアプリがあるとします。ユーザーが途中でやめたくなったらダウンロードをキャンセルできるようにしてみましょう。

非同期ダウンロードの基本例

using System;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

class Downloader
{
    public async Task DownloadAsync(string url)
    {
        var client = new HttpClient();
        string content = await client.GetStringAsync(url); // キャンセルなし
        Console.WriteLine("ダウンロードが完了しました!");
    }
}

CancellationToken を追加する

public async Task DownloadAsync(string url, CancellationToken token)
{
    var client = new HttpClient();
    string content = await client.GetStringAsync(url, token); // これでキャンセル対応!
    Console.WriteLine("ダウンロードが完了しました!");
}

呼び出し側でキャンセルを管理する

static async Task Main(string[] args)
{
    var downloader = new Downloader();
    var cts = new CancellationTokenSource();

    Console.WriteLine("ダウンロードするURLを入力してください:");
    string url = Console.ReadLine();

    var downloadTask = downloader.DownloadAsync(url, cts.Token);

    Console.WriteLine("ダウンロードをキャンセルするには何かキーを押してください...");
    Console.ReadKey();

    cts.Cancel(); // キャンセルの合図

    try
    {
        await downloadTask;
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("ダウンロードはユーザーによってキャンセルされました!");
    }
}

これで簡単にユーザーがいつでも操作を中断できます。

4. CancellationTokenSource とメソッドの相互作用

flowchart TD
    A["ユーザーのコード (Main)"] -- 作成 --> B["CancellationTokenSource"]
    B -- 発行 --> C["CancellationToken"]
    C -- 渡される --> D["非同期操作"]
    A -- Cancel() を呼ぶ --> B
    D -- 定期的にチェック --> C
    C -- キャンセルを通知 --> D
    D -- 例外を投げるか終了 --> A

5. キャンセルの処理

操作がキャンセルトークンを受け取ったとき、振る舞いは主に2つです:

.NET のメソッドが自動的に例外を投げる場合。
標準メソッド(Stream.ReadAsync、HttpClient.GetAsync、Task.Delay など)にトークンを渡すと、Cancel() が呼ばれた瞬間にそれらのメソッドは自動的に OperationCanceledException を投げます。呼び出し側はその例外をキャッチするだけでOKです。

自前の非同期コードの場合。
自分で長時間動く処理(ループや重い計算)を書く場合は、定期的に token.IsCancellationRequested をチェックする、または token.ThrowIfCancellationRequested() を呼んでキャンセルに対応する責任があります。

例: 手動でキャンセルをチェックする「長い」操作

public async Task CalculatePrimesAsync(int max, CancellationToken token)
{
    for (int i = 2; i < max; i++)
    {
        token.ThrowIfCancellationRequested(); // キャンセルをチェック

        if (IsPrime(i))
        {
            Console.WriteLine($"素数: {i}");
            await Task.Delay(100, token); // 少し休ませる(キャンセル可能)
        }
    }
    Console.WriteLine("計算が完了しました!");
}

private bool IsPrime(int n)
{
    for (int i = 2; i <= Math.Sqrt(n); i++)
        if (n % i == 0) return false;
    return true;
}

6. 役立つ注意点

CancellationToken をサポートするメソッドとクラス

クラス/メソッド CancellationToken をサポートする? 使用例
Task.Delay
✔
await Task.Delay(1000, token);
HttpClient.GetAsync
✔
await client.GetAsync(url, token);
Stream.ReadAsync
✔
await stream.ReadAsync(buffer, 0, len, token);
Task.Run
✔
Task.Run(() => ..., token);
File.ReadAllTextAsync
✔
await File.ReadAllTextAsync(path, token);
Thread.Sleep
✖ サポートしていない; 代わりに Task.Delay を使うのが良い
あなたのメソッド ✔ (対応を追加すれば!)
MyLongMethod(token)

キャンセル可能な操作のライフサイクル

sequenceDiagram
    participant ユーザー
    participant Main
    participant CancellationTokenSource
    participant 非同期操作

    ユーザー->>Main: 操作を開始
    Main->>CancellationTokenSource: CTS を作成
    Main->>非同期操作: 起動して CancellationToken を渡す
    ユーザー->>Main: 「キャンセル」ボタンを押す
    Main->>CancellationTokenSource: Cancel() を呼ぶ
    非同期操作->>非同期操作: キャンセルを検知 (\nIsCancellationRequested)
    非同期操作-->>Main: OperationCanceledException を投げる
    Main->>ユーザー: 「操作はキャンセルされました」と表示

実際の利用例

  • UI アプリ: 長時間のダウンロードや計算、ファイル操作をユーザーがウィンドウを閉じたり操作をキャンセルしたときに中断する。
  • サーバーアプリ: クライアントが接続を切ったらリクエスト処理を早めにキャンセルしてリソースを節約する。
  • 大規模データ処理: 長時間実行されるタスクはいつでも停止できるようにしておく。
  • ハードウェア連携: スキャンや印刷など、緊急停止が必要な操作にはキャンセル対応が必須。

7. CancellationToken を使う際のよくあるミス

ミスその1: トークンチェックを無視する。
操作が token.IsCancellationRequested をチェックしない、あるいは ThrowIfCancellationRequested() を呼ばないと、キャンセルされても止まらずリソースを消費し続けます。

ミスその2: OperationCanceledException の誤った処理。
< span class="code text-red">OperationCanceledException をキャッチしないとアプリが予期せず終了することがあります。キャンセル専用の例外処理を try-catch で行いましょう。

ミスその3: キャンセル時のリソース管理の不備。
キャンセルは自動的に状態を巻き戻すわけではありません(ファイルやDBの変更など)。catch ブロックで必要なクリーンアップを行ってください。

ミスその4: 既にキャンセルされたトークンを渡す。
トークンが既にキャンセル済みだと、メソッドは即座に例外を投げます。これを考慮してロジックを組む必要があります。

2
タスク
C# SELF, レベル 60, レッスン 4
ロック未解除
キャンセル対応の素数検索
キャンセル対応の素数検索
1
アンケート/クイズ
TaskとThreadの比較、レベル 60、レッスン 4
使用不可
TaskとThreadの比較
データの並列処理
コメント
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION