ProConcepts Asynchronous Programming in ArcGIS Pro - EsriJapan/arcgis-pro-sdk GitHub Wiki

ArcGIS Pro は非同期アプリケーションです。アドインを作成する開発者は、非同期での実装を準備する必要があります。このコンセプト ドキュメントでは、アドインで使用できる様々な非同期プログラミングの手法について説明します。このコンセプト ドキュメントは ProConcepts Framework working with multithreading in arcgis pro の情報を補完するものです。開発者は、最初 に上記コンテンツの内容を理解する必要があります。

ただし、このコンセプト ドキュメントは、マルチスレッドまたは非同期プログラミングのイントロダクションやチュートリアルではありません。これは、ArcGIS Pro API とアドインでの使用に焦点を当てています。 非同期プログラミング および関連トピックに関する一般的な情報については、オンラインで入手可能なチュートリアルと入門書を読むことをお勧めします。

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          10/06/2024  
ArcGIS Pro:    3.4
Visual Studio: 2022

トピック

• 概要
• ArcGIS Pro のスレッド
  • QueuedTask
  • BackgroundTask
  • System.Threading.Tasks.Task
• API の特徴
• 非同期メソッドの使用
  • Async と await
  • 非同期関数からの戻り値
  • 例外処理
  • 進行状況とキャンセル
• 同期メソッド (#calling-asynchronous-methods-within-a-queuedtask)
  • QueuedTask の使用
  • 例外処理
  • QueuedTask からの戻り値
  • QueuedTask 内での非同期メソッドの呼び出し
• カスタム メソッドの開発
  • 同期メソッド
    • スレッドのチェック
  • UI の更新
  • 非同期メソッドの代替
• BackgroundTask の使用

ArcGIS Pro は非同期アプリケーションです。 ArcGIS Pro は多くの理由で非同期性を利用しますが、アドイン開発者にとって非同期 API の主な目的は、ArcGIS Pro の UI の応答性を維持しながらアドインが "作業" を行えるようにすることです。ここでの "応答性" とは、バックグラウンドで処理が行われている間に UI がコンテンツを描画したり更新したりできることを意味します。一方 ArcMap では、長時間の処理中に UI が "フリーズ" し、応答性が低下することがあります。非同期 API の主な目的は、アドイン開発者に並列性や並行性* を提供することではありません。後述するように、API を介した ArcGIS Pro のプライマリ ワーカー スレッドを使用すると、(アドインまたは Pro コードからの) すべての送信されたバックグラウンド操作をキューに入れて、それらが順次実行されるようにすることで、同時実行を防げます。これについては、以下のセクションで詳しく説明します。

*バージョン 2.6 で BackgroundTask を使用したバックグラウンドでの同時処理をサポートしました。

通常、ArcGIS Pro のアドイン開発者は、2 つのスレッドにのみ対応する必要があります。UI スレッドと、"QueuedTask" を介してアクセスされる、アプリケーションが提供する特殊なワーカー スレッドの 2 つです。ただし、バージョン 2.6 では、BackgroundTask と呼ばれる、アドイン開発者が使用するための 3 つ目のバックグラウンド スレッド (実際にはバックグラウンド スレッド プール) へのアクセスが導入されました。QueuedTask とBackgroundTask はどちらも Microsoft の .NET タスク並列ライブラリ TPL と、タスク非同期パターン TAP と呼ばれるプログラミング パターンを使用します。QueuedTask と BackgroundTask は System.Threading.Tasks.Task クラスをモデルにしていますが、以下のようないくつかの重要な違いがあります:

• QueuedTask と BackgroundTask は、COM コンポーネントおよびスレッド アフィニティを持つコンポーネントとの使用に互換性のある シングル-スレッド アパートメント を使用しています*。
• QueuedTask と BackgroundTask は、Microsoft の Task スレッド プールではなく、ArcGIS Pro のマネージド スレッド プール上で操作を実行します。
• QueuedTask の処理は、論理的な競合を防ぐためにキューに入り FIFO シーケンスで実行されます。これにより、呼び出しの適切な順序が保証され、競合のリスクが軽減し、一貫したアプリケーションの状態を維持できます。QueuedTask 上の別々の処理は並列に実行されないため、Microsoft の "System.Threading.Tasks.Task" (および ArcGIS Pro の BackgroundTask) を使用する場合と比較して、タスク作成の難易度が軽減されます。

*BackgroundTask は、スレッド アフィニティを持つオブジェクトでの使用を想定していませんが、"TaskPriority.single" 型の TaskPriority を使用してスレッド アフィニティを提供できます。

QueuedTask クラスは、アドイン開発者がアドイン コードを非同期に実行するために使用する事実上の主要なメカニズムです。QueuedTask は、すべての処理を ArcGIS Pro アプリケーションのプライマリ ワーカースレッドで実行します。これは、MCT (Main CIM Thread) と呼ばれることもあります。

ArcGIS Pro アプリケーションのステートの大部分は、CIM (Cartographic Information Model) と呼ばれるモデルによって維持されています。CIM は、マップ、レイアウト、レイヤー、スタイル、シンボルなどのコンテンツ、構成、表現を含む、開かれたプロジェクトの完全な状態を記述する多数のモデルで構成されています。CIM へのアクセスは MCT によって制御され、MCT は QueuedTask を介してアクセスされます。MCT は、CIM アプリケーションの状態の変更が CIM スレッド プールのすべてのスレッド間で同期され、それに応じて ArcGIS Pro の UI が更新されるようにします。UI のアプリケーションの有効/無効状態も MCT タスクの実行中に自動的に制御され、ビューの作成やアプリケーションのシャットダウンなど、アプリケーションの重要なフェーズも MCT で調整されます。

ほとんどの場合、アドイン開発者は、カスタム アドイン コードで非同期操作を実行する際に、QueuedTask を 排他的 に使用します。

ArcGIS Pro のほとんどの GIS 操作は QueuedTask 上で実行されますが、操作をバックグラウンド スレッド上でノンモーダルに実行することが適している場合もあります (COM コンポーネントの使用と互換性があります)。このような操作は長時間行われる可能性があり、アドイン開発者は、ArcGIS Pro の UI を有効にしたまま、その間 QueuedTask を拘束することを避けたいと考えています。このため、バージョン 2.6 では、BackgroundTask がパブリック API に追加されました。BackgroundTask は一般的にアプリケーションの状態にアクセスする操作では使用できません。BackgroundTask の使用方法や制限事項については、Using BackgroundTask のセクションで説明しています。

開発者は、アドインの中で System.Threading.Tasks.Task を使用することを妨げられませんが、"System" タスクは (ArcGIS Pro API の大部分を支える) COM コンポーネントとの使用には互換性がないことに注意する必要があります。"System" タスクでの使用に適した操作はサード パーティのコードのみを含む操作であり、おそらく独自の Web サービスや本質的に非同期で ArcGIS Pro アプリケーションの状態にアクセスする必要のない他のサード パーティのアプリケーション エンド ポイントと通信するためのものでしょう。"System" タスクで使用される操作は、本質的に非モーダルである必要があり、アプリケーションのビジー状態で ArcGIS Pro の UI を無効にする必要はありません (QueuedTask の場合と同様)。BackgroundTask が利用可能であることを考えると、アドインでの "System" タスクの使用はまれであり、それらの使用はこのドキュメントの範囲外です。

すでに ArcGIS Pro のアドイン開発に取り組んだことのある開発者は、ArcGIS Pro の API の大部分が同期型ではなく非同期型であることに気づいたことでしょう。非同期アプリケーションが主に同期 API を持っていることは直感的に理解しにくいかもしれませんが、アプリケーションのワークフローは一般的に "順番に" 実行されるコンポーネントのステップで構成されています (例: 機能選択、属性変更、保存)。ワークフロー自体は、通常、非同期的に実行されるもので、単一の作業単位または "操作" として実行されます。また、API は非常に細かく、非同期メソッドの使用はより困難になる可能性があるため、同期 API にも適しています。したがって、ArcGIS Pro API のメソッドは主に 2 つのカテゴリに分類されます:

• どのスレッドからでも呼び出すことができる少数の非同期メソッドです。このタイプのメソッドは Async という接尾語を使って命名され、通常はタスクを返します ("通常" というのは void を返すこともあるため)。ほとんどの場合、非同期メソッドの同期バージョンも用意されています。非同期メソッドは粗い粒度のものが多く "単独" で使用できることがよくあります。

• ArcGIS Pro のワーカー スレッドでのみ呼び出されるべき非常に多くの同期メソッド - 主に QueuedTask 経由の MCT。これは API メソッドの大部分です。UI スレッドから QueuedTask を必要とする同期メソッドを呼び出そうとすると CalledOnWrongThreadExcetpion が発生します。

また、3 つ目と 4 つ目のカテゴリーがあります:

• GUI スレッドで呼びだす必要があるメソッド (通常 ArcGIS Pro の UI 要素を作成または更新)、またスレッド アフィニティのない同期メソッド (多くのジオメトリ メソッドや、キャッシュされたアプリケーションの状態や "スナップショット" を使用するメソッド（map.GetLayersAsFlattenedList(), etc..）などいくつかのメソッド (非同期と同期の両方) があります。注記：スレッド アフィニティのないメソッドは (UI や QueuedTask に加えて) BackgroundTask での使用に適しています。

ArcGIS Pro API の非同期メソッドは、UI スレッド* から安全に呼び出されるように設計されています (ただし、QueuedTask や BackgroundTask からも呼び出せます)。非同期メソッドは、メソッド名に "Async" というサフィックスが付いており、戻り値のタイプが Task であることで識別できます (例: PanToSelected Async、RedrawAsync、SetViewingModeAsync)。非同期メソッドは性質上、粗い粒度になる傾向があり、通常 "定型化された" ワークフローや操作をカプセル化します。ほとんどの場合、API の非同期メソッドは同期対応のものを持っていますが、前述のように API メソッドの大半は同期のみです。

ワークフローの例を使用して、ArcGIS Pro API の非同期メソッドの使い方を説明しましょう。以下のコードでは、API を使用して GP ツール "SelectLayerByAttribute" を実行し、"TerritorialStats_3" レイヤーで "KentCC" という名前の郡を選択しています。次に、選択されたフィーチャの範囲にズームを実行します (ズームインの際にアニメーション効果を出すために時間遅延を設けています)。非同期メソッドは UI から直接呼び出されています:

internal class SelectCountyAsyncButton : Button {

  //select the county of Kent. Zoom to its extent
  protected override void OnClick() {
    //Create the GP parameters
    var values = new string[] { "TerritorialStats_3", "NEW_SELECTION", "name = 'Kent CC'" };
    //Execute the GP Tool
    Geoprocessing.ExecuteToolAsync("SelectLayerByAttribute_management", values);
    //Zoom to the result
    MapView.Active.ZoomToSelectedAsync(new TimeSpan(0, 0, 3));
  }
}

このコードを実行すると、動作に矛盾が生じます。郡のフィーチャが選択されているにもかかわらずズームインせず、ArcGIS Pro の範囲が変更されない場合があります (フィーチャ選択の後に、選択されたフィーチャの範囲へズームします)。また、選択されたフィーチャーに期待通りに拡大され、コードが正しく動作する場合もあります。コードが最初に実行された際に、基盤となる GP 環境が初期化されているように見えると、この矛盾が特に顕著になります。

問題は、"ExecuteToolAsync" の呼び出しが非同期で実行され (名前が示すように) フィーチャが選択される前に、呼び出し元にすぐに制御が返されることです。アドインはコードの実行を続行し、ワークフローの 2 番目の非同期メソッドである "ZoomToSelectedAsync" を呼び出します。このメソッドは、ExecuteToolAsync の内部実行特性に応じて、フィーチャ選択が実行される前にズームロジックを実行する場合があります。そのため、(コードに書かれているように) ワークフローの 期待される 処理順序が、最初に選択、次にズームであるにもかかわらず、メソッドが非同期のため、ズームが最初に実行され、選択が 2 番目に実行される可能性があります (この場合 "ズームイン" はされません)。

私たちが必要としているのは、非同期メソッドを呼び出す一貫した方法であり、それらが繰り返し、一貫した方法で実行され、意図した順序で実行されることです。今回のケースでは、まず GP の "選択" ツールを実行し、それが完了してから、"選択範囲へのズーム" を実行します。非同期メソッドを一貫性のある方法で呼び出す方法については、次のセクションで説明します。

*API の特徴の概要で述べたように、スレッド アフィニティの理由から UI 上で呼び出す必要がある非同期メソッドがいくつかありますが、それはまれです。

要約: GP ツールの実行と選択範囲へのズームメソッドが正しい順序で実行されるようにするには、最初のメソッド (実際には返された Task) が完了するのを待ってから、2 番目のメソッドに進むなどの方法が必要です。さらに、UI をブロックしたり "フリーズ" させずに最初のメソッドが完了するのを待ちことが大事です。.NET にはこのような目的のために、"async" と "await" と呼ばれる機能を提供しています。

async 修飾子は、メソッドを非同期としてマークするために使用され、同じメソッドが内部敵に await 演算子を使用することを示します。await 演算子は、呼び出し側が非同期メソッドの "完了" (具体的には、返された task が完了するまで) の間、 non-blocking 待機をしたいときに、各非同期メソッドに "追加 "されます。 各 "waited" コールはノンブロッキングのため、呼び出し側のスレッド (通常はアドインの UI スレッド) は、非同期メソッドの実行中もレスポンスを維持できます。

後述するように、await 演算子は非同期プログラミングのための非常に強力で多彩な構成要素であり、包含するメソッドの async 修飾子と常にペアになっています。async と await を使った例を以下に示します:

internal class SelectCountyAsyncButton : Button {

  //select the county of Kent. Zoom to its extent
  //Note the addition of the 'async'
  protected async override void OnClick() {/
    //Create the GP parameters
    var values = new string[] { "TerritorialStats_3", "NEW_SELECTION", "name = 'Kent CC'" };
    //Execute the GP Tool - we await it's execution.
    //UI remains responsive
    await Geoprocessing.ExecuteToolAsync("SelectLayerByAttribute_management", values);
    //Zoom to selection only when ExecuteToolAsync has completed
    await MapView.Active.ZoomToSelectedAsync(new TimeSpan(0, 0, 3));
  }
}

async と await (つまり "ノンブロッキング" な待機) を追加することで、改良されたコードは期待通りに実行されるようになりました。フィーチャ選択は最初に完了し、アドインはノンブロッキングで待機します。ArcGIS Pro の UI は応答性を維持しています (フリーズしたり "ブロック" されたりしません)。ズームは 2 番目に実行され、選択フィーチャの範囲に一貫してズームします。

非同期関数は、Task<result> ("'result' の Task" または "'result' 型の Task" と読み替えられます) という戻り値の型を使って、呼び出し元に値を返します (result は戻り値の型を表します)。 戻り値は、タスクの Task.Result プロパティに格納されています。(注記: "Task" のみを返す非同期関数の場合、返される結果はなく、Task.Result は null です)。

タスクが完了するまでは、通常 Task.Result に直接アクセスしてはいけません。Task.Result は ブロッキング プロパティです。タスクが完了する前にアクセスすると、タスクが完了して結果の値が利用可能になるまで呼び出し側がブロックされます。幸いなことに、タスクをノンブロッキングで待機するために使用しているキーワード await には、返された Task.Result プロパティから戻り値を抽出しなくても、戻り値を自動的に解決するという利点があります。

これは、以下の例で示されています。

 //Assume this async function returns an int representing some kind of count
 //Note the return type of 'Task<int>'- "Task of 'int'"
 public Task<int> GetCountOfFeaturesAsync(FeatureLayer featureLayer) { ... }

 //We are calling 'GetCountOfFeaturesAsync' from the UI...perhaps via a button click

 //Attempt 1 - add-in consumes the method to "get" the count...
 //no await is being used
 var count = GetCountOfFeaturesAsync(parcelLayer);
 //This compiles but use of "var" masks the fact that our "count" local
 //variable is actually set to Task<int> -not- int. The method is also not
 //being awaited...most likely, the add-in developer forgot to add the await...

 //Attempt 2 - using Task.Result directly
 var task = GetCountOfFeaturesAsync(parcelLayer);
 var count = task.Result;
 //This approach works - but - should generally be avoided. Accessing
 //Task.Result before the task has finished _blocks_ the UI

 //Attempt 3 - using await
 var count = await GetCountOfFeaturesAsync(parcelLayer);
 //This is the preferred method. Await does a non-blocking wait _and_ resolves
 //the Task.Result automatically. 'count' will contain the returned value when the
 //task completes.

.NET タスク インフラストラクチャ が直面する問題の 1 つは、未処理の例外を呼び出し元のスレッド (通常は UI) に戻す方法です。タスク インフラストラクチャはその例外を AggregateException クラスでラップすることでスレッドに戻します。アタッチされた子タスクが親タスクに伝播される例外が発生した場合、AggregateExceptions をネストすることもできます (AggregateException を独自のAggregateException などでラップします)。ただし、ほとんどのアドインは "System" タスクではなく、すべての処理を 単一のスレッドで実行する ArcGIS Pro の "QueuedTask" を使用しているため、アドインでこのようなシナリオが発生する可能性は非常に低いと言えます。

AggregateException にラップされた未処理の例外は、AggregateException.InnerExceptions プロパティに含まれています。AggregateException.InnerExceptions を列挙することで、発生元の例外にアクセスできます。ただし、呼び出し側が実行中のタスクを 待機 していない限り (あるいは Task.Wait を使ってブロッキング待ちをしていない限り)、タスクからの AggregateException は、タスクがガベージ コレクションされるまで呼び出し側には 伝わりません。これにより、操作が完了した後 (例: ボタンのクリック) 1～2秒後に AggregateException が発生するという、一見奇妙な動作が発生する可能性があります。

タスクが await されている場合、未処理の例外は、操作の実行中に呼び出し側に伝わり、await によって自動的に AggregateException.InnerExceptions プロパティから抽出され、発生します。つまり、async と await を使用するアドイン コードは、通常の try/catch を使用して、非同期メソッドから発生した例外を通常の方法で処理できます。

以下のコード例では、アドインの非同期メソッドによる様々なシナリオと関連する例外動作を示しています。

 //We are calling 'DoWorkAsync' from the UI thread via a button click

 //Scenario 1. The Task is not awaited...the "catch" will never catch an exception.
 //Not recommended
 try {
   DoWorkAsync(...);
 }
 catch(Exception ex) {
   //This code will never be hit
   ...
 }
 //Because we are not awaiting the asynchronous method, the add-in code will
 //exit the scope of the try/catch the moment after DoWorkAsync() is called. Any
 //exception thrown within DoWorkAsync will be propagated _after_ the returned task
 //is garbage collected (which could be at a much later point in time depending on
 //how long DoWorkAsync runs before failing ...)

 ...

 //Scenario 2. use Task.Wait. Not recommended as it is a blocking wait
 try {
  DoWorkAsync(...).Wait();//ditto for DoWorkAsync().Result
 }
 catch(AggregateException ae) {
   //access unhandled exception(s) via the InnerExceptions property...
   foreach(var ex in ae.InnerExceptions) {
     ...
 //Because we are waiting for the task to complete, the add-in remains
 //within the scope of the try/catch. We can catch AggregateException and
 //enumerate 'InnerExceptions' to retrieve the thrown exception.
 //However, we are blocking the UI
 ...

 //Scenario 3. Await the Task. This is the recommended approach.
 try {
  await DoWorkAsync(...);//non-blocking wait
 }
 catch(InvalidOperationException ioe) {
   //await "unwraps" the unhandled exception which we can catch
   //directly
     ...
 //Because we are awaiting the task, we remain within the scope
 //of the try/catch while DoWorkAsync() is executing and can catch
 //the relevant exception type(s). Notice we do not need to
 //handle 'AggregateException'...

プログレッサとキャンセラブル プログレッサの使用については、ProConcepts-Framework, Progress and Cancellation で詳しく説明しています。このセクションでは、主に CancellationTokenSource と CancellationToken の使用について説明し、その資料を補完します。

注記: Progressor パラメーターを必要とする非同期メソッドで進捗状況を表示しない、またはキャンセルしない場合のデフォルトは、組み込みの静的な Progressor.None(または CancelableProgressor.None) を使用します。また、プログレッサ ダイアログが Visual Studio デバッガーの UI スレッドに干渉するのを防ぐために (その逆も同様に)、デバッガーで実行している際はプログレッサの表示が抑制されます。プログレッサの表示は、ProgressorSource コンストラクタ をオーバーロードし delayedShow パラメーターを扱うことで制御できます。"delayedShow = true" を設定すると、タスクが早く完了した場合にダイアログの表示を遅らせることができます。"delayedShow = false" (デフォルト) を設定すると、遅延がなく、ダイアログがすぐに表示されます。

CancellationTokenSource と CancellationToken

.NET の TAP API では、CancellationTokenSource and a CancellationToken を使った、非視覚的な組み込みのキャンセル メカニズムを提供します。CancellationTokenSource は、キャンセルの "トリガー" またはイニシエーターを提供し、一方、CancellationToken は、キャンセル可能なメソッドがキャンセルされたかどうかを "監視" するためのリスナーを提供します。CancellationTokenSource には、CancellationTokenSource.Token プロパティに関連する CancellationToken が含まれています。

CancellationTokenSource を使用するには、アドインは CancellationTokenSource を直接インスタンス化し、通常はクラス レベルのインスタンス変数として保持するか、CancellationTokenSource プロパティが "組み込み" されている CancelableProgressorSource をインスタンス化します。アドインは、アドインは、CancellationTokenSource.Token を消費する任意の非同期メソッドに渡すことができます*(そしてアドインがキャンセルしたい場合があります)。アドインは、CancellationTokenSource.Cancel() を呼び出してソースをキャンセルします。これにより、CancellationToken.IsCancellationRequested プロパティが true に設定され、リスナー (この場合は実行中の非同期操作) がキャンセルされたかどうかを判断できるようになります。

CancellationToken のキャンセル ステータスを定期的にチェックするのは、非同期オペレーションの責任です。キャンセルされたオペレーションは、単に終了するか、より一般的には、必要なクリーンアップを実行して OperationCancelledException をスローするかを選択できます。アドインはこれをキャッチして処理する準備が必要です。

アドインは、特にキャンセルされている場合は、使用後に CancellationTokenSource を破棄する必要があります。 キャンセルされると、CancellationTokenSource を "キャンセル解除" して再利用できません。一般的なパターンは次のようになります:

 //class level variable - perhaps in the module or view model of a dockpane
 private CancellationTokenSource _cts = null;

 //A cancel command bound to a "Cancel" button on a dialog or dockpane
 public ICommand CancelCmd {
      get  {
        if (_cancelCmd == null) {
          _cancelCmd = new RelayCommand(() => {
	   //Request cancellation.
	   _cts?.Cancel();
           }, () => _cts != null, true, false);
        }
        return _cancelCmd;
   ...

 //Runs the cancellable operation - called directly from a 'Start'
 //button or similar...
 private async void DoWorkAsync() {
    _cts = new CancellationTokenSource();
    try {
      await RunCancelableProgressAsync(_cts.Token);
    }
    catch (OperationCanceledException e) {
      //we were cancelled - take appropriate action
    }
    finally {
      _cts = null;//Dispose of any old source
    }
 }

 //The Cancellable operation elsewhere in the add-in...
 //Consumes a CancellationToken
 public Task RunCancelableProgressAsync(CancellationToken token) {
    return QueuedTask.Run(()=> {
      ...
      while(stillWorking) {
        //Doing work
        ...
        //Check cancellation
        if (token.IsCancellationRequested) {
           //we are cancelled - so we can either simply exit....
           stillWorking = false;//or "break", etc.
           ...
           //...or... we can terminate throwing an
          //OperationCanceledException
          token.ThrowIfCancellationRequested();
        }
      }
   }
 }

*注記: CancelableProgressorSource を消費するキャンセル可能な非同期関数は、常にプログレッサから CancellationTokenSource を取得して、CancellationToken を取得できます。

ArcGIS Pro API のメソッドの大部分は同期型で、同期型メソッドのほとんどすべては、MCT と呼ばれる特別な ArcGIG Pro のワーカー スレッド上で実行する必要があります。ArcGIS Pro ワーカー スレッドを必要とする同期メソッドは、Intellisense および API リファレンスで、"This method must be called on the MCT. Use QueuedTask.Run (このメソッドは MCT で呼び出す必要があります。QueuedTask.Run を使用してください)" と記載されています。

これは、QueuedTask.Run のコンテキスト内でメソッドを (操作の中で) 実行する必要があることを開発者に通知しています。QueuedTask.Run (および BackgroundTask.Run) は、呼び出された際に呼び出し元にタスクを返し、完了するまで待機できます。

アドイン開発者が ArcGIS Pro API を初めて使用する際に陥りやすいミスは、同期メソッドを QueuedTask.Run でラップせずに、アドイン ロジック内で直接呼び出すことです。これにより、MCT を必要とする最初の API メソッドが呼び出されたときに、ArcGIS.Core.CalledOnWrongThreadException 例外* が発生します。このエラーは、適切なメソッドをQueuedTask.Run でラップすることで簡単に修正できます。次のセクションで説明しています。

* CalledOnWrongThreadException が本番環境で発生することは意図していません。この例外は、メソッドの呼び出しに間違ったスレッドを使用していることを開発者に知らせるためのデバッグ補助として提供されています。この状態は、通常の開発過程で修正されることを想定しています。

QueuedTask.Runを使用して同期メソッドを呼び出すための最も一般的な構文は、"無名" 関数やデリゲート、または "ラムダ" と呼ばれるものを使用することです。値を返さないラムダは 'Action' として定義され、値を返すラムダは 'Func' として定義されます。QueuedTask.Run (および BackgroundTask.Run) は両方のタイプを受け入れます。つまり、アドイン開発者は、必要に応じて、ラムダから呼び出し元に値を返すかどうかを選択できます*。ラムダは、引数を受け入れるようにパラメーター化できますが、それは一般的ではありません。

QueuedTask* でラムダを使用するための一般的な構文は次のとおりです (明示的には言及されていませんが、"一般的な" 構文は、BackgroundTask.Run で使用する場合もほぼ同じです):

 Task t = QueuedTask.Run(() => {
    //code goes here
    ...
 });

 //Though this is the more common syntax - rather than assigning the returned
 //task into a local variable we simply await it - same as we did with asynchronous
 //methods in the preceding section
 await QueuedTask.Run(() => {
    //code goes here
    ...
 });

ラムダは、QueuedTask.Run のスコープ内に配置された () => {...} 構文によって定義されます。パラメーターがある場合は、ラムダの "()" 括弧に次のように追加されます: (x_val, y_val) => {...}。パラメータに型指定は必要ないことに注意してください。型指定はパラメーターの type から推測されます。非同期メソッドで見てきたように、返されるタスクを待つことができます。

*アドイン開発者は、必ずしもアドインをラムダに "パッケージ化" する必要はありません。匿名デリゲートの代わりにカスタム メソッドを使用することもできます。ラムダが便利なのは、"ワーカー コード" を別のメソッドに "格納" するのではなく、同じ関数内に維持できるからです。

以下のワークフロー例を使用して、QueuedTask.Run の使用方法を説明します。アドイン開発者が、"SelectFeaturesButton" がクリックされるたびに、現在のマップ範囲内の選択可能なフィーチャをすべて選択するための、以下のコードを実装していることを前提としています。

///<summary>Select all visible and selectable features within the "middle" of
///the current view extent</summary>
internal class SelectFeaturesButton : Button {

  protected override void OnClick() {
     Envelope selExtent = null;
     if (MapView.Active.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.Map) {
        var extent = MapView.Active.Extent;
        selExtent = extent.Expand(-0.25, -0.25, true);
        MapView.Active.SelectFeatures(selExtent);
     }
     else if (MapView.Active.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneGlobal ||
      MapView.Active.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneLocal) {
        //get the extent in pixels
        var sz = MapView.Active.GetViewSize();
        var builder = new EnvelopeBuilderEx() {
            XMin = 0,
            YMin = sz.Height,
            XMax = sz.Width,
            YMax = 0
        };
        selExtent = builder.ToGeometry().Expand(-0.25, -0.25, true);
        MapView.Active.SelectFeatures(selExtent);
     }
  }
}

アドイン開発者がコードの初期デバッグを行うと、すぐに CalledOnWrongThreadException 例外が発生します:

コードを確認すると、開発者がアドインのコードを QueuedTask でラップするのを忘れていることがわかります。そのため、アドインは (誤って) UI スレッド上で ArcGIS Pro API のメソッドをすべて実行しようとしてしまい、これが例外発生の原因となっています。MapView.Active.SelectFeaturesは、MCT を使用する必要があり、QueuedTask.Run 内で呼び出す必要があります。UI スレッド上で実行すると、CalledOnWrongThreadException が発生します。

この問題を解決するために、アドイン開発者は、QueuedTask.Run を必要とするすべてのメソッドに QueuedTask.Run を使用するようにコードを変更し、それぞれの呼び出しを独自のラムダでラップします:

///<summary>Select all visible and selectable features within the "middle" of
///the current view extent</summary>
internal class SelectFeaturesButton : Button {

  //Notice addition of 'async' and 'await'...
  protected async override void OnClick() {
      Envelope selExtent = null;
     if (MapView.Active.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.Map) {
        var extent = MapView.Active.Extent;
        selExtent = extent.Expand(-0.25, -0.25, true);
        //SelectFeatures must be run on the MCT.
        await QueuedTask.Run(() => {
           MapView.Active.SelectFeatures(selExtent);
        });
     }
     else if (MapView.Active.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneGlobal ||
      MapView.Active.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneLocal) {
        //get the extent in pixels
        var sz = MapView.Active.GetViewSize();

        var builder = new EnvelopeBuilderEx() {
            XMin = 0,
            YMin = sz.Height,
            XMax = sz.Width,
            YMax = 0
           };
        selExtent = builder.ToGeometry().Expand(-0.25, -0.25, true);
        //SelectFeatures must be run on the MCT.
        await QueuedTask.Run(() => {
           MapView.Active.SelectFeatures(selExtent);
        });
     }
  }
}

"技術的には"、上記の例に関して、開発者は QueuedTask.Run を使用して API の要件を満たし、それを必要とする関連操作を MCT に送信します。ただし、この実装は最適ではありません。API は、これらのメソッドが実際に MCT の使用を "必要" だと述べていますが、各メソッドが個別に (つまり個別のラムダ内で) MCT の使用を必要とすることを文字通り意味するわけではありません。

代わりに、API メソッドのシーケンスを (可能な限り) 単一のラムダに統合する必要があります:

 //Avoid this...
 await QueuedTask.Run(() => {
    method1(...);
 });
 await QueuedTask.Run(() => {
    method2(...);
 });
 await QueuedTask.Run(() => {
    method3(...);
 });

 //Prefer this...
 await QueuedTask.Run(() => {
    method1(...);
    method2(...);
    method3(...);
 });

また、QueuedTask.Run を構築する際にわずかなオーバーヘッドが発生しますが、ループ内で QueuedTask が呼び出されている場合には、このオーバーヘッドが大きくなる可能性があります。これも、コードを 単一のラムダにまとめることを推奨する理由です:

 //Avoid this...
 foreach(var some_item in ...) {
   await QueuedTask.Run(() => { //QTR inside the loop
     //do work
   });
 }

 //Prefer this...
 await QueuedTask.Run(() => { //QTR outside the loop
    foreach(var some_item in ...) {
     //do work
    }
 });

もう一つの修正点は、ラムダを起動する 前 にアクティブなビューの状態をキャプチャすることです:

  var mv = MapView.Active;//capture the active view state
  //use "mv"...

見た目にはわかりやすいですが、MapView.Active を使用すると、アプリケーション内で例外が発生することがあります。おそらく、選択ロジックが呼び出されたときに、以前にキューに入れられた操作が MCT で実行されている可能性があり、操作の実行を開始する前にこれらを完了する必要があります。

これはエッジ ケースですが、アドイン コードが呼び出されてから、QueuedTask.Run が実際に実行されるまでの間に、アプリケーションの状態が変化する可能性があります。例えば、ラムダが実行される前に、アクティブなビューがテーブルに変更されたり、ビュー ペインが閉じられたりする場合があります。 その場合、MapView.Active が null になり、例外が発生する可能性があります。技術的には 必須 ではありませんが、ローカル変数を使用してアプリケーションの状態のスナップショットをキャプチャすることにより、アドイン コードを堅牢にできます。ラムダが呼び出される前にローカル変数にキャプチャされたアプリケーションの状態は、あなたの下から変更されることはありません。

これはコードの例ですが、単一のラムダに統合され、アプリケーションの状態がローカル変数に取り込まれています:

///<summary>Select all visible and selectable features within the "middle" of
///the current view extent</summary>
internal class Button1 : Button {

  //Notice addition of 'async' and 'await'...
  protected async override void OnClick() {
      Envelope selExtent = null;
      var mv = MapView.Active;//capture the Mapview state...add null check if needed

     //Consolidate the code into a single QueuedTask.Run.
     await QueuedTask.Run(() => {
       if (mv.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.Map) {
          var extent = mv.Extent;
          selExtent = extent.Expand(-0.25, -0.25, true);
          mv.SelectFeatures(selExtent);
       }
       else if (mv.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneGlobal ||
         mv.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneLocal) {
          //get the extent in pixels
          var sz = mv.GetViewSize();
          var builder = new EnvelopeBuilderEx() {
            XMin = 0,
            YMin = sz.Height,
            XMax = sz.Width,
            YMax = 0
          };
          selExtent = builder.ToGeometry().Expand(-0.25, -0.25, true);
          mv.SelectFeatures(selExtent);
       }
    });//end of the QueuedTask.Run lambda
  }
}

注記: この例では QueuedTask.Run の後にコードがないため、"await" は厳密には必要ありません。また、OnClick は void を返しますが、"async" と表示できます。void とマークされた非同期メソッドは、UI に直接関連付けられたイベントやメソッドに関連付けられており、非常によく見られます (今回のケースのように)。

ラムダ内の例外ハンドラーは特別な処理を必要としません。ラムダ内で、待機していない非同期メソッドが実行されていない限り、必要に応じて try/catch/finally の通常のパターンを使用できます。ラムダの外で例外をキャッチするには、前述の非同期メソッドからの例外処理と同様に、try/catch ブロック内で待ち受ける必要があります。ラムダの外で例外をキャッチするには、QueuedTask.Run または BackgroundTask.Run を、前述の非同期メソッドからの例外処理と同様に、try/catch ブロック内で待ち受ける必要があります。

  await QueuedTask.Run(()=> {
     //"normal" try/catch inside the lambda
     try {
       ...
     }
     catch(InvalidOperationExcepion ioe) { ... }
  });


  try {
   //QTR is awaited!...
   await QueuedTask.Run(()=> ....);
  }
  catch(ArgumentNullException ane) {
    ... etc ...

QueuedTask.Run (および BackgroundTask.Run) は、戻り値のあるラムダとないラムダ (それぞれ "Func" と "Action" のデリゲート) のオーバーロードを提供します。ラムダから値を返すには、アドインの開発者は、必要な "return" ステートメントをラムダ内の必要な場所に追加するだけです。戻り値は、非同期関数からの戻り値 のセクションで説明したように、Task.Result プロパティに格納されており、await ステートメントによって "アンラップ" できます。Task.Result から返された値を変数に代入する場合、アドイン開発者は await 演算子を使用する必要があります。

 //no return value. QueuedTask is being awaited
 await QueuedTask.Run(() => {
    //do work
 });

 //the value in item_count is returned in the Task.Result.
 //It is assigned into the local variable 'result' when
 //the task completes
 var result = await QueuedTask.Run(() => {
    //do work - return a value
    return item_count;
 });

 //Be aware of this, notice - no await
 //'result' will be assigned a value of type Task<int> and _not_
 //int which may not be what the add-in developer was expecting...
 var result = QueuedTask.Run(() => {
    //do work - return a value
    return item_count;
 });

 //to get the result the task still needs to be awaited...
 var count = await result;

ラムダで実装されているワークフローの特性によっては、ラムダ内で非同期メソッドを呼び出す必要がある場合があります。UI スレッドから非同期メソッドを呼び出す場合と同じルールが適用されます。つまり、メソッドが完了するまでノンブロッキングの待機の実行が目的の場合は、非同期メソッドを待機する必要があります。await を使用するには、QueuedTask.Run のラムダ* に 'async' 修飾子を付ける必要があります:

 //execute a QueuedTask that contains an asynchronous method
 //note the 'async' modifier on the lambda
 await QueuedTask.Run( async () => {
    ...
    //async method within the lambda is awaited...
    var result = await FooAsync(...);
   ...
 });

*ネストされた QueuedTask は、"親" の QueuedTask の中で、あたかもそれぞれが 通常の同期関数 であるかのように動作し (ネストされた QueuedTask の) asyncや await は実際には必要ありません (すべての QueuedTask は MCT 上で 1 つずつ、順番に実行されます。ネストした QeuedTask も同様です)。ただし、ネストされた非同期メソッドが QueuedTask を使用していると確信できない限り、"async" と "await" を繰り返し 'recipe-style' で使用することにマイナス面はありません。

アドイン開発者は、クラスやメソッド、特に再利用可能なワークフローをラップするユーティリティやヘルパー関数の独自のライブラリを作成すると便利です。アドイン開発者に推奨されるパターンは、API と同じ規則に従うことです。つまり、主に同期メソッドを記述し、必要に応じて非同期の代替メソッドを提供します。

以下の説明では、前のセクションで説明した、選択とズームのワークフローを、同期と非同期メソッドに "変換" することを想定しています。

アドインのメソッドが同期型であるためには、理想的には非同期型のコード* を含まず、Task 型を返すことはできません。

これは、同期メソッドに統合された最初のワークフローです。これには 3 つのパラメーターがあります。1 つは MapView 型で、他の 2 つは選択範囲の拡張についてです。このメソッドは、選択結果を呼び出し元に返します:

 //Synchronous utility method
 public SelectionSet SelectFeaturesWithViewExtent(
                           MapView mv, double ratio, bool asRatio) {
   Envelope selExtent = null;
   //null check
   if (mv == null) throw new ArgumentNullException(nameof(mv));

   if (mv.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.Map) {
      selExtent = mv.Extent.Expand(ratio, ratio, asRatio);
   }
   else if (mv.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneGlobal ||
      mv.ViewingMode == ArcGIS.Core.CIM.MapViewingMode.SceneLocal) {
      //get the extent in pixels
      var sz = mv.GetViewSize();
      var builder = new EnvelopeBuilderEx() {
            XMin = 0,
            YMin = sz.Height,
            XMax = sz.Width,
            YMax = 0
      };
      selExtent = builder.ToGeometry().Expand(ratio, ratio, asRatio);
   }
   return mv.SelectFeatures(selExtent);
}

このコードは特にユニークなものでははなく、必要に応じて他のワークフローに組み込むことができます。ただし、消費している基本的な ArcGIS Pro API の要件により、QueuedTask.Run 内で実行される操作の一部としてのみ呼び出すことができます。

*これは絶対的なものではなく、経験則に近いものです。重要なのは、どのような状況でも、メソッドを "非同期" としてマークして同期と見なすことはできないということです。 したがって、同期メソッドは非同期コードを実行できますが、同期を維持するために、それを待つことはできません。

唯一のスレッド消費者ではない場合は、スコープがパブリックであるため、同期関数にスレッド チェックを追加することをお勧めします。同期 API メソッドは、間違ったスレッドで呼び出された場合に例外をスローするように対処するので、カスタム メソッドがスレッド チェックを実行することは 必須 ではありませんが、コードを参照する他のアドイン開発者にとって、自己文書化のための有用な手がかりとなります。

QueuedTask には、コードが現在実行されているスレッドをチェックするためにアドインが使用できる 2 つの静的プロパティがあります: QueuedTask.OnGUI と QueuedTask.OnWorker で、それぞれ UI と MCT のどちらにいるかを判断します。今回の目的ではどちらでも構いません。MCT 上にいない場合は、CalledOnWrongThreadException をスローして、他の開発者にこのメソッドのスレッド アフィニティ要件を明らかにします。通常、スレッド チェックは最初に行います:

 public SelectionSet SelectFeaturesWithViewExtent(
                           MapView mv, double ratio, bool asRatio) {
   Envelope selExtent = null;

   //self-documenting thread check
   if (!QueuedTask.OnWorker) {
     throw new ArcGIS.Core.CalledOnWrongThreadException();
   }

   //null check
   if (mv == null) throw new ArgumentNullException(nameof(mv));
   ...
}

特定のケースでは、カスタム メソッドは UI の UI 要素のコンテンツ (進行状況を表示するコントロールなど) を更新する必要があります。 WPF では、UI 要素のコンテンツは UI スレッド* からのみ更新できます。したがって、カスタム メソッドがバックグラウンド スレッド (QueuedTask や BackgroundTask など) で実行されている場合は、UI スレッドで更新を行うコードを適切に呼び出す必要があります。 WPF は、この目的のために特別にDispatcher クラスを提供します。

Dispatcher は WPF の 任意の UI 要素からアクセスできますが、ほとんどのアドイン コードは、ビュー モデルやアドイン モジュールなどの非ビジュアルクラスで実行される可能性があるため、WPF の UI 要素にすぐにアクセスできません。 インスタンス (Dispatcher にアクセスするため)。 ただし、ArcGIS Pro アプリケーション インスタンスは FrameworkApplication.Current を介してすぐに利用でき、その Dispatcher はこの目的に便利に使用できます:

 //access the Pro application dispatcher to invoke UI updates
 var dispatcher = FrameworkApplication.Current.Dispatcher;
 ...

WPF の Dispatcher オブジェクトは、UI 要素を更新するための 2 つの主要なメソッドを提供します - 非同期の Dispatcher.BeginInvoke と同期の Dispatcher.Invoke です (そして、ブロックされます)。BeginInvoke は、指定されたアクションを UI で実行するようにスケジュールし、すぐに制御をアドインに戻します。BeginInvoke を待機する必要はありません (同期メソッドを非同期メソッドに "変換" するため)。これは基本的に、実行したら忘れるというメカニズムです。UI がアドインのコードと正確に同期していることが重要な場合は、Invoke を使用してください。Invoke は、UI が更新されるまで呼び出し元をブロックします。実際には、Invoke を使用することはほとんどないでしょう。

UI の更新を行うアドイン コードが UI または ArcGIS Pro バックグラウンド スレッドの両方で実行できる場合は、Dispatcher.CheckAccess() を使用して Invoke が必要かどうかをテストすることができます。CheckAccess は、現在のスレッドが、Dispatcher に関連付けられているスレッド (ここでは UI スレッド) と同じかどうかをチェックします。CheckAccess が true を返した場合、invoke は 必要ありません (UI スレッドにいるため)。CheckAccess が false を返した場合、invoke が必要になります (UI スレッドにいないため)。

完成したロジックは以下のようになります*:

  //Assume this method does the relevant UI update...
  private void UpdateProgress(...) {
    //whatever "update progress" means - change a counter, text, etc
    ...
    NotifyPropertyChanged("ProgressValue");//Assuming something is bound to this
  }

  //Our method that needs to update the UI
  public void DoWork(...) {
    ...
    //this code is running synchronously but on which thread?
    //check UI access...
    if (FrameworkApplication.Current.Dispatcher.CheckAccess()) {
      //this means we are on the UI thread already
      UpdateProgress(...);//no invoke necessary
    }
    else {
      //this means we are on another thread (usually the MCT)
      //we must invoke progress via the Dispatcher
      FrameworkApplication.Current.Dispatcher.BeginInvoke(
                  (Action)(() => UpdateProgress(...))); //Fire and forget...
    }
    ...

*"進行状況" をユーザーにシンプルに伝達するために、progressor クラスは、公称周波数で進行状況を更新するための純粋なコールバック メカニズムを提供します。

この例は BeginInvoke (非同期) を使用しており、それを待機していないことに注意してください。BeginInvoke を使用するための構文は、やや複雑になる可能性があります。 主な問題は、通常、匿名デリゲートのみを除くオーバーロードを使用する場合 (つまり、 "() => ..." ラムダ) です。"Action" と入力するには、ラムダの明示的なキャストを提供する必要があります。そうしないと、コードがコンパイルされません。キャストは次のようになります: (Action)(... lambda going here ...) これは (Action)(() => UpdateProgress(...)) の最終的な構文につながります。

アドインは、UI の更新ロジックをユーティリティ メソッドに統合することができ、次のように構文を単純化できるという利点があります:

  //Utility method to consolidate UI update logic
  public void RunOnUIThread(Action action) {
    if (FrameworkApplication.Current.Dispatcher.CheckAccess())
       action();//No invoke needed
    else
       //We are not on the UI
       FrameworkApplication.Current.Dispatcher.BeginInvoke(action);
  }

 //Assume this method does the relevant UI update...
  private void UpdateProgress(...) { ... }

  //Our method that needs to update the UI
  public void DoWork(...) {
    ...
    //Use the utility method...
    Module1.Current.RunOnUIThread(() => UpdateProgess(50, "working..."));
    ...

*すべての WPF の UI コンテンツは、DispatcherObject から派生しています。 DispatcherObjects には、それらが作成されたスレッドからのみアクセスできます。多くの場合、所有スレッドと呼ばれます。ほとんどの場合、UI コンテンツの所有スレッドは UI スレッドです。

ArcGIS Pro APIのパターンに従うと、カスタムの "select "メソッドに非同期の代替手段を提供し、UI スレッドから安全に呼び出せるようにすることができます。これにより、UI スレッドから安全に呼び出すことができます。非同期メソッドの設計では、同期メソッドを QueuedTask でラップし、返される型を "Task "に変更します。メソッド名に "Async "というサフィックスを付けて、同期メソッドとの差別化を図っていますが、これは必須ではなく、あくまでも慣例です。この非同期メソッドは次のように実装されています:

  //recall: synchronous method signature
  public SelectionSet SelectFeaturesWithViewExtent(
       MapView mv, double ratio, bool asRatio) { ... }

  //Asynchronous alternative that wraps the synchronous method
  public Task<SelectionSet> SelectFeaturesWithViewExtentAsync(
      MapView mv, double ratio, bool asRatio) 
  {
       //Wrap the synchronous method in a QueuedTask
       return QueuedTask.Run(() => SelectFeaturesWithViewExtent(mv, ratio, asRatio));
  }
          

カスタム アドインのコードを主に同期メソッドとして記述することで、QueuedTask.Run で同期メソッドをラップするだけで、必要に応じて非同期の代替手段を簡単に提供できます。SelectFeaturesWithViewExtentAsync を UI スレッドから安全に呼び出すことができるようになりました。

ArcGIS Pro のほとんどすべての GIS 操作は、QueuedTask で実行されます。ただし、操作をバックグラウンド スレッド上でノンモーダルに実行することが適している場合がいくつかあります (COM コンポーネントの使用と互換性があります)。これらの操作は長時間実行される可能性があり、アドイン開発者はその間 QueuedTask を拘束することを避け、ArcGIS Pro の UI を有効にしたままにしておきたいと考えています。BackgroundTask は、ArcGIS Pro のバックグラウンド スレッド プールで処理を実行しますが、これはバージョン 2.6 以前はパブリック API では利用できませんでした。

ArcGIS Pro のバックグラウンド スレッド プールは、通常の部分と優先度の高い部分に分けられます。通常の優先度のプールは、ほとんどの操作を対象としており、中程度から長時間実行される操作に適しています。優先度の高いプールは、I/O 操作を伴わない計算機的な性質を持つ短時間の操作のために厳密に確保されています。特定のリクエストが短いか長いかを確実に判断できない場合は、長いと仮定して通常の優先度プールを使用してください。バックグラウンド操作の優先度は、BackgroundTask.Run() の第一引数として渡される ArcGIS.Core.Threading.Tasks.TaskPriority パラメーターで指定します。

操作が QueuedTask ではなく BackgroundTask での使用に適しているかどうかを判断するには、次の基準を満たす必要があります:

• 操作は ArcGIS Pro の状態にアクセスしたり変更したりしません (つまり、CIM の状態がないため、レイヤー、マップ、スタイル、レイアウト、またはその他のプロジェクトコンテンツの読み取り/書き込みはありません)。操作の最初の段階で状態を 読み取る ことは安全ですが、バックグラウンド操作では、アプリケーションの状態が一旦開始された後も静的なままであると仮定することはできません(QueuedTask 内の場合と同様)。
• この操作は、実行中にユーザーからの入力を必要としません (ただし、バックグラウンド タスクは、UI を通じてユーザーに 進行状況 を伝えることができます)。

BackgroundTask は QueuedTask とは大きく異なります。QueuedTask は操作を 単一のスレッド (MCT) にキューを追加し、送信された操作を FIFO 順に実行しますが、BackgroundTask は、ArcGIS Pro のバックグラウンド スレッド プールで使用可能なスレッドを使用して、送信された操作を 同時に 実行します。同時に実行されるバックグラウンド タスク間で共有されるアドインの状態は、破損を防ぐために、適切なロック、ミューテックスなどで保護する必要があります。バックグラウンド操作が行われている間、ユーザーは自由に現在のプロジェクトをアンロードしたり、アクティブなビューを変更したり、アプリケーションに変更を加えたりすることができます。バックグラウンド操作は、そのような場合にも対応できるように堅牢である必要があります。ネストされた BackgroundTask は、もしそのようなことがあったとしても、インライン化されません。これを、ネストされた QueuedTasks が (単一のスレッドに) インライン化され、同期関数であるかのように実行される QueuedTask と比較してください。

BackgroundTask は、スレッド アフィニティを持つオブジェクトでの使用を想定していませんが、BackgroundTask.Run でラムダを呼び出す際に TaskPriority.single 型の TaskPriority を使用することで、スレッド アフィニティを提供し、一貫したスレッドでタスクを実行できます:

   //Use TaskPriority.single for background operations with thread affinity
   await ArcGIS.Core.Threading.Tasks.BackgroundTask.Run(
          TaskPriority.single, () => {
            //Do Work
            ...
    }, BackgroundProgressor.None);

以下の例では、ユーティリティ メソッドが BackgroundTask を使用して、StyleItems のコレクションから一連のプレビュー画像を生成しています。アプリケーションの状態は変更されていないため、QueuedTask をこの操作と結び付ける必要はありません。 さらに、プレビュー画像の生成にはコストがかかる可能性があるため、BackgroundTask はデフォルトの優先度である TaskPriority.normal を使用して実行されています:

using System.Windows.Media;
using System.Windows.Media.Imaging;
using ArcGIS.Core.Threading.Tasks;
...

//Generate preview images for the input style items
internal Task<List<ImageSource>> GeneratePreviewImagesAsync(IList<StyleItem> styleItems) {

  //Application state is not affected so let's use a background thread...
  //This is potentially long running so leave the priority at 'normal'
  return BackgroundTask.Run(() => {
     //make each image a little bigger (just for purposes of visibility)
     var scale = new ScaleTransform() {
       ScaleX = 2,
       ScaleY = 2
     };
     var preview_images = new List<ImageSource>();
     foreach (var style_item in styleItems) {
        //If PreviewImage is null, a PreviewImage will be generated
        var bmsource = (BitmapSource)style_item.PreviewImage;
        //scale up the image and save it
        preview_images.Add(new TransformedBitmap(bmsource, scale));
     }
     return preview_images;
  }, BackgroundProgressor.None);
}


//Usage...
var styles = Project.Current.GetItems<StyleProjectItem>().ToList();
var theStyle = styles.First(style => style.Name == "ArcGIS 2D");

//Get all the point symbols from the 2D style
var point_symbols = await QueuedTask.Run(() => theStyle.SearchSymbols(StyleItemType.PointSymbol, ""));

//Generate preview images for each in the background
var preview_images = await GeneratePreviewImagesAsync(point_symbols);