ProConcepts Framework - EsriJapan/arcgis-pro-sdk GitHub Wiki

ArcGIS Pro は、高度に構成可能で拡張可能なアプリケーションです。すべてのソフトウェアの変更と拡張は、アドインを使用して実現されます。アドイン モデルは、単一の圧縮ファイルに便利にパッケージ化されたカスタマイズのコレクションを作成するための宣言ベースのフレームワークを提供します。アドインは、インストール プログラムや登録を必要としないため、簡単に共有できます。アドインは、既知のフォルダーにコピーするだけでシステムに追加され、このフォルダーから削除することで削除されます。アドインは、一元化されたネットワーク共有を使用して、組織内のユーザー間で共有することもできます。

アドインは、.NET と Esri のデスクトップ アプリケーション マークアップ言語（DAML）を使用して作成されます。DAML（Esri によって作成された XML 言語）はカスタマイズを記述します。.NET クラスはカスタム動作を提供します。ArcGIS Pro ソフトウェア開発キット（SDK）には、Microsoft Visual Studio と統合して開発を簡素化するアドイン ウィザードが含まれています。

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

トピック

• アドインの拡張性ポイント
• 構成
• プラグイン データソース
• ローカル アドイン VS 共有 アドイン
• アドイン インストール時にエンド ユーザー使用許諾契約書（EULA）を表示する
• DAML（Desktop Application Markup Language）の概要
  • モジュール プラグイン
  • モジュール
    • DAML でのモジュールの宣言
    • デリゲート コマンド
  • 構成可能なエクステンション
  • JIT 読み込み
  • コンディションとステート
    • ステートとコンディションの宣言
    • ステートのアクティブ化
    • 暗黙的および明示的なステート
    • ステートの場所
  • コンポーネント カテゴリ
    • categoryRefID
    • insertComponent
    • カスタム カテゴリ
• Daml 要素
• バックステージ
• コンテナ コントロール
  • ギャラリー
  • メニュー
    • コンテキスト メニュー
    • コンテキスト メニュー項目のキー チップへのアクセス
    • コンテキストの取得
  • パレット（ボタンとツール）
  • 分割ボタン
• コントロール
  • 概要
    • 拡張キャプション
    • 簡略化モード
  • ボタン
  • チェック ボックス
  • コンボ ボックス
  • カスタム コントロール
  • ダイナミック メニュー
  • 編集ボックス
  • ラベル コントロール
  • スピナー
  • ツール
• ドッキング ペイン
• ペイン
  • カウント付きペイン キャプション
• プロパティ シートとページ
• タブとグループ
  • タブ コンディション
  • サブグループ
  • sizePriorities を使用したスケーリングのコントロール
• ツールバー
• コマンドの検索
  • コマンドのサジェスト
• UI コントロール
  • ハンバーガー ボタン
  • 円形アニメーション
  • DateTimePicker コントロール
  • Info ボタン
  • メッセージ ラベル
  • 検索テキストボックス
  • TabIndicator
  • 待機カーソル
  • WebViewBrowser コントロール
• XAML アイコン
• Runtime API
• アドイン メタデータ
• イベント
  • パブリッシュ
  • サブスクライビング
  • 強力な参照を使用してサブスクライブする
• RelayCommand
• ライセンスのチェック インとチェック アウト
• Undo/Redo フレームワーク
• ドラッグ アンド ドロップ
  • ドロップのサポート
  • ペインにドロップ
    • コントロールにドロップ
    • Pro ウィンドウにドロップ
    • DAML のカスタム ドロップ ハンドラー
  • ドラッグのサポート
• 通知
  • トースト通知
  • クイック アクセス ツールバー（QAT）
  • 通知ドッキング ペイン
• 診断モード（イベント ログ）
  • 診断カウンター
• ArcGIS Pro でのマルチスレッドの操作
  • マルチスレッド プログラマーにとっての課題
  • ArcGIS Pro の内部スレッドモデル
  • タスクとタスクの非同期パターン
  • Run の使用
  • QueuedTask の使用
  • BackgroundTask の使用
  • ロック ガイドライン
• Progress と Cancellation
  • Cancellation を使用したメソッド実装の例
  • 非同期メソッド内での統合された進行状況ダイアログの使用
  • よくある問題
  • 参考文献

ArcGIS Pro アドイン フレームワークは、アドインの多数の拡張ポイントをサポートしています。次のリストは、最も一般的なカスタマイズを示しています。

• Ribbon
  • Tabs/Contextual Tabs
  • Groups
  • Controls
    • Buttons
    • Split buttons
    • Button palettes
    • Tools (including tray tools and construction tools)
    • Tool palettes
    • Toolbars
    • Galleries
    • Combobox
    • Editbox
    • Menus
    • Dynamic menus
    • Custom controls
• Panes
• DockPanes
• Property sheets/pages
• Backstage tabs
• Component categories
• ProWindow (for modal and modeless dialogs)

ArcGIS Pro の構成は、アプリケーションの高度なカスタマイズです。構成はアドインに似ていますが、アプリケーションを拡張するためのより多くの方法を提供し、組織のブランドとワークフローを反映するバージョンの ArcGIS Pro を設計するのに役立ちます。構成で実行できる重要なことには、次のようなものがあります。

• カスタム スプラッシュ画面とカスタム スタート ページを作成する
• アプリケーションのタイトルとアイコンを変更する
• 使用頻度の低いコントロールを再配置または削除する。新しいコントロールを挿入する
• 起動時にロジックを挿入して、ライセンスを確認したり、ユーザーの役割に応じてユーザー インターフェイスを変更する
• どのアドインをロードするかを制御する
• コマンドをフィルタリングする（コマンド通知とそれらを無効にするオプション）

構成では、アドインとまったく同じように、モジュール、ボタン、ドッキング ペインなどのような新しい機能を公開することもできます。

構成の詳細については、ProConcepts Configurations と ProGuide Configurations を参照してください。

プラグイン データソースは、サード パーティがカスタム（「サポートされていない」）データ ソースを Esri ソフトウェアに統合できるようにするためにArcObjectsで最初にリリースされたパターンでした。2.3 以降、Pro フレームワークが拡張され、カスタム プラグイン データソースが Pro に組み込まれました。ArcObjects では、プラグイン データソース（または「ワークスペース」）の実装は COM dll ですが、Pro では、プラグイン データソースはアドインです。アドインとして、RegisterAddin.exe によるダブル クリック登録、既知のフォルダーへの xcopy スタイルの展開、上位互換性、ArcGIS.Core.Data API を使用した .NET での実装などの多くの同じ利点を享受できます。

プラグインの基礎となるジオデータベース構造は ProConcepts Plugin Datasource で説明されており、プラグイン データソースの実装方法に関するステップ バイ ステップのガイドは ProGuide Plugin Datasource で説明されています。2.3 以降の Pro SDK は、プラグイン データソース .csproj を最初から生成するためのプロジェクト テンプレートを C# でのみ提供します。

カスタム プラグイン データソースは、完全に .NET に実装されています。これらは .esriPlugin 拡張子を持ち、1 つの例外を除いて、「通常の」Pro アドインと同じ既知のフォルダーの場所にデプロイされます。Pro アドインはバージョンのない「ArcGISPro」フォルダーにコピーされますが、デフォルトのプラグイン展開フォルダーはバージョン管理されています（ArcGISPro2.4、ArcGISPro2.5、ArcGISPro2.6 など）。ただし、プラグインには通常のアドインと同じ読み込み特性があります。たとえば、以前のバージョンは新しいバージョンの Pro によって読み込まれ、Pro アセンブリ参照は自動的に転送され、最新バージョンのプラグインが優先されます。バージョン管理されたデフォルトのデプロイメント フォルダーは、プラグインが Pro にロードされる方法の特異性です。

プラグインは Pro のネイティブ（c++）コードによってロードされ、ネイティブ コードはバージョン管理されたアドイン フォルダー（ArcObjects 10x と同じ）を使用してアドイン（またはこの場合は「プラグイン」）を検出します。プラグインはネイティブ コードによって読み込まれ、マネージ クライアントとネイティブ クライアントの両方と統合できるようになりますが、これは実装の詳細であり、アドイン コードでプラグインを実装または操作するために重要ではありません。管理対象クライアントには、Pro アプリケーション自体とサード パーティのアドインが含まれます。ネイティブ コードの統合は、プラグイン データソースから生成されたフィーチャ クラスまたはテーブルと統合できるように、Pro アプリケーションのc++層に制限されています（注：サード パーティは常に .NET を介して Pro プラグインと対話します）。プラグインは Pro のネイティブ層によってロードされるため、[アドイン マネージャー]タブには表示されません。プラグイン固有のユーザーとマシンの設定については、ArcGIS Pro Plugin Registry Keys を参照してください。

カスタム プラグイン データ ソースは、Pro ではジオデータベース フィーチャ クラスおよびテーブルとして外部に表示されるため、アプリケーションのレイヤーおよびスタンド アロン テーブルのデータ ソースとして使用できます。プラグイン テーブルから供給されたレイヤーまたはスタンド アロン テーブルを含むプロジェクトが保存されている場合、そのプロジェクトを再度開くと、マップまたはシーンは、コア データストアのフィーチャ クラスまたはテーブルの場合と同じように、（カスタム プラグイン データ ソースからの）基になるプラグイン テーブルを自動的にハイドレートします。プラグイン テーブルをソースとするフィーチャ レイヤーは、他の（フィーチャ）レイヤーと同じように描画、識別、クエリ、シンボル化などができますが、それらのソース（プラグイン）データは編集できません。

プラグインには Config.daml ではなく Config.xml が含まれています。Daml要素（ボタン、ツール、ドッキング ペイン、メニュー、プロパティ シートなど）をプラグインに追加することはできません。それらはサポートされていません。プラグインはヘッドレスであり、カスタム プラグイン データソースの実装のみが含まれています。SDK アイテム テンプレートを介してプラグイン プロジェクトにボタン、ツール、ドッキング ペインなど、またはその他の DAML 要素を追加しようとすると、「無効な ArcGIS Pro アドイン プロジェクト」というエラーが発生します。

プラグイン自体の中では、Pro ArcGIS.Core API のみにアクセスできます（Pro アセンブリに関して）。ArcGIS.Desktop.xxxxx エクステンション API からクラスインスタンスにアクセスしようとすると、Pro アプリケーションがクラッシュします。ArcGIS.Desktop.xxxxx エクステンション API dll 参照をプラグインに追加して、Pro SDK NuGet を含めることはできません。プラグインにアクセスするには（たとえば、レイヤーを作成するため、プラグインから行を取得するためのクエリなど）、ArcGIS.Core.Data API を介してプラグインをインスタンス化する別の Pro アドインが必要です。このパターンを説明する完全に実装されたプラグインとアドインについては、Simple Point Plugin サンプルを参照してください。

ユーザーのデフォルト アドイン フォルダー (C:\Users\<username>\Documents\ArcGIS\AddIns\ArcGISPro) からロードされたすべてのアドインは「ローカル」アドインとみなされ、アドイン マネージャーのバックステージ タブの「My Add-ins」リストに表示されます。 逆に、よく知られたフォルダーからロードされたアドインは「共有アドイン」とみなされ、「Shared Add-ins」リスト*に表示されます。共有アドインは、アドイン マネージャー ページを使用して削除することはできません。 書き込み権限があれば、ファイル エクスプローラーを使用してこれらのアドインを削除できます。 詳細については、Pro ヘルプのアドインの管理を参照してください。

* 3.4 以前では、よく知られたフォルダーからロードされたアドインは 「My Add-Ins」 リストに表示されました。

アドインまたは構成のインストール時にエンド ユーザー使用許諾契約書（EULA）を表示するには、EULA 情報をアドイン .csproj または .vbproj のルートに EULA.rtf ファイルとして追加します。ファイルは rtf である必要があります。「EULA」という名前にする必要があります。Eula.rtf の Build Content プロパティを Content に設定します。アドインが RegisterAddin.exe を使用してインストールされると（単にコピーするのではなく）、EULA ファイルがアドイン メタデータから抽出され、Esri ArcGIS アドイン インストール ユーティリティ ダイアログに表示されます。エンド ユーザーは、[アドインのインストール] ボタンを有効にしてインストールを続行するために、[同意する] チェック ボックスをクリックする必要があります。

詳細については、Pro Concepts Advanced Topics の「Display End user license Agreement、EULA、withAddin installation」セクションを参照してください。

アドインと構成には、宣言的でアクティブな側面があります。アドインと構成の宣言部分は、アプリケーション用語でカスタマイズを記述するフレームワーク要素（主にプラグイン）のコレクションを含む DAML ファイル内で定義されます。たとえば、アドインは、ドッキング ペインと2つのグループとボタンのコレクションを持つ新しいタブで構成されている場合があります。これらの DAML 要素は、キャプション、ツールチップ、画像、レイアウト（位置）の詳細など、コンポーネントの静的な側面も記述します。宣言部分には、必要に応じて関連オブジェクトをアクティブ化（作成）するためにフレームワークが必要とする情報も含まれています。宣言的側面とプログラム的側面へのこの分割により、柔軟性が向上し、カスタマイズの展開と配布が簡素化されます。

次の DAML は、新しいアドインの始まりを示しています。この場合、ボタンが 1 つある新しいタブがアプリケーションに追加されます。

<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="Acme.dll"
        defaultNamespace="Acme"
        xmlns="http://schemas.esri.com/DADF/Registry" 
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://schemas.esri.com/DADF/Registry
		file:///C:/Program%20Files/ArcGIS/Pro/bin/ArcGIS.Desktop.Framework.xsd">

  <AddInInfo id="{3329a7d3-9f16-4642-9a70-475b421c77b5}" 
             version="1.0" desktopVersion="3.0.34791">
    <Name>Acme</Name>
    <Description>Acme Extension</Description>
    <Image>Images\AddinDesktop32.png</Image>
    <Company>Acme</Company>
    <Date>1/10/2020 10:28:50 AM, 2019</Date>
    <Subject>Mapping</Subject>
  </AddInInfo>

  <modules>
    <insertModule id="acme_MainModule" className="MainModule" 
                  autoLoad="false" caption="Acme">
      <tabs>
        <tab id="acme_MainTab" caption="Acme Tools" keytip="AT">
          <group refID="acme_mainGroup"/>
        </tab>
      </tabs>
      <groups>
        <group id="acme_mainGroup" caption="Tools" keytip="G1">
          <button refID="acme_FullExtent" size="large" />
        </group>
      </groups>
      <controls>
        <button id="acme_FullExtent" caption="FullExtent "
                className="FullExtent" loadOnClick="true"
                smallImage="Images\FullExtent16.png" 
                largeImage="Images\FullExtent32.png"
                condition="esri_mapping_mapPane"
				keytip="B1">
          <tooltip heading="Full Extent">
            Displays the current map at its full extent.<disabledText />
          </tooltip>
        </button>
      </controls>
    </insertModule>
  </modules>
</ArcGIS>

注：1 つのファイル内の DAML 要素は、他のファイル内の要素を変更または削除できます。たとえば、別のアドインによって定義されたリボン グループに 1 つのボタンを挿入するだけのアドインです。次の例は、マッピング モジュールの既存のタブのグループにボタンを追加するものです。ボタンは特定のコントロールの前に配置されます。

<updateModule refID="esri_mapping">
  <groups>
    <updateGroup refID="esri_mapping_navigateGroup">
      <insertButton refID="acme_FullExtent" 
                    insert="before" 
                    placeWith="esri_mapping_zoomFullButton" 
                    separator="true"/>
    </updateGroup>
  </groups>
</updateModule>

すべての DAML 要素はルート ArcGIS 要素に分類される必要があります。最初の子ノードは AddInInfo 要素であり、アドイン自体に関するメタデータを保持します。これには、一意の GUID 識別子、そのバージョン、名前、および説明が含まれます。

  <AddInInfo id="{3329a7d3-9f16-4642-9a70-475b421c77b5}" 
             version="1.0" desktopVersion="3.1">
    <Name>Acme</Name>
    <Description>Acme Extension</Description>
    <Image>Images\AddinDesktop32.png</Image>
    <Company>Acme</Company>
    <Date>5/28/2015 10:28:50 AM, 2015</Date>
    <Subject>Framework</Subject>
  </AddInInfo>

カスタマイズが続き、modules, categories, conditions, propertySheets, backstage, dropHandlers などのいくつかの主要な項目に分類されます。ご覧のとおり、ほとんどのカスタマイズは modules 要素の下に表示されます。

すべてのルート ノードは、insert, update, delete の 3 つの異なるアクションの1つ以上を実行します。操作の種類は、要素名によって決まります。たとえば、新しいモジュールは、insertModule 要素を使用して宣言されます。同様に、モジュールは updateModule 要素を使用して更新されます。insert 以外の操作が有効でない場合、insert プレフィックスは削除されていることに注意してください。

  <modules>
    <insertModule id="acme_mainModule" caption="Acme" 
                  className="MainModule" autoLoad="false">
      ...
    </insertModule>
  </modules>

カスタマイズの種類ごとに、作成者が一意の ID を割り当てる必要があります。ID は、要素が挿入されるときに確立されます。カスタマイズは、更新または削除されるときに ID によって参照されます。

次の抜粋では、以前に挿入されたボタンのキャプションが updateButton 要素を使用して更新されています。id 属性は新しいオブジェクトを宣言するときに使用され、refID 属性は既存の要素を参照するために使用されることに注意してください。

  <updateButton refID="esri_SubSystem_Button1" caption="New Caption"/>

同様に、ボタンは deleteButton を使用して削除されます。

  <deleteButton refID="esri_SubSystem_Button1"/>

DAML 命令（insert, update, delete）は、さまざまなソースから処理され、実行時にフレームワークによって結合されて、元の DAML ファイルを変更せずに、すべての関係者によって提示されたすべてのカスタマイズの単一のメモリ内表現になります。ArcGIS Pro の各セッションの完全な DAML を調べるには、コマンドラインオプション /dumpcombineddaml を ArcGISPro.exe に追加します。

  ArcGISPro.exe /dumpcombineddaml

メニューなどの一部のカスタマイズは、純粋に宣言型です。DAML での定義は、フレームワークがメニューを作成して表示するために必要なすべてです。ただし、ほとんどのカスタマイズにはアクティブな（コード ビハインド）コンポーネントがあり、これらのほとんどは共通の基底クラス PlugIn から継承します。

  public abstract class PlugIn : PropertyChangedBase
  {
    public string Caption { get; set; }
    public string DisabledTooltip { get; set; }
    public bool Enabled { get; set; }
    public string ID { get; }
    public object LargeImage { get; set; }
    public object SmallImage { get; set; }
    public string Tooltip { get; set; }
    public string TooltipHeading { get; set; }

    protected internal virtual void OnUpdate();
  }

PlugIn とその派生クラスのメソッドとプロパティの多くは、開発者がオーバーライドまたは実装する必要はありません。たとえば、多くのプラグインに見られる Caption プロパティの実装はフレームワークによって提供され、プラグインが DAML を使用して宣言されたときに提供されたキャプションを返します。開発者は、OnClick などの特定の動作が必要な保護された仮想オーバーライドのみを提供する必要があります。

前述のように、すべてのプラグインには英数字の識別子（ID）が必要です。このIDは、プラグインが宣言されたときにプラグイン DAML 内で指定され、COM コクラスに一意の名前を付けるために使用される GUID と概念的に類似しています。

アクティブなコンポーネントを持つすべてのプラグインは、クラス属性とアセンブリ属性を使用して、DAML をマネージコードに接続します。クラス名は、名前空間を含む完全なクラス名です。アセンブリは DAML ファイルと同じフォルダーにあると想定されるため、パスを指定しないでください。ルート ArcGIS ノードにはdefaultNamespace属性と defaultAssembly 属性があり、DAML 全体でこの情報が不必要に繰り返されるのを軽減することに注意してください。

<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="Acme.dll"
        defaultNamespace="Acme"

プラグインが別の名前空間に属している場合は、クラス名の一部として指定してください。名前空間がデフォルトの名前空間の一部である場合は、欠落している部分のみを指定してください。次の例では、FullExtentButton クラスが Acme.Controls 名前空間に追加されています。デフォルト名は Acme であるため、DAML クラスエントリは Controls.FullExtentButton を読み取る必要があります。

namespace Acme.Controls
{
  sealed class FullExtentButton : Button
  {
  }
}

<button id="acme_FullExtent" caption="Full Extent" className="Controls.FullExtentButton" 
        loadOnClick="true" 
        smallImage="Images\GenericButtonBlack16.png" 
        largeImage="Images\GenericButtonBlack32.png">
</button>

次の Pro UI 要素はプラグインから派生しています。

• Button
• ComboBox
• CustomControl
• DynamicMenu
• EditBox
• Gallery
• Pane
• DockPane
• Spinner

モジュールは、サブシステムのハブおよび中央アクセス ポイントとして機能します。サブシステム内の機能にアクセスする必要がある場合は、モジュールから始めます。モジュールはシングルトンであり、コードの実行時にアクセスが明示的に要求されたとき、またはコンテキスト シフトのためにモジュールが「関連」になったときに、フレームワークによって自動的にインスタンス化されます。モジュールの一部であるすべてのプログラム要素は、そのように明示的に宣言されています。これらの要素には、リボン ボタン、ツール、ギャラリー、コンボ ボックス、編集ボックス、パレット、その他のコントロール、およびアプリケーション ペインとドッキング ペインが含まれます。モジュールとそれに関連するコンポーネントの間の明確に定義された関係により、アプリケーションはサブシステム全体を初期化、初期化解除、および削除できます。

UI レベルのロジックのほとんどは、モジュールまたはモジュールが直接管理するヘルパー（非 UI）クラスに存在する必要があります。たとえば、ボタンを作成する場合、ボタン クラス自体にビジネス ロジックを含めることはできません。すべてのロジックは、その親モジュールに集中化する必要があります。ビジネス ロジックを一元化すると、スパゲッティ現象が減少します。たとえば、それぞれが特定のイベントをリッスンする複数のボタンの代わりに、1 つのモジュールにイベントをリッスンさせ、代わりに各ボタンが OnUpdate でモジュールをポーリングすることをお勧めします。

モジュールは、ビジネス ロジックの集中化をはるかに容易にするいくつかのパターンもサポートします。たとえば、モジュールは、プラグインの 1 つがロードされるたびに自動的にロードされます。たとえば、ほとんどの場合、リボンのボタンはクリックされるまで読み込まれません。これが発生すると、ボタンの親モジュールもロードされます。同様に、ドッキング ペインが読み込まれると、その親モジュールも読み込まれます。

モジュールは、その構成アイテムの1つが作成されると、自動的にロードされます。たとえば、ユーザーがボタンをクリックしたためにボタンが作成された場合、その親モジュールもインスタンス化されます。モジュールは、コンテキストに基づいてロードすることもできます。モジュールがコンディションを指定する場合、アプリケーションのステートがそのコンディションを満たしたときに、フレームワークは自動的にモジュールを作成します。コンディションに基づいてモジュールをロードすると、アプリケーションのイベントに基づいてロードしたいが、イベントをリッスンするオブジェクトを作成（および dll をロード）したくないシナリオで役立ちます。

モジュールには、ペインを操作するためのパターンもあります。モジュールは、そのペインの1つがアクティブ化、非アクティブ化、開かれる、または閉じられるたびに自動的に通知されます。これは、モジュールがフレームワークの ActivePaneChanged イベントをリッスンして、関連するペインをフィルタリングする必要がないことを意味します。代わりに、モジュールには、ペインの1つが変更されたことが直接通知されます。

通知を受信するには、以下をオーバーライドします。

  protected override void OnPaneClosing(Pane pane, CancelRoutedEventArgs e);
  protected override void OnPaneClosed(Pane pane);
  protected override void OnPaneOpened(Pane pane);
  protected override void OnPaneActivated(Pane incomingPane);
  protected override void OnPaneDeactivated(Pane outgoingPane);

詳細については、ArcGIS Pro API Reference Guide を参照してください。

モジュールはルート ArcGIS 要素内で宣言されますが、モジュールのコンテナ要素内でさらに囲む必要があります。autoLoad属性は、モジュールが自動的にジャスト イン タイム（JIT）-デフォルト-、または、アプリケーションの起動時にロードされているかどうかを制御するために使用されます。ほとんどすべての場合、autoLoad は false に設定する必要があります。

  <modules>
    <insertModule id="acme_mainModule" caption="Acme" 
                  className="MainModule" autoLoad="false">
      <!--Declare additional customizations here..-->
    </insertModule>
  </modules>

新しいモジュールを宣言する場合、insertModule 要素内に含まれるすべての構成プラグイン宣言は暗黙的に挿入されるため、要素名の insert プレフィックスは省略できます（たとえば、insertButton は単純な button になります）。

モジュールは、リボン内のボタンの作成を簡素化するためのパターンであるDelegateCommands をサポートします。抽象ボタンクラスを継承する完全なボタン プラグイン クラスを作成する代わりに、ボタンが実際にはモジュール クラスの静的メソッドにすぎないことを宣言できます。

以下のサンプルでは、​​OnCustomButtonClick という名前の静的メソッド（Module1 クラス上）を使用して DelegateCommand を実装しています。DAML では、ボタン要素の className 属性は、モジュールの ID に加えて、コロン '：' で区切られた呼び出す静的メソッドの名前を保持します。

  <insertModule id="MyAddIn_Module" className="Module1" autoLoad="false" caption="Module1">
     <tabs>...</tabs>
     <groups>...</groups>
     <controls>
        <button id="MyAddIn_Module_Button" className="MyAddIn_Module:OnCustomButtonClick" 
           caption="Button1" largeImage="Images\GenericButtonBlack32.png" 
            smallImage="Images\GenericButtonBlack16.png">
           <tooltip>Tooltip text</tooltip>
       </button>
     </controls>
  </insertModule> 

Module1.cs では、静的メソッド OnCustomButtonClick は OnClick ハンドラーを実装します。

  internal class Module1 : Module {
     //Delegate command OnClick handler
     internal static void OnCustomButtonClick() {
          System.Diagnostics.Debug.WriteLine("Button clicked");
     }
   

DelegateCommand の「応答」メソッドは通常、プライベートまたはインターナルである必要があることに注意してください。

DelegateCommands は、bool を返す静的プロパティを介して OnUpdate 機能を追加でサポートできます。プロパティは、プレフィックス Can が付いたDelegateCommand OnClick メソッドと同じ名前である必要があります。

この例では、OnClick メソッドは OnCustomButtonClick と呼ばれるため、プロパティは **Can**OnCustomButtonClick と呼ばれる必要があります。

  internal class Module1 : Module {
     private static bool _isEnabled = true;
  
     //Delegate command OnClick handler
     internal static void OnCustomButtonClick() {
          System.Diagnostics.Debug.WriteLine("Button clicked");
     }
  
     //Delegate command OnUpdate implementation
     internal static bool CanOnCustomButtonClick {
        get {
            //Module1 code must keep '_isEnabled' current
            return _isEnabled;
        }
     }

プロプライエタリ ライセンス ロジックを実装したいアドイン開発者は、構成可能なエクステンション を実装することで実装できます。構成可能なエクステンションは10.x で導入され、開発者はアドインを ArcMap エクステンション ダイアログ ボックスに追加できるようになりました。ArcGIS Pro は、Pro アドイン開発者に同じフレームワークを提供します。

Pro で構成可能なエクステンション パターンを実装するアドインは、ArcGIS Pro アプリケーションのバックステージの[ライセンス]タブに外部エクステンションとして表示されます。

ユーザーがバックステージから構成可能なエクステンションを有効にしようとすると、サードパーティの開発者は IExtensionConfig（10.xと同じ）を介してカスタム ライセンス コードを実行し、有効化アクションが許可されているかどうかを判断できます。

アドインの構成可能なエクステンションの実装は、2段階のプロセスです。

1. Config.daml ファイルの<insertModule ...></insertModule>要素内に<extensionConfig .../>要素を追加します。
2. IExtensionConfigModuleクラスに実装します（オプション 、必須ではありません）。

<extensionConfig .../>DAML要素は、あなたのアドインのライセンス タブ外部エクステンション リスト エントリの内容を制御します。製品名とメッセージは、IExtensionConfig 実装内で動的に更新できます（ステータスを示すなど）。製品名とメッセージは、（リスト エントリの）有効なチェック ボックスがクリックされるたびに更新されます。

たとえば、以下に示す DAML は、次の外部エクステンション リスト エントリになります。

extensionConfig hasExtendedInfo 属性が true に設定されていることに注意してください。これはアドインがアドイン モジュールに IExtensionConfig が実装されていることを Pro に通知します。hasExtendedInfo 属性を true に設定しないと、アドイン モジュールの IExtensionConfig 実装はすべて無視されます。DAML の <extensionConfig ... hasExtendedInfo="false"/> 要素を持つアドインは、[ライセンス]タブに永続的に有効になっているものとして一覧表示されます（無効にすることはできません）。

IExtensionConfig 実装については、ProGuide License Your Add-in で詳しく説明されています。

デフォルトでは、アドイン モジュールは JIT でロードされます（<modules><insertModule .... autoLoad="false">...）。構成可能なエクステンションであるアドインも JIT でロードでき、自動ロードする必要はありません（つまり autoLoad="true"）。JIT がロードされたアドインは、アクティブ化されたときにカスタムの有効化（またはライセンス）ロジックを実装します。アクティベーションは次の場合に発生します。

1. カスタム UI コンポーネントのいずれかが UI（ボタン、タブなど）をクリックされるか、表示されます（ドッキング ペイン、ペインなど）
2. ArcGIS Pro の[ライセンス]タブがバックステージで開きます。

有効化またはライセンス ロジックを実行するのに便利な場所は、アドイン モジュールのコンストラクターです。アドイン エクステンション ステートは、次の3つの値のいずれかに設定できます。

• Enabled：開発者は、基盤となるアドイン機能を有効にする必要があります。
• Disabled：開発者はアドイン機能を無効にする必要があります。
• Unavailable：エクステンションは無効になっており、バックステージから有効にすることはできません。開発者は、Pro セッション全体でアドイン機能を無効にする必要があります（つまり、Unavailable ステートをクリアするには再起動が必要です）。

アドイン開発者は、対応するエクステンション ステートがアドイン内でどのように伝播されるかを決定する責任があります。推奨される方法は、コンディションを使用してアドイン機能を有効または無効にすることです。

構成可能なエクステンションを実装する方法の詳細については、ProGuide License Your Add-inを参照してください。

フレームワークには、ユーザー定義のコンディションに基づいてカスタマイズのアクティブ化をトリガーするメカニズムが組み込まれています。従来のイベントやコールバックとは異なり、コンディションとカスタマイズの間のバインディングは、DAML を使用して静的に（宣言的に）提供されます。このメカニズムは、リボン タブ、ドッキング ペイン、ボタン、ツールなどのさまざまな GUI 要素をアプリケーション内で表示または有効にする必要がある場合としない場合を表すための簡略化された宣言型の手段を提供します。ここでの目標は、現在進行中のアクティビティに合わせて「調整」された整頓されたユーザー インターフェイスを提示することです。コンディションを使用すると、コード モジュールとそれに関連するリソースが、関連する場合にのみロードおよび消費されるようになります。

コンテキスト トリガー アクティベーションが実際にどのように機能するかを説明する前に、2 つの重要な用語を定義する必要があります。

State—ステートは、アプリケーションの全体的な状況の特定の側面を象徴するブール値を命名しています。たとえば、特定のビューがアクティブであるかどうか、または特定のタイプのフィーチャが選択されているかどうかです。ステートは通常の文字列を使用して宣言されます。名前の衝突を避けるために、通常、プラグインの命名規則を使用して名前が付けられます。

Condition—コンディションは、（A または B）などの 1 つ以上のステートで構成されるDAML式であり、A と B の両方がステートです。コンディション自体は、コンディションの使用を許可する DAML 要素から参照できるように名前が付けられています。たとえば、カスタム リボン タブは、マップ ビューがアクティブな場合は自動的に表示され、他のタイプのビューがアクティブな場合は非表示になります。

ステートとコンディションは、次のように DAML 要素を使用して宣言されます。

単純なコンディション（1 つのステートのみで構成される）：

  <conditions>
    <insertCondition id="aSimpleCondition">
      <state id="someState"/>
    </insertCondition>
  </conditions>
  
  A more complex condition:
  
  <conditions>
    <insertCondition id="aMoreComplexCondition">
      <and>
        <state id="someState"/>
        <or>
          <state id="someOtherState"/>
          <state id="yetAnotherState"/>
        </or>
      </and>
    </insertCondition>
  </conditions>

上記のコンディションは、「someState AND (someOtherState OR yetAnotherState)」と評価されます。

コンディションは、モジュール ブロックのスコープ外の DAML ファイルのルート レベルで定義されます。これは、コンディションが単なる式（アクティブなアスペクトなし）であり、モジュールのコントロールに関連付ける必要がないためです。コンディションは、範囲がグローバルであると見なす必要があります。ブール演算子 And、Or、Not は、必要に応じて再帰的に組み合わせて複雑な条件式を形成できますが、別のコンディション ブロック内のステートの代わりにコンディション自体を（再帰的に）使用することはできません。

コンディションは、condition 属性を使用して特定のプラグインに関連付けられます。次の XML フラグメントは、アクティブなビューがマップビューである場合は常に、このタブが表示されるように指定しています。

  <tab id="myTab" caption="New Tab" condition="esri_mapping_MapView"/>

フレームワークは、コンディションを使用してトリガーできるアクティブ化動作の固定セットを定義します。ステートはステート テーブルで維持されます。ステートはステートがテーブルに存在する場合は activated 、それ以外の場合は deactivated と呼ばれます。アプリケーションの実行中、フレームワーク内のステート テーブルは定期的に変更がないか監視されます。変更が検出されると、テーブルは現在定義されているコンディションと照合され、それに応じて適切なactivated（またはdeactivated）がトリガーされます。

次の表は、現在定義されているアクティベーション動作と、それらが適用されるプラグインのタイプをまとめたものです。

ステートは暗黙的または明示的のいずれかです。暗黙のステートとは、フレームワーク自体によって本質的に定義およびコントロールされるステートです。これらのステートは自動的にアクティブ化および非アクティブ化されます。

明示的なステートは、開発者が提供するコードを使用して手動で設定されます。これらのステートの意味は通常、開発者によって定義され、カスタム モード（「編集中」）やカスタム ステータス（「ラスター レイヤーが TOC で選択されている」）など、より具体的なタイプのコンテキストを識別するために使用されます。

明示的なステート変更は、State オブジェクトで Activate または Deactivate を呼び出すことによって行われます。

  // Called when a raster layer is selected.
  State.Activate("esri_core_RasterLayerSelected");  
  
  // Called when editing mode is exited.
  State.Deactivate("esri_core_EditingModeExited");  

ステート テーブルは、フレームワーク内の2つのレベル（アプリケーション レベルのステートとペイン レベルのステート）で維持されます。各ペインには、そのインスタンスにのみ関連するステートが含まれている場合があり、ユーザーが単に別のペイン（現在の選択や現在のツールなど）に切り替えた場合は変更しないでください。このため、各ペイン インスタンスは、Pane クラスを介してアクセスできる独自のステート テーブルを維持します。

  // Deactivate a state associated with a particular view.
  Pane.State.Deactivate("esri_mapping_FeatureSelected");  

アプリケーション レベルのステートには、現在アクティブなビューや、特定のモジュールが現在ロードされているかどうかなど、アプリケーション全体に関連するグローバル ステートが含まれます。アプリケーションレベルのステートには、Application クラスを介してアクセスします。

  // Activate a state associated the application as a whole.
  Application.State.Activate("esri_mapping_DigitizerEnabled");  

コンディションの一致中、フレームワークは常にアプリケーション レベルに関連付けられたステートと、現在アクティブなペインに関連付けられたステートを考慮します。したがって、その式がこれら2つのテーブルの組み合わせで肯定的に評価される場合、コンディションは満たされます。適切なレベルでステートをアクティブ化または非アクティブ化することが重要です（ステートのタイプに応じて）。

コンディションとステートの詳細については、ConditionQuery コミュニティ サンプルを参照してください。

フレームワークは、特定のカテゴリにコンポーネントを登録するためのメカニズムをサポートしています。このメカニズムは、レジストリ設定ではなく DAML 宣言に依存しています。Pro は（作図ツールの作成に使用される esri_editing_construction_point, esri_editing_construction_polyline, esri_editing_construction_polygon のような）定義済みカテゴリのセットが含まれていますが、開発者は独自のカテゴリを作成することができます。

Pro カテゴリ内にDAMLコマンド（ボタンなど）を登録するには、ターゲットカテゴリのIDを含む必要があるcategoryRefID属性を使用します。以下の例では、ツールがポリゴンの編集作図ツールカテゴリに登録されています。

 <controls>
   <tool ... categoryRefID="esri_editing_construction_polygon" caption="Buffered Line">
     <tooltip heading="Buffered Line">
               Create a polygon with a fixed buffer.<disabledText /></tooltip>
     <content toolOptionsID="ConstructionToolWithOptions_BufferedLineToolOptions" />
   </tool>
 ...

実行時に、編集は作図ツールのカテゴリ（ポイント、ポリライン、ポリゴンなど）をスキャンし、見つかった作図ツールのインスタンスを、フィーチャ作成ドッキング ペインの適切な作図ツール パレットに追加します。このカテゴリの使用により、Pro は、どのコマンドがどのカテゴリに登録されているかによって、さまざまなメニューとオプションを動的に構成できます。

特定のカテゴリでは、カテゴリの参加者が <content .../>xml サブ要素の形式でカスタムデータを提供することもできます。そのカスタムデータは何か、その形式はカテゴリによって異なります。編集作図ツールの例に戻ると、作図ツールコマンドはtoolOptionsID、（カテゴリ）「content」サブ要素を介して提供されます。編集は、提供された toolOptionsID を使用して（提供されたものを想定して）作図ツールオプションビューを起動し、その esri_editing_tool_options カテゴリでビューを検索します。Config.damlのDAMLエントリは次のようになります。

 <controls>
    <controls>
   <tool ... categoryRefID="esri_editing_construction_polygon" caption="Buffered Line">
     ...
     <content toolOptionsID="ConstructionToolWithOptions_BufferedLineToolOptions" />
   </tool>
 ...
    ...
    </controls>
   </insertModule>
<modules/>
<categories>
    <!-- the options view model + view are registered in the "esri_editing_tool_options" 
         category -->
    <updateCategory refID="esri_editing_tool_options">
      <insertComponent id="ConstructionToolWithOptions_BufferedLineToolOptions" ...>
        <content className="BufferedLineToolOptionsView" />
      </insertComponent>
  ...

(完全な例は Editor Construction Tool With Options sample にあります)

コマンドは categoryRefID 属性を使用しますが（基本的に、リボンでホストできるほとんどのDAML要素はコマンドと見なされますが、最も一般的なコマンドはボタンとツールです）、カテゴリに登録する必要があるカスタムコンテンツは <insertComponent ...> 要素を使用します。

カスタムの「BufferedLineToolOptions」は <insertComponent ...> 要素を使用してカスタム UI を esri_editing_tool_options カテゴリ内に登録することに注意してください（BufferedLineToolOptions は「埋め込み可能なコントロール」を使用しています。詳細については、ProGuide Using Embeddable Controls を参照してください）。コンポーネントをカテゴリに追加するには、更新するカテゴリの ID または「refID」で識別される <updateCategory ...> 子要素を含む <categories> セクションを Config.daml に追加し、登録するコンテンツ要素ごとに1つずつ <insertComponent ...> 子要素を追加します。

埋め込み可能なコントロールの場合のように、登録されているコンテンツが「ViewModel-View」ペアで構成されている場合、<insertComponent ...> 要素 ID はViewModel を識別します。View を識別するには className 属性を持つ子 <content...> 要素が必要です。

<categories>
  <!-- A custom embeddable control is added to the "esri_editing_tool_options" category to
      allow the Buffered Line construction tool to show a custom options UI on the 
      create dock pane -->
    <updateCategory refID="esri_editing_tool_options">
      <!-- This is the View model -->
      <insertComponent id="ConstructionToolWithOptions_BufferedLineToolOptions" 
          className="BufferedLineToolOptionsViewModel">
        <!-- This is the View (User Control) -->
        <content className="BufferedLineToolOptionsView" />
      </insertComponent>

バッファー ライン ツールがフィーチャ作成ドッキング ペインesri_editing_tool_options でアクティブ化されると、その埋め込み可能なコントロールが編集によってアクティブ化され、ユーザーは特定のバッファ距離を入力できるようになります。

開発者は、DAML で独自のカテゴリを作成し、その中に独自のコンポーネントを登録できます。最初に、カスタム カテゴリがDAMLで宣言されます。カテゴリは純粋な宣言型であり、アクティブな部分（コードビハインド）はありません。次の DAML フラグメントは、「ProjectContainers」と呼ばれるカテゴリのカテゴリ宣言の例を示しています。

  <categories>
    <insertCategory id="ProjectContainers"/>
  </categories>

カスタム コンポーネント（汎用 C# クラス、埋め込み可能なコントロールなど）は、前述のように <insertComponent ...> 要素を使用して、config.daml 内のカテゴリにタイプを登録します。カテゴリに登録されると「定める」要件、つまりコントラクトは、カテゴリの作成者（つまり「あなた」）によって定義されます。コントラクトは、抽象クラスまたはインターフェースとして定義できます。この例では、ProjectContainers カテゴリは、カテゴリ コンポーネントが派生し、実装/オーバーライドする必要があるコントラクトに抽象クラス ProjectItemContainers を使用します。名前は完全に任意です。

//ProjectContainers components must derive from "ProjectItemContainers"
public abstract class ProjectItemContainers {
   public virtual string Foo(string name, string path, string type, string data);
}

ProjectContainers のカテゴリ コンポーネントを作成するには、カスタム MapContainer クラスを実装し、ProjectItemContainers から継承する必要があります。この場合、これは関連する仮想メソッド Foo() を実装（オーバーライド）します。インターフェイスがコントラクトとして使用されている場合、MapContainer クラスはインターフェイスを実装することが期待されます。

  //Derive from ProjectItemContainer 
  public sealed class MapContainer : ProjectItemContainer {
    . . .

    public override Item Foo(string name, string path, string type, string data) {
       //TODO implement Foo as required
    }

アドインで完成した MapContainer クラスは、前述のように、<categories> セクションと <insertComponent ...> 要素内の config.daml のカテゴリに登録されます。

<categories>
  <updateCategory refID="ProjectContainers">
    <!-- our custom MapContainer class that derives from ProjectItemContainer -->
    <insertComponent id="MapContainer" className="MapContainer">
      <content type="Map" displayName="Maps"/>
    </insertComponent>
  </updateCategory>
</categories>

実行時に、ProjectContainers カテゴリの作成者は、フレームワークが提供するCategories.GetComponentElements メソッドを使用して、登録されているすべてのコンポーネントを列挙します。コンポーネントは、同じまたは異なるアドインに含めることができます。Categories.GetComponentElements は通常、アドインのライフサイクルの早い段階（Module.Initialize 内など）で呼び出され、1回だけ呼び出す必要があります。コンポーネントはカテゴリ内で動的に登録できないため、セッション内でこのメソッドを繰り返し呼び出す意味はありません。GetComponentElements メソッド（この場合は「ProjectContainers」）のパラメーターとして、ID をコンポーネントカテゴリに渡します。GetComponentElements は、指定されたカテゴリ内で見つかったエントリごとに、ArcGIS.Desktop.Framework.ComponentElementインスタンス(API リファレンス topic10086.html )を返します。

返された各コンポーネント要素をテストして、コントラクトの存在を確認します（インターフェイスまたは抽象クラス、あるいはその両方）。コンポーネントが返されるときに、ComponentElement.GetContent() を呼び出して Systm.DAML.Linq.XElement コンテンツ サブ要素ノード（存在する場合）を取得するか、component.ReadAttribute を使用してコンテンツ要素から直接属性値を読み取ることもできます。コンポーネントの新しいインスタンス（この場合は「MapContainer」クラスのインスタンス）をインスタンス化するために ComponentElement.CreateComponent() を呼び出します。CreateComponent 呼び出しが失敗した場合、例外がスローされます。

  Collection<ArcGIS.Desktop.Framework.ComponentElement> components;
  components = Categories.GetComponentElements("ProjectContainers");
  
  // Check the components
  foreach (ComponentElement component in components)
  {
    //read the value of the <content type="" ...> attribute
    string value = component.ReadAttribute("type");
    if (value != key)
      continue;//category components that do not provide a "type" are skipped
  
    //ProjectItemContainers have a two stage creation mechanism
    ProjectItemContainer container = null;
    try
    {
      //test the component element for "ProjectItemContainer"
      container = component.CreateComponent() as ProjectItemContainer;
      if (container == null) {//"container" is NOT a ProjectItemContainer
        continue;//Skip component - throw exception etc
      //TODO - hold on to the instance of your ProjectItemContainer, eg in 
      //a list...

カスタム カテゴリの 2 つの完全に機能する例は Pro SDK サンプルにあります。

• Configure Gallery
• Custom Categories

Configure Gallery は、ボタンとツールを Pro のリボンのギャラリーに構成ロードするためのカスタム カテゴリの実装を示しています。Custom Categories は、Pro ウィンドウを構成するためのカスタム カテゴリの実装を示しています。

バックステージは、アプリケーションと現在のプロジェクトの追加機能を公開するフル スクリーンのユーザー インターフェイス ビューです。バックステージはタブとボタンで構成されています。各タブは特定のタスクにスコープされ、独自のユーザー インターフェイスを表示します。ボタンは、操作を実行する単なるコマンドであり、バックステージに追加のユーザー インターフェイスはありません。

バックステージのタブも状況に応じて表示され、満たされていないコンディションを指定すると無効になります。

ペイン、ドッキング ペイン、およびプロパティ ページと同様に、カスタムのバックステージ タブには、2 つのコンポーネントがあります。BackstageTab から派生するコンポーネント クラスと、FrameworkElement から派生するビュー クラス（通常はUserControl）です。バックステージ タブは DAML で定義する必要があります。

  <backstage>
    <insertButton refID="acme_Save"/>
    <insertTab id="acme_Open"
                caption="Open"
                className="AcmeOpenProjectCmd"
                keytip="OO">
      <content className="AcmeOpenProjectView"/>
    </insertTab>
    <insertButton refID="acme_Exit"/>
  </backstage>

目に見えるすべてのリボン コントロールは、個々のコントロールを表すため、controls要素の下で宣言されています。残りのリボン コントロールはコンテナ コントロールです。つまり、コントロールのコレクションを保持します。たとえば、メニューはコントロールのリストです。各タイプのコンテナ コントロールには、DAML に独自のセクションがあります。

ギャラリーは、関連するアイテムまたはコマンドのコレクションをリボンに表示するコントロールです。ギャラリー内のアイテムが多すぎる場合は、展開矢印が表示され、コレクションの残りの部分が展開されたペインに表示されます。ギャラリーは通常、提供される選択肢のより豊富な表現を提供し、それぞれが選択された場合の結果のプレビューを表すことがよくあります。ギャラリーは、複数の行と列を同時に表示するように編成でき、メニューによって提供される小さな1次元領域に制約されたくない場合に最適です。

次の画像は、ベースマップのドロップ ダウン ギャラリーを示しています。

ギャラリーは、インライン ギャラリー表現を使用して、リボン上に凝縮されたグリッドを表示できます。この方法で提示されるアイテムは、実装に応じて、最も一般的なアイテムまたは最近使用されたアイテムのいずれかであることがよくあります。次の画像は、レイヤー テンプレートのインライン ギャラリーを示しています。

ギャラリーの実際のコンテンツは、実行時に入力されます。キャプション、ドロップ ダウン イメージ、アイテム サイズの制約、ツール チップなどの比較的静的な側面は、宣言的に指定されます。itemSizeString がギャラリーに表示される項目の最大幅を指定するために使用されます。

 <gallery id="esri_mapping_basemapGallery" className="Ribbon.BasemapGalleryViewModel"
   caption="Basemap" extendedCaption="Choose basemap" keytip="BM" 
   itemsInRow="3" helpContextID="" loadingMessage="Loading..." 
   itemWidth="140" itemHeight="115" 
   dataTemplateFile=
     "pack://application:,,,/ArcGIS.Desktop.Mapping;component/Map/Ribbon/GalleryTemplates.xaml"
   templateID="BaseMapTemplate" showItemCaption="true" showItemCaptionBelow="true"
   resizable="true" condition="esri_mapping_BasemapGalleryCondition"
   largeImage="Images/Basemap32.png">
   <tooltip heading="">
    Choose a basemap for your map. The basemap is the reference data that displays under the notes and other 
    GIS data you have added to the map.<disabledText></disabledText>
   </tooltip>
 </gallery>

ギャラリー アイテムは通常、GalleryItem クラスを介してモデル化されます。GalleryItem には、Icon, LargeIcon, Text, Group, Tooltip のプロパティがあります。カスタム GalleryItems は、必要に応じて追加のプロパティや動作をカプセル化するために継承を通じて作成できます。ギャラリー アイテムは、ItemTemplate を介して UI に表示されます。

レスポンシブ UI エクスペリエンスをより適切にサポートするために、フレームワークは、多数のアイテムを非同期でロードしようとしているときに、待機中のスピナーとロード メッセージをギャラリーのドロップ ダウン リストに提供します。LoadingMessage は、実行時に更新するか、LoadingMessage 属性を使用して静的に設定できます。このデフォルトの動作を取得するには、UI スレッドをブロックし、スピナーが表示されないようにするため、ギャラリーのコンストラクターに重いコードを配置しないでください。読み込みメッセージは、ドロップ ダウン ギャラリーにのみ表示されます（インライン ギャラリーには表示されません）。

ItemCollection に追加されたすべてのアイテムは、最終的にギャラリー ポップアップ コントロールに追加されたボタンのコンテンツになるため、メイン UI スレッドで作成する必要があります。

ギャラリーは、DAML の galleries 要素の下で宣言されます。

  <gallery id="acme_MapGallery" 
     className="acme_Maps"    
     caption="Maps" 
     itemsInRow="3" 
     itemWidth="140" 
     dataTemplateFile="pack://application:,,,/Acme;component/Styles/GalleryTemplates.xaml" 
     templateID="BaseMapTemplate" 
     showItemCaption="true" 
     resizable="true" 
     largeImage="Images\Basemap32.png">
    <tooltip>Choose a map.</tooltip>
    <button refID="acme_Button1"/>
    <button refID="acme_Button2"/>
  </gallery>

ギャラリーには、追加のオプションを表示するメニューを含めることもできます。このメニューには、別のネストされたギャラリーを含めることができます。

ギャラリーは、フレームワークの Gallery 基底クラスから継承することによって実装されます。

  sealed class MapGallery : ArcGIS.Desktop.Framework.Contracts.Gallery
  {
    private bool _initialized;
  
    protected override void OnDropDownOpened()
    {
      LoadItems();
    }
  
    private void LoadItems()
    {
      if (_initialized)
        return;
  
      for (int x = 0; x < 28; x++)
      {
        GalleryItem galleryItem = new GalleryItem("GalleryItem " + x.ToString(), 
              null, "tip: " + x.ToString());
        this.Add(galleryItem);
      }
      _initialized = true;
    }
  
    protected override void OnClick(GalleryItem item)
    {
      System.Windows.MessageBox.Show(item.Text);
    }
  }

ギャラリーは、宣言でカスタム テンプレートを指定できます。単純なデフォルト テンプレートは、1 つを指定しないすべてのギャラリーに使用されます。このテンプレートは、GalleryItems のコレクションを想定しています。独自のアイテム テンプレートを使用している場合は、適切なタイプでコレクションを埋めることができます。カスタム テンプレートを指定するときは、ファイルとそのキーをリストする必要があることに注意してください。

前の例を考えると：

  <gallery id="esri_mapping_basemapGallery" ...
   dataTemplateFile="pack://application:,,,/ArcGIS.Desktop.Mapping;component/Map/Ribbon/GalleryTemplates.xaml"
   templateID="BaseMapTemplate">
       <tooltip heading="">
              ...
       </tooltip>
  </gallery>

このギャラリーは、キー BaseMapTemplate を持つ DataTemplate GalleryTemplates.xaml を使用します。テンプレートは次のようになります。

  <!-- In GalleryTemplates.xaml -->
  
  <ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
  
  <DataTemplate x:Key="BaseMapTemplate">
    <Grid>
      <StackPanel Orientation="Vertical" Margin="5,0,5,0">
        <Grid Margin="5">
          <Image Source="{Binding Thumbnail}" MaxHeight="87" MaxWidth="120">
            <Image.Effect>
              <DropShadowEffect Color="#FF565454" Opacity="0.4" />
            </Image.Effect>
          </Image>
        </Grid>
        <TextBlock Text="{Binding Title}" HorizontalAlignment="Center" />
      </StackPanel>
    </Grid>
  </DataTemplate>
  
  ...

または、データに複数のデータ テンプレートがある場合は、パブリック DataTemplateSelector を作成し、そのリソース キーを templateID として指定できます。これを行うには、次のような DataTemplateSelector クラスを実装する必要があります。

  public class BaseMapTemplateSelector : System.Windows.Controls.DataTemplateSelector
  {
    public DataTemplate BaseMapTemplate { get; set; }
    public DataTemplate OtherMapTemplate { get; set; }

    public BaseMapTemplateSelector(){}
    ///<summary>When overridden in a derived class, returns a System.Windows.DataTemplate 
    ///based on custom logic.</summary>
    ///<returns>Returns a System.Windows.DataTemplate or null. The default value is null.
    ///</returns>    
    public override DataTemplate SelectTemplate(object item, DependencyObject container)
    {
      BaseMap basemap = item as BaseMap;
      if (basemap != null)
        return this.BaseMapTemplate;

      return this.OtherMapTemplate;
    }
  }

DataTemplateSelector は、GalleryTemplates.xaml で使用するテンプレートを指定します。

  <DataTemplate x:Key="BaseMapTemplate">
    ...
  </DataTemplate>
  <DataTemplate x:Key="OtherMapTemplate">
   ...
  </DataTemplate>
  
  <testAppGallery:BaseMapTemplateSelector 
       BaseMapTemplate="{StaticResource BaseMapTemplate}"
       OtherMapTemplate="{StaticResource OtherMapTemplate}"
       x:Key="BaseMapTemplateSelector"/>
  

次に、リソースキーを templateID: templateID="BaseMapTemplateSelector" として指定します。

  <!-- DAML -->
  <gallery id="esri_mapping_basemapGallery" ... 
     dataTemplateFile="..." templateID="BaseMapTemplateSelector">
  </gallery>

データ テンプレートまたはテンプレート セレクターは、Gallery または ComboBox の基底クラスで次の方法で設定することもできます。

  public object ItemTemplate { get; set; }

リボン内ギャラリー自体だけでなく、ギャラリー アイテムのツールチップを指定するには、ギャラリー データ テンプレートで ActiPro ScreenTipService 添付プロパティを使用します。

  <ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:ribbon="http://schemas.actiprosoftware.com/winfx/xaml/ribbon">
  
     <DataTemplate x:Key="BaseMapTemplate">
        <Grid ... 
        ribbon:ScreenTipService.ScreenTipHeader="{Binding Name}" 
        ribbon:ScreenTipService.ScreenTipDescription="Some description">
  
       ...
       <!--<Grid.ToolTip> DO NOT DEFINE TOOLTIP IN THIS WAY
          <TextBlock Width="Auto" Text="{Binding Name}" />
       </Grid.ToolTip>-->
       ...

メニューは純粋に宣言型であり、menus 要素の下に追加されます。メニューには、ボタン、動的メニュー、ギャラリー、その他のメニューなど、さまざまなコントロールを含めることができます。宣言されると、メニューには ID、キャプション、および画像が割り当てられます。 最初に定義されたとき、すべてのメニュー項目は、表示される順序でメニュー要素内に単純にリストされます。

  <menu id="acme_mainMenu"
        caption="Main Menu"
        largeImage="Images\MenuImage32.png"
        smallImage="Images\MenuImage16.png">
    <button refID="acme_paste"/>
    <button refID="acme_pasteSpecial"/>          
  </menu>

既存のメニューは、DAML を使用して簡単に変更できます。以下の例では、menuItem2 の直後に新しいメニュー項目を追加しています

  <menus>
    <updateMenu refID="exampleMenu">
      <insertButton refID="menuItem2a" placeWith="menuItem2" insert="after"/>
    </updateMenu>
  </menus>  

メニューを参照し、属性 inline="true" を設定することで、同じメニューを他のメニューと共有できます。

  <menu id="changeCase" caption="Change case">
    <button refID="bold"/>
    <gallery refID="pasteGallery" inline="true"/>
    <button refID="Save"/>
  </menu>
  
  <menu id="mainMenu" caption="MainMenu">
    <menu refID="changeCase" inline="true"/>
    <button refID="ShowPeopleSheet" separator="true"/>
  </menu>
  <menu id="AnotherMenu" caption="AnotherMenu">
    <button refID="Save" separator="true" />
    <gallery refID="pasteGallery"/>
    <menu refID="changeCase" inline="true"/>
    <button refID="ShowPeopleSheet" separator="true"/>
    <dynamicMenu refID="dynoMenu"/>
  </menu>

コンテキスト メニューは、プログラムで取得されるメニューです。これは、<menu ...></menu> 要素を使用して DAML で定義されます。Pro コンテキスト メニューを XAML 要素にバインドして、Pro フレームワークにコンテキスト メニューを取得させることができます。たとえば、Config.daml でこのコンテキスト メニュー定義を指定すると、次のようになります。

  <!-- in the Config.daml -->
  <menu id="acme_module_ContextMenu" caption="Context Menu">
    <button refID="acme_module_Save" separator="true" />
    ...

ビュー モデルでコンテキスト メニュー プロパティ「GetMenu」を定義します。

 public System.Windows.Controls.ContextMenu GetMenu {
   //Create the context menu as needed
   get { return FrameworkApplication.CreateContextMenu("acme_module_ContextMenu"); }
 }

WPF UI（ドッキング ペインのユーザー コントロールなど）では、ビュー モデル プロパティを ContextMenu 要素（この場合はスタックパネル）のプロパティにバインドします。

<StackPanel Orientation="Horizontal" ContextMenu="{Binding GetMenu}">

これで、UI を介してコンテキスト メニューが要求されると（たとえば、この要素を右クリックする）、config.daml で定義されているコンテキスト メニューが表示されます。フレームワークに XAML で 1 つのインラインを宣言する代わりに ContextMenu を作成させることは、DAML で簡単に拡張できることを意味します。ContextMenu の詳細については、MSDN の FrameworkElement.ContextMenu Property を参照してください。

ショートカットキーは "keytip" 属性を使って DAML を通してコンテキスト メニューの項目に割り当てることができます。それは通常、メニュー項目のキャプションの文字の1つです。コンテキスト メニューがポップアップすると、キャプションの最初の文字に下線が引かれます。キーが押されると、対応するコマンドが起動されます。同じコンテキスト メニューの項目に対してキー チップを定義する場合は、衝突を避けるべきであることに注意してください。

<menus>
  <menu id="exampleMenu" caption="SomeMenu" >
    <button refID="menuItem1"/>
    <button refID="menuItem2"/>
    <button refID="menuItem3"/>
  <menu/>
</menus>

<button id="menuItem1" caption="Example" className="SomeClass" keytip="E"/>

コンテキスト メニューは、カタログ ペイン、カタログ ビュー、およびコンテンツ ペイン（別名「TOC」）からコンテキスト（「選択されたもの」）にアクセスできます。[コンテンツ]ペインには、マップとシーンのコンテキストのみが表示されます。レイアウト コンテキストは現在サポートされていません。

カタログ コンテキストを取得するには、最初にフレームワーク アプリケーションからアクティブ ウィンドウを取得します。これは、現在フォーカスがあるドッキング ペインまたはビュー ペインのいずれかになります。ウィンドウを IProjectWindow にキャストします（「as」を使用）。アクティブなウィンドウがカタログ ペインまたはカタログ ビューのいずれかである場合、キャストは成功します。そうでない場合、ウィンドウは null になります。

var window = FrameworkApplication.ActiveWindow as ArcGIS.Desktop.Core.IProjectWindow;

現在選択されているものは、IProjectWindow.SelectedItems メンバーからアクセスできます。0 個以上選択できます。注：アイテムがプロジェクト コンテンツ アイテムである場合は、関連する「ProjectItem」クラス（つまり、マップ、スタイル、レイアウト、シーン、ツール ボックスなどの「プロジェクト アイテム」）にさらにキャストできます。ProConcepts Content and Items を参照してください。

 //get the currently selected item(s) in the catalog pane (note: more
 //than one item can be selected) window will be null if the ActiveWindow is not the 
 //Catalog dock pane or a Catalog view.
 var window = FrameworkApplication.ActiveWindow as ArcGIS.Desktop.Core.IProjectWindow;
 var item = window?.SelectedItems.First();

マップまたはシーンの TOC からコンテキストを取得するには、MapView.Active.GetSelectedLayers() メンバーを使用して現在選択されているレイヤーのリストを取得し、MapView.Active.GetSelectedStandaloneTables() を使用して現在選択されているスタンドアロン テーブルを取得します。

ツールパレットは表面上はメニューですが、関連するツールのセットをグループ化するために特別に設計されています。ツールのパレットからツールを選択すると、そのツールがアクティブなツールになり、新しいパレットボタンとして表示されます。分割ボタンと同様に、パレットは純粋に宣言型であり、実際のボタンとツールのみがアクティブな部分を持っています。

  <toolPalettes>
    <toolPalette id="examplePalette" caption="Example">
      <tool refID="tool1"/>
      <tool refID="tool2"/>
    </toolPalette>
  </toolPalettes> 

パレットにリストされている最初のツールは、パネルに表示される最初のツールです。

分割ボタンは、関連するボタンをグループ化します。分割ボタンの矢印部分をクリックすると、関連するグループが表示されます。リストされている最初のボタンは、コレクションで最も一般的に使用されているボタンであり、リボンに直接表示されます。残りのボタンはあまり使用されておらず、ドロップ ダウン メニューに追加されます。分割ボタンは純粋に宣言型であり、関連するアクション部分はありません。コントロールに参加している各ボタンにはアクティブな部分がありますが、分割ボタン自体はありません。

ドロップダウン リストからコントロールが選択されると、そのコントロールがスプリット ボタンのアクティブ コントロールになります。スプリット ボタンには、シンプルなボタン コントロール、メニュー、ダイナミック メニュー、ギャラリーのいずれかを含めることができます。

  <splitButtons>
    <splitButton id="acme_pasteSplitBtn">
      <button refID="acme_paste" />
      <button refID="acme_pasteSpecial" />
      <button refID="acme_pasteWithFormatting" />
    </splitButton>  
    <insertSplitButton id ="exampleSplitButton">
      <button refID="button1"/>
      <gallery refID="gallery1"/>
      <menu refID="menu1" inline="true" />
      <dynamicMenu refID="dynamicMenu2" inline="false"/>
    </insertSplitButton>
  </splitButtons>

あまり使用されないボタンのコレクションの代わりに、分割ボタンでギャラリーを表示できます。最初の要素はまだボタンです。後で見るように、ギャラリーはさらに独自のボタンメニューを表示できます。

  <splitButtons>
    <splitButton id="acme_pasteSplitBtn">
      <button refID="acme_paste" />
      <gallery refID="acme_pasteGallery" />
    </splitButton>
  </splitButtons>

コントロールには、Button、Tool、CheckBox、ComboBox、EditBox、LabelControl、DynamicMenu、CustomControlなど、アプリケーションリボンに表示できる任意のシンプルなウィジェットが含まれます。すべての単純なリボンコントロールは、モジュールのコントロール要素で宣言されます。コントロールはコントロールセクションで宣言されますが、グループを定義するときに参照されます。これにより、コントロール全体を再宣言しなくても、同じコントロールを複数のグループに表示できます。

次の宣言には、ボタンに関連する最も一般的な属性のいくつかが含まれています。

  <insertModule id="acme_MainModule" className="AcmeMain" caption="Acme">
    <controls>
      <button id="acme_AddFromFileButton"
              className=" AddFromFile"
              caption="From File"
              largeImage="Images\AddFromFile32.png"
              smallImage="Images\AddFromFile16.png">
        <tooltip heading="Add from file" image="Images\AddFromFile16.png">
          Add spatial data files to the project
          <disabledText>Requires an open project with a map</disabledText>
        </tooltip>
      </button>
    </controls>
  </insertModule>

前述のように、フレームワーク プラグインは、自由に存在することは許可されておらず、モジュールとリンクする必要があります。上に示したケースでは、ACME によって作成された新しいボタンが宣言され、モジュールに追加されます。これにより、ボタンがACME モジュールに論理的にリンクされます。ある時点で、フレームワークがモジュールをアンロードする必要があると判断した場合、新しく追加されたボタンもアンロードされます。

プラグイン構成ファイルを使用して既存のコントロールを更新または削除することもできますが、すべての属性を更新できるわけではありません。プラグインの実行時の動作（クラス、アセンブリ、コンディションなど）を変更する可能性のあるものは、insert を介してのみ設定できます。

次の例では、前の例で追加したボタンのキャプションを更新します。

  <updateModule refID="acme_MainModule">
    <controls>
      <updateButton refID=" acme_mapping_AddFromFileButton" caption="New Caption"/>
    </controls>
  </updateModule>

すべてのコントロール要素はいくつかの属性を共有します。loadOnClick のボタンは、フレームワークによって作成されなければならない時に属性が決定されます。デフォルトでは、コントロールは有効になっているように見えますが、クリックされるまで実際にはインスタンス化されません。この単純な JIT ストラテジーは、コントロールのインスタンス化をエンド ユーザーが開始するまで延期することにより、リソースの使用率と起動時間を改善します。非表示のコントロールは、loadOnClick に割り当てられた値に関係なく、表示されるまで（またはプログラムで実行されるまで）ロードされません。

ToolTips は、ToolTip サブ要素を使用して定義され、必要な数の行にまたがることができます。image 属性は、チップ テキストの横に表示される画像を提供するために使用されます。コマンド ツール チップは、disabledText 要素もサポートしています。この文字列は、コマンドが無効になっている場合は常にツール チップになります。

ほとんどのコントロールは、リボンで複数のサイズをサポートしています。たとえば、ボタンは、small（小さいアイコンのみ）、middle（テキスト付きの小さいアイコン）、large（テキスト上の大きいアイコン）をレンダリングできます。異なるサイズのユニークな画像を指定するには smallImage と largeImage 属性を使用します。画像はグラフィックである必要はありません。XAML を使用することもできます。右から左に実行する場合、画像は反転しないことに注意してください。このモードで実行しているときに画像が反転する必要がある場合（矢印ボタンなど）、flipImageRTL 属性を true に設定します。また、overlayLargeImage と overlaySmallImage を使用して、対応する画像の上にグラフィックまたは XAML を描画することもできます。

次の画像は、サポートされている 3 つのサイズの 3 つのボタン（赤い四角）を示しています。

 <button refID="esri_mapping_zoomFullButton" size="small" />
 <button refID="esri_core_editCutButton" size="middle" />
 <button refID="esri_geoprocessing_selectByAttributeButton" size="large"/>

disableIfBusy 要素は、主ワーカー スレッドがビジー状態である時はいつでもコントロールが無効であることを知らせるために使用されます。これにより、作業がキューに入れられるのを防ぎます。この要素はデフォルトで true です。常に有効にする必要があるコントロールは、これを false に設定する必要があります。

すべてのコントロール宣言は、コンディションの割り当てを可能にする condition 属性をサポートします。指定されたコンディションが満たされない場合、コントロールはフレームワークによって自動的に無効になります。さらに、コントロールは、コンディションが満たされるまでアンロードされたままになります。コンディションが指定されていない場合、コントロールは常に関連していると見なされます。詳細については、「コンディションとステート」セクションを参照してください。

コントロールは、適切なプラグインから派生した基底クラスから継承することによって実装されます。

以下に示すButtonクラスは、典型的なコントロールです。仮想 OnClick は、リーフ クラスによってオーバーライドされ、必要なカスタム動作を実行するために使用されます。

  sealed class ShowPeopleSheet : ArcGIS.Desktop.Framework.Contracts.Button
  {
    protected override void OnClick()
    {
      User user = new User();
      user.FirstName = "Michael";
      user.LastName = "Faraday";
      PropertySheet.Show("UserManager", null, user);
    }
  }

コントロールは、実行時にプロパティ（たとえば、キャプションやツール チップ）を更新でき、これらの変更はアプリケーションに自動的に反映されます。

  protected override void OnClick()
  {
    this.Caption = "New Caption";
    this.Tooltip = "New Tooltip";
    this.Checked = true;
  }

FrameworkApplication.GetPlugInWrapper 関数を使用して、実行時にすべてのコントロールにアクセスして更新できます。Checked プロパティは、チェックされた外観を表示するためにボタンとチェック ボックスで使用されます。

  protected override void OnClick()
  {
    IPlugInWrapper wrapper = FrameworkApplication.GetPlugInWrapper("acme_ZoomBtn");
    wrapper.Caption = "New Caption";
    wrapper.Tooltip = "New Tooltip";
  }

アクセシビリティをサポートするには、各コントロールに適切なキーチップを提供する必要があります。選択した1つまたは複数の文字は意味があり、既存のキーチップ（同じリボン上のコントロールの場合）と競合しないようにする必要があります。キーチップは、必要に応じて明確にするために複数の文字で構成できます。

多くのキャプションはあいまいであり、何度も複製される可能性があります（例：FORMAT）。これを解決するには、extendedCaption 属性を使用して詳細を提供します。extendedCaption は、リボンのカスタマイズとタスク ダイアログの 括弧内 のキャプションの横に表示されます。

  <tab id="esri_layouts_polygonFormatTab" caption="FORMAT" extendedCaption="polygons" 
              condition="esri_layouts_polygonCondition" 
              tabGroupID="esri_layouts_polygonTabGroup">
      <group refID="esri_layouts_polygonFormatGroup"/>
      <group refID="esri_layouts_textFormatGroup"/>
      <group refID="esri_layouts_sizeAndPositionGroup"/>
  </tab>

アプリケーション リボンが簡略化モードの場合、コントロールは小さいサイズで描画されます。 キャプションを追加するには、以下のように 'showCaptionOnToolbar' 属性を使用します。 チェックボックスとリボン内ギャラリーは自動的にキャプションを表示します。コンボ ボックスやエディット ボックスなどのいくつかのコントロールは、簡略化モードでのキャプションの表示をサポートしていません。

        <group id="SimplifiedMode_Group1" caption="My Group">
          <splitButton refID="SimplifiedMode_ExploreSplitButton" 
					   size="large" 
					   showCaptionOnToolbar="true" />
        </group>

ボタンは、OnClick イベントに応答する単純なコントロールです。

  <button id="acme_AddFromFileButton"
      className=" AddFromFile"
      caption="Add from file"
      keytip="AF"
      largeImage="Images\AddFromFile32.png"
      smallImage="Images\AddFromFile16.pngg">
    <tooltip heading="Add from file" image="Images\AddFromFile16.png">
      Add spatial data files to the project
      <disabledText>Requires an open project with a map</disabledText>
    </tooltip>
  </button>

ボタンは、Button 基底クラスから派生することによって実装されます。

  sealed class AddFromFile : ArcGIS.Desktop.Framework.Contracts.Button
  {
    protected override void OnClick()
    {
      base.OnClick();
    }
  }

また、overlayLargeImage 属性と overlaySmallImage DAML 属性を使用すると、対応するボタン画像の上にグラフィックや XAML を描画することができます。矢印ボタンなど、画像を右から左に反転させたい場合は、flipImageRTL 属性を true に設定します。

チェック ボックスはボタンとまったく同じように機能します。DAML の checkbox タグを使用して定義され、CheckBox ベースクラスから派生しています。IsChecked プロパティを使用すると、チェックされた外観を与えることができます。

  <checkBox id="acme_AutoSave"
            className="AutoSave"
            caption="Auto Save"
            keytip="AS">
    <tooltip heading="Auto Save" image="Images\AutoSave16.png">Automatically save edits
    </tooltip>
  </checkBox

  internal class AutoSave: ArcGIS.Desktop.Framework.Contracts.CheckBox
  {
    public AutoSave()
    {
      IsChecked = true;
    }

    protected override void OnClick()
    {
      // TODO - add specific customization here as necessary
    }
  }

コンボ ボックスを使用すると、ユーザーはドロップ ダウン リストから項目を選択するか、オプションでコントロールのテキスト ボックスに新しいテキストを入力できます。ComboBox には通常、ComboBoxItem オブジェクトのコレクションが含まれますが、任意のタイプ（文字列や画像など）のオブジェクトのコレクションを含めることができます。

IsEditable と IsReadOnly 属性は、ComboBox の動作を指定します。

ほとんどの場合、コンボボックスは ComboBoxItem オブジェクトで埋められますが、任意のオブジェクトで埋めることができます。カスタム アイテムがコンボ ボックスに追加されるとき、通常、カスタム アイテム テンプレートが使用されます。

  <comboBox id="acme_ComboBox1" 
            caption="ComboBox 1" 
            className="ComboBox1" 
            itemWidth="140" 
            isEditable="false"
            isReadOnly="true" 
            resizable="true">
    <tooltip heading="Tooltip Heading">Tooltip text<disabledText /></tooltip>
  </comboBox>

コンボ ボックスは、ComboBox 基底クラスから派生することによって実装されます。

  sealed class AcmeCombo : ArcGIS.Desktop.Framework.Contracts.ComboBox
  {
    public AcmeCombo()
    {
      FillCombo();
    }
  
    private void FillCombo()
    {
      // Add 6 items to the combobox
      for (int i = 0; i < 6; i++)
      {
        string name = string.Format("Item {0}", i);
        Add(new ComboBoxItem(name));
      }
  
      // Select first item
      SelectedItem = ItemCollection.FirstOrDefault();
    }
  
    protected override void OnSelectionChange(ComboBoxItem item)
    {
      // Do work    
    }
  }

カスタム コントロールを作成するには、一般的な WPF System.Windows.Controls.UserControl を記述し、それを Config.DAML の customControl タグに関連付けます。例えば、

  <customControl id="Module1_CustomControl1" caption="A Custom Control" 
                 className="CustomControlViewModel" loadOnClick="false">
            <content className="CustomControlView"/>
            <tooltip heading="">Illustrates a Custom Control</tooltip>
  </customControl>

アドイン内に DAML で参照されているカスタム コントロールの ViewModel と View を追加します（上記の例では CustomControlViewModel と CustomControlView）。例えば、これは CustomControlView xaml の定義になります。

  <UserControl x:Class="CustomControlView"
               xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
               xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
               xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
               xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
               mc:Ignorable="d" 
               d:DesignHeight="68" d:DesignWidth="90">
      <Grid>
          ...
      </Grid>
  </UserControl>

カスタム コントロールは、DAML の isDropDown 属性をサポートします。これは、カスタム コントロールをドロップ ダウン ボタンのポップアップ ウィンドウ部分として描画するようにフレームワークに通知します。これは、作成者がポップアップ UI を完全に制御できることを除いて、ドロップ ダウン ギャラリーと非常によく似ています。カスタム コントロールの高さは、small グループのアイテム サイズの場合は 22 ピクセル、 large グループのアイテム サイズの場合は 68 ピクセルにする必要があります。

純粋に宣言型（DAMLでのみ定義）である通常のメニューとは異なり、ダイナミック メニューは実行時に入力されます。派生クラスは、メニューが開く前に呼び出されるOnPopup オーバーライドにアイテムを追加する必要があります。ダイナミック メニューには、キャプションと画像で構成される単純なアイテム、または他のダイナミック メニューを含む既存の DAML コントロールへの参照を含めることができます。OnClickオーバーライドは、アイテムがクリックされたときに指定されたインデックスで呼び出されます。ポップアップが閉じると、すべてのメニュー項目がクリアされます。

ダイナミック メニューは、リボンまたは他のメニューに直接配置できます。ダイナミック メニューがメニュー上にあり、inline 属性が true に設定されている場合、アイテムはプルライト サブメニューに追加されるのではなく、ホスティング メニューに直接追加されます。

  <dynamicMenu caption="Acme Menu"
                className="DynoMenu"
                id="acme_dynoMenu"
                largeImage="Images\MenuImage32.png"
                smallImage="Images\MenuImage16.png" >
    <tooltip heading="Heading" image="Images\MenuImage16.png">Some text</tooltip>
  </dynamicMenu>

ダイナミック メニューは、DynamicMenu 基底クラスから派生することによって実装されます。次の例は、追加される 3 つのタイプのボタンを示しています。デリゲート メニュー項目、通常のメニュー項目、およびいくつかの DAML ボタンです。

  sealed class DynoMenu : ArcGIS.Desktop.Framework.Contracts.DynamicMenu
  {
    internal delegate void MathAction(double number);
  
    protected override void OnPopup()
    {
      double angle = 28.0;
  
      MathAction action = Test;
  
      this.Add("item 1", @"pack://application:,,,/Images/Image1.png", true, true, 
               false, action, angle);
      this.Add("item 2", @"pack://application:,,,/Images/Image2.png");
      this.AddSeparator();
      this.AddReference("acme_basicButton");
      this.AddReference("acme_basicMenu");
      this.AddReference("acme_basicGallery");
    }
  
    protected override void OnClick(int index)
    {
      switch (index)
      {
        case 1:
          System.Windows.MessageBox.Show("2nd item");
          break;
      }
    }
  
    private void Test(double angle)
    {
      System.Windows.MessageBox.Show(angle.ToString());
    }
  }

編集ボックスは、ユーザーがリボン タブのコントロール内にテキストを入力するための便利な手段を提供します。編集ボックスは、キャプション付きまたはキャプションなしで表示されるように構成できます。sizeString 属性は、コントロールに表示される入力の種類を表している文字列を介してコントロールの幅を確立するために使用されます。編集ヒントは、実行時に更新することもできます。DataType 属性（string、double、int）を使用して編集ボックスのタイプを指定し、format 属性を使用して数値の表現を制御します。

  <editBox id="acme_Currency" caption="Currency:"
           className="CurrencyEditBox"
           dataType="double"
           format="C" keytip="CC" 
           sizeString="$9.99"/>

編集ボックス コントロールは、EditBox 基底クラスから派生することによって実装されます。

  sealed class CurrencyEditBox : ArcGIS.Desktop.Framework.Contracts.EditBox
  {
    protected override void OnEnter()
    {
      // Do work
    }
  }

C# 形式の例：

  decimal value = 123.456m;
  Console.WriteLine(value.ToString("C2"));
  // Displays $123.46

  value = -12345;
  Console.WriteLine(value.ToString("D"));
  // Displays -12345
  Console.WriteLine(value.ToString("D8"));
  // Displays -00012345

リボンに文字列を追加するだけの場合は、LabelControl を使用できます。

  <labelControl id="acme_label" 
                caption="the quick brown fox jumps over the lazy dog" 
                hasTwoLines="true"/>

スピナー コントロールは、編集ボックスのようですが、インクリメント ボタンとデクリメント ボタンを追加で提供し、minimum 属性と maximum 属性で確立された範囲をサポートします。デフォルト値と増分値を指定することもできます。format 属性を使用して、倍精度浮動小数点数の表示方法を制御します。たとえば、「C」を使用して通貨を表示したり、F4 を使用して小数点以下 4 桁の倍精度浮動小数点数を表示したりします。さらに、suffix 属性を使用して、パーセント記号（％）などの末尾の文字列にタグを付けます。

スピナーは、loadOnClick による遅延ロードをサポートしていません。スピナーは、表示されるとインスタンス化されます。

  <spinner id="acme_spinner" 
           caption="Spin" 
           className="RotateSpinner" 
           format="F1" 
           defaultValue="45"
           maximum="90" 
           minimum="0"
           increment="1" 
           keytip="dz" 
           suffix="&#176;">
    <tooltip image="Images\Angle16.png" heading="Rotate">Specify rotation angle
      <disabledText>No item selected.</disabledText>
    </tooltip>
  </spinner>

スピナー コントロールは、スピナー 基底クラスから派生することによって実装されます。

  sealed class RotateSpinner : ArcGIS.Desktop.Framework.Contracts.Spinner
  {
    protected override void OnValueChanged(double? value)
    {
      // Do work
    }
  }

ツールはボタンと非常によく似ていますが、選択後に自動的にチェックされたままになる点が異なります。ツールは、現在のペインと連携して機能します。

  <tool id="acme_zoomTool"
        caption="Zoom"
        className="ZoomTool"
        keytip="ZT">
    <tooltip heading="Zoom" image="Images\Zoom16.png">Zoom the map.
      <disabledText>No active map.</disabledText>
    </tooltip>
  </tool>

ツールは、Tool 基底クラスから派生することによって実装されます。ツールは、必要に応じて、マウスとキーボードのイベントをオーバーライドすることを選択できます。この例では、ツールは OnMouseUp イベントを受信する必要があるため、最初に OnMouseDown を処理していることをProに通知する必要があります。そうしないと、Pro がメッセージを消費します。

  sealed class ZoomTool : ArcGIS.Desktop.Framework.Contracts.Tool
  {
    protected override void OnMouseDown(MouseButtonEventArgs e)
    {
      // Do work - set handled to true to receive mouse messages
      e.Handled = true;
    }
  
    protected override void OnMouseUp(MouseButtonEventArgs e)
    {
      switch (e.ChangedButton)
      {
        case MouseButton.Right:
          e.Handled = true;
          ContextMenu menu = FrameworkApplication.CreateContextMenu("acme_AddDataMenu");
          menu.IsOpen = true;
          break;
        // etc …
        }
    }
  }

ペインを宣言するときに、デフォルトのツールを割り当てることができます。このツールは、ペインのインスタンスが作成されるときに自動的に選択されます。複数のペインを操作する場合、アクティブなツールが自動的に変更され、入力ペインが反映される場合があります。元のペインに戻ると、システムはペイン タイプで最後に使用したツールを再度アクティブ化しようとします。

ドッキング ペインは、アプリケーション内のビュー領域の上部、右側、左側、または下部にドッキングできるモードレス ダイアログ ボックスです。ドッキング ペインは、他のドッキング ペインとグループ化して、相互にドッキングすることもできます（つまり、下、上など）。また、ドッキングを解除してフロートすることもできます。最後に、ドッキング ペインは、固定および固定解除をサポートしているため、スペースを節約するためにアプリケーション フレームに戻ります。アプリケーション フレームワークは、各ドッキング ペインのドッキング状態を保持するため、後続のセッションで表示されたときに、同じ位置に表示されます。

ドッキング ペインはシングルトンであり（特定のドッキング ペインのインスタンスが複数存在することはありません）、一度作成されると、アプリケーションが閉じられるまで破棄されません。

ドッキング ペインは、ペインと同じ方法で定義されます。フレームワークがドッキング ペインを作成すると、そのコンテンツ クラスも作成され、コンテンツのデータ コンテキストがドッキング ペインに設定されます。この自動バインドにより、ペインおよびドッキング ペインを開発するときに MVVM パターンを使用できます。たとえば、適切に設計されたドッキング ペインでは、XAML コード ビハインドのロジックが可能な限り少なくなります。代わりに、XAML のすべてのコントロールは、ドッキング ペインの基底クラスのプロパティにバインドする必要があります。ドッキング ペインとペイン基底クラスは、ビュー モデルと見なすことができます。

  <dockPanes>
    <dockPane id="acme_TOCDockPane" 
              caption="Contents" 
              className="TOCDockPaneViewModel" 
              smallImage="AttributesWindow16"
              dock="group"  
              dockWith="esri_core_ProjectDockPane">
      <content className="TOCDockPaneView"/>
    </dockPane>
  </dockPanes>

ドッキング ペインは、dockWith 属性を使用して、他のドッキング ペインに対して相対的に配置されるように宣言できます。上記の例では、ドッキング ペインは、最初に表示されたときに esri_coreProjectDockPane ドッキング ペインとグループ化する必要があることを宣言しています。これ以降、このドッキング ペインが表示されるたびに、ユーザーの再配置をサポートするために、その場所は永続化されたドッキング状態から取得されることに注意してください。

すべてのドッキング ペインは、DockPane 基底クラスから派生する必要があります。DockPane 基底クラスは、PlugIn 基底クラスから継承します。ドッキング ペインは、FrameworkApplication.Dockpanes から利用できる DockPaneManager クラスによって管理されます。ドッキング ペインは論理的にシングルトンであるため、作成されるのではなく検出されます。FrameworkApplication.DockPanes.Find を使用して、ドッキング ペインを検索および作成します。

  class TOCDockPaneViewModel : ArcGIS.Desktop.Framework.Contracts.DockPane
  {
    protected override Task InitializeAsync()
    {
      // Initialize instance...
      return Task.FromResult(0);
    }
  
    protected override Task UninitializeAsync()
    {
      // Uninitialize instance...
      return Task.FromResult(0);
    }
  
    protected override void OnActivate(bool isActive)
    {
      // Called when activated/deactivated
    }
  }

フレームワークは複数のペインをサポートしているため、ユーザーは複数のサブジェクトを表示して操作できます。一度にアクティブにできるペインは 1 つだけです。アクティブなペインは、リボンで使用できるものを確立します。異なるペインを切り替えると、使用可能なタブとコントロールが変更される可能性があります。アクティブなペインは、いつでもユーザーが操作しているものを表します。したがって、アプリケーションのプライマリ コンテキストを提供します。同時に多くのペインを開くことができ、それらはグループ化、タイル化（水平または垂直）、またはフロートすることができます(ただし、インタラクティブな操作のみ)。

ペインは、ペイン コレクション要素内で宣言されます。

  <panes>
    <pane id="acme_MapPane" 
          caption="Map" 
          className="MapPane" 
          smallImage="Images\Map16.png" 
          loadingMessage="Initialize..."
          defaultTab="acme_MapTab" 
          defaultTool="acme_ZoomTool">
      <content className="MapPaneView"/>
    </pane>
  </panes>

ペインはデフォルトのタブやデフォルトのツールに関連付けることができるため、他の関連するツールやタブがまだ選択されていない場合は、ペインがアクティブ化されたときにデフォルトが自動的に選択されます。

ペインは、DAML 定義、コントローラー、およびビューの3つの部分で構成されています。コントローラは、カスタム コントロールで見たものと似ており、フレームワークのPane 基底クラスから継承する必要があります。ビュー コンポーネントはコントロールのカスタム外観であり、このクラスは通常、WPFUserControl から派生します。DAML className 属性はコントローラーを定義し、content 要素はビューを定義します。ペインがインスタンス化されると、コントローラーがビューのデータ コンテキストとして設定されます。これにより、ビュー/ビュー モデルの関係と、このパターンに伴うすべての利点が可能になります。

  class MapPane : ArcGIS.Desktop.Framework.Contracts.Pane
  {
    protected override Task InitializeAsync()
    {
      // Initialize instance...
      return Task.FromResult(0);
    }
  
    protected override Task UninitializeAsync()
    {
      // Uninitialize instance...
      return Task.FromResult(0);
    }
  
    protected override void OnActivate(bool isActive)
    {
      // Called when activated/deactivated
    }
  }

ペインは、FrameworkApplication.Panes を介して利用できる PaneCollection クラスによって管理されます。ペインは、PaneCollection.Create メソッドを使用してプログラムで作成されます。このメソッドには、呼び出し元がユーザー定義データを渡すことを可能にする追加のオーバーロードがあります。呼び出されるCreateのバージョンに応じて、適切なコンストラクターがペイン派生クラスで呼び出されます。ペインのコンストラクターが呼び出された後、ペインの InitializeAsync 関数が呼び出され、必要に応じて非同期で初期化する機会が与えられます。同様に、ペインを閉じると、その UninitializeAsync 関数が呼び出されます。PaneCollection クラスは ActivePane も保持し、既存のペインを検索してアクティブ化するためのメソッドを備えています。

各ペイン インスタンスには、ユーザーが同じペインの複数のインスタンスを区別できるようにするインスタンス識別子 InstanceID が関連付けられています。ペインはさらに ContentID をオーバーライドして、カスタム識別子を提供できます。ContentID は、DAML の <pane ...></pane> 要素で定義された ID に相関します。

ペインは、マウスとキーボードのイベントを直接受け取ります。処理されない場合、イベントはアクティブであれば現在のツールに転送されます。

Undo/Redo セクションで詳しく説明するように、ペインとドッキング ペインは、アプリケーションの操作を管理する上で重要な役割を果たします。

場合によっては、ペインのキャプションに、現在開いている同じタイプの他のペインの数を反映させると便利です（例:2つのうち1つ）。たとえば、同じペインの複数のインスタンスが開いている場合、キャプションを更新して "1/2" や "2/2" などと表示すると、ユーザーは開いているインスタンスを簡単に識別して区別できます。これを実現するには、ペインの GroupID プロパティを一意の値に設定します。アプリケーションは同じ GroupID で開かれたペインの数を記録し、この数はペインのキャプションに表示されます。これを示す完全な実装は、CustomPaneWithContents Sample を参照してください。

var customPane = FrameworkApplication.Panes.Create(...);
customPane.GroupID = "My Custom Pane";

プロパティ シートには、関連のない個々のプロパティ ページのコレクションが含まれています。各ページには、関連するプロパティのグループを設定するためのコントロールが含まれています。プロパティ シートは、モーダルまたはモードレスで表示できます。

デフォルトでは、プロパティシートはそれぞれ固有のサイズと位置を持ちますが、instanceID 属性を設定することで、プロパティ シートをグループ化して同じサイズと位置を共有することができます。

プロパティ シートは純粋に宣言型です。これらは DAML でのみ定義され、対応する管理対象クラスはありません。ペインやドッキング ペインなどのプロパティ ページには、宣言型コンポーネントとアクティブ コンポーネントの両方があります。すべてのプロパティ ページのアクティブな部分は、ArcGIS.Desktop.Framework.Contracts.Page クラスから派生する必要があります。ビュー クラスは通常、WPF UserControl から派生します。

  <propertySheets>
    <insertSheet id="acme_mainSheet"
                  caption="Options">
      <page id="acme_mainOptions"
            caption="Settings"
            className="SettingsPage">
        <content className="SettingsPageView"/>
      </page>
              
    </insertSheet>      
  </propertySheets>

プロパティ ページは、表示されたときにのみ読み込まれます。シートが読み込まれるときには読み込まれません。ページにアクセスする必要があります。ページが読み込まれると、その Page.IsLoading プロパティが最初に true に設定されます。次に、そのPage.InitializeAsync 関数が実行されます。返されたタスクが完了すると、その IsLoading プロパティは false にリセットされます。

プロパティページには、条件付きにするオプションがあります。DAMLでページにコンディションが指定されている場合、そのコンディションが現在満たされていなければ、ページはシートに表示されません。

シートの hasGroups 属性を true に設定し、ページの group 属性を設定してグループ見出しを指定することにより、ページをシート内でグループ化することもできます。

プロパティシートが PropertySheet.Show または PropertySheet.ShowDialog のいずれかで表示される場合、データを引数の 1 つとして渡すことができ、そのすべてのページが Page.Data プロパティを使用してデータにアクセスできます。

プロパティ シート ダイアログ ボックスには、タイトル バーと、[OK]、[キャンセル]、[適用]のいくつかのボタンがあります。[適用]ボタンは、シートがモードレスの場合にのみ表示されます。ページが有効 (Page.IsValid) であると報告している限り、[OK] ボタンは有効のままです。[適用]ボタンは、シート内のいずれかのページがそのPage.IsModified プロパティを true に設定し、すべてのページが有効になると有効になります。[適用]または[OK]をクリックすると、IsModified フラグが true に設定されている各ページで、CommitAsync が呼び出されます。同様に、[キャンセル]ボタンをクリックすると、CancelAsync が呼び出されます。プロパティ ページは、CanReset プロパティが true を返すようにオーバーライドすることで、オプションで「ページのリセット」ボタンを表示することができます。ページが変更されると、"Reset Page" ボタンが有効になります。このボタンをクリックすると、オーバーライド関数 ResetAsync() が呼び出され、ページがデフォルトにリセットされます。

最後に、プロパティ シートを閉じると、読み込まれた各ページの Page.Uninitialize が呼び出され、必要なクリーン アップを実行できます。

コントロールを宣言しても、コントロールが実際に表示される場所と方法は確立されないことに注意してください。サイズや相対的な配置など、リボン上のコントロールの位置は、group と tab 要素を使用して確立されます。

ArcGIS Pro は、新しいバージョンの MicrosoftOffice で普及しているリボン パラダイムを使用します。リボンは、1つ以上のタブを含む単一の固定ツール バーで構成されています。使用可能な（表示される）タブの数は、アプリケーションの状態に応じて動的に変化する可能性があります。タブは、ユーザーの操作（クリック）によって、またはアプリケーション内で実行されているコードによって指示されたときにアクティブになります。

各タブは1つ以上のグループで構成され、小さな長方形の領域にはキャプションがあり、1つ以上のコントロールが含まれています。グループ内のコントロールの表現は、コントロールが使用されると予想される頻度によって異なり、DAML で宣言的に構成されます。頻繁に使用するコントロールは大きくてわかりやすいものにする必要がありますが、あまり使用しないツールは小さくする必要があります。さらに、コントロールは通常、機能をより明確にするためにキャプションとペアになっています。

グループは、オプションで「ダイアログ ランチャー」ボタン（グループ キャプションの横にある小さなリンク ウィジェット）をサポートできます。このボタンは、見えない機能にアクセスできるダイアログ ボックスを表示するために使用されます。これは、launcherButtonID 属性で指定します。グループは、groups コンテナ要素内のコントロールのリストとして宣言されます。

 <groups>
   <group id="esri_mapping_navigateGroup" caption="Navigate" 
           launcherButtonID="esri_mapping_navigationOptionsButton" 
           smallImage="Images/3DNavigationTool16.png" 
           launcherKeytip="NG">
     <tool refID="esri_mapping_exploreSplitButton" size="large"/>
     <button refID="esri_mapping_zoomFullButton" size="small"/>
     <button refID="esri_mapping_fixedZoomInButton" size="small"/>
     <button refID="esri_mapping_prevExtentButton" size="small"/>
     <button refID="esri_mapping_zoomToSelectionButton" size="small"/>
     <button refID="esri_mapping_fixedZoomOutButton" size="small"/>
     <button refID="esri_mapping_nextExtentButton" size="small"/>
     <gallery refID="esri_mapping_bookmarksNavigateGallery" inline="false" size="large"/>
   </group>  
   <group id="esri_mapping_labelingLayerGroup" caption="Layer"
         smallImage="Images/LabelingRibbonLayer16.png" keytip="ZL">
     <button refID="esri_mapping_labelLayerEnableButton" size="large"/>
   </group>
    <group id="esri_mapping_labelingGroup" caption="Labeling"
           smallImage="Images/MapRibbonLabeling16.png" keytip="ZL">
      <button refID="esri_mapping_labelPauseButton" size="middle" />
      <button refID="esri_mapping_labelViewUnplacedButton" size="middle"/>
      <menu refID="esri_mapping_labelingOptionsMenu" size="middle"/>         
    </group>
 </groups>

上記の例では、いくつかのグループが宣言されており、各グループはその内容をリストしています。要素は以前に宣言されたコントロールを参照することに注意してください。たとえば、ボタンがコントロール下の宣言で画像を指定しているのに、サイズがグループで指定されていることに注意してください。これは、同じコントロールが複数のグループで異なって表示される可能性があるためです（グループ A では large だが、グループ B では small）。ラベル コントロールを使用して、グループに追加のテキスト情報を提供します。セパレータを使用して、同じグループ内の複数のコントロールを分離します。

グループの可視性は、その「condition」属性を介して制御できます。関連するコンディションが true の場合、グループが表示されます（タブまたはメニューが表示されている場合はタブまたはメニューに表示されます）。コンディションが false の場合、グループは表示されません（タブまたはメニューが表示されている場合）。したがって、グループのコンディションを使用すると、Pro セッション内のさまざまなアクションまたはイベントに応じてグループの可視性を切り替えることができます。

group 要素には「appearsOnAddInTab」属性があります。この属性が「true」に設定されている場合、そのグループ内で定義されているすべてのコントロールがアドイン タブに配置されます。これは、新しいタブを定義することなく、コントロールを Pro リボンに配置するための簡単な方法です。以下のコード スニペットは、アドイン タブに1つの「ツール」を持つ「ダイナミック メニュー」グループを作成します。

  <group id="DynamicMenu_Group1" caption="Dynamic Menu" appearsOnAddInTab="true">
    <!-- host controls within groups -->
    <tool refID="DynamicMenu_FeatureSelectionDynamic" size="large" />
  </group>

コントロールと同様に、既存のグループは DAML で変更できます。次の例では、新しいボタンを既存のグループに挿入し、ボタンを削除します。

  <updateModule refID="esri_mapping">
    <groups>
      <updateGroup refID="esri_mapping_navigateGroup">
        <insertButton refID="acme_FullExtent" 
                      insert="before" 
                      placeWith="esri_mapping_zoomFullButton" 
                      separator="true"/>
        <deleteButton refID="esri_mapping_fixedZoomOutButton"/>
      </updateGroup>
    </groups>
  </updateModule>

グループが宣言されると、それを参照してタブに配置できます。タブは、タブのコレクション要素内のグループのリストとして宣言されます。次の例では、以前に宣言されたグループが、id が「esri_mapping_homeTab」の新しいタブに追加されています。

  <tabs>
    <tab id="esri_mapping_homeTab" 
         caption="MAP" 
         condition="esri_mapping_pane_core" 
         keytip="M">
      <group refID="esri_core_clipboardGroup" />
      <group refID="esri_mapping_navigateGroup" />
      <group refID="esri_mapping_mapGroup" />
      <group refID="esri_mapping_selectionGroup" />
      <group refID="esri_mapping_inquiryGroup" />
      <group refID="esri_mapping_labelingGroup" />
    </tab>
  </tabs>

コントロールと同様に、タブの関連性はコンディションを使用して管理できます。コンディション属性は、タブが表示され、使用可能かどうかを制御するために使用されます。コンディションはタブのアクティブ化を制御するために使用されるのではなく、タブの可用性のみを制御します。コンディションが指定されていない場合、タブは常に表示されます。

関連するタブのコレクションは、わかりやすくするために、グループ化できます。これらのコレクションはタブ グループと呼ばれます。以下に表示されるリボンには、3つのタブを含むタブ グループがあります。

タブ グループは、tabGroups コレクション要素内で宣言され、ID で構成されます。タブは、tabGroupID 属性を使用してタブ グループに関連付けられます。以前は 2.x タブ グループはキャプションと背景色をサポートしていましたが、現在は Esri_White の背景色に変更されています。

  <tabGroups>
    <tabGroup id="esri_mapping_featureLayerTabGroup">
    </tabGroup>
  </tabGroups>
  
  <tab id="esri_mapping_featureLayerAppearanceTab" 
       caption="APPEARANCE" 
       condition="esri_mapping_onlyFeatureLayersSelectedCondition" 
       tabGroupID="esri_mapping_featureLayerTabGroup" 
       keytip="JA">
    <group refID="esri_mapping_layerScaleVisibilityGroup"/>
    <group refID="esri_mapping_layerEffectsGroup" />
    <group refID="esri_mapping_layerSymbology" />
    <group refID="esri_mapping_layerExtrusion" />
    <group refID="esri_mapping_layer3DGroup" />
  </tab>

タブ グループは通常、「グラフィック エレメントの編集」など、ユーザーが一時的にモードに入る状況で使用されます。タブ グループは通常、永続的に表示されるタブ（グローバル タブ）では使用されません。タブ グループ内のタブは同じコンディションである必要があります。タブ グループ内のいずれかのタブに関連するコンディションがある場合、タブ グループ全体が表示されます。

コントロールと同様に、タブの関連性はコンディションを使用して管理できます。コンディション属性は、タブが表示され、使用可能かどうかを制御するために使用されます。コンディションはタブのアクティブ化を制御するために使用されるのではなく、タブの可用性のみを制御します。コンディションが指定されていない場合、タブは常に表示されます。タブ内のグループもコンディションを含みます。これにより、ほぼ同じように見える複数のタブを作成する必要がなくなります。

アクセシビリティをサポートするには、タブごとに適切なキー チップを提供する必要があります。選択した文字は意味があり、既存のキー チップと競合しないようにする必要があります。キー チップは、必要に応じて明確にするために複数の文字で構成できます。

サブグループは、オプションでグループ内で宣言されます。サブグループは、リボンのスケーリングをより細かく制御し、アプリケーション ウィンドウのサイズが変更されたときにユーザーエクスペリエンスが最適になるようにします。各サブグループは、最大 3 つのコントロールを保持できます。サブグループには size と verticalAlignment の 2 つの属性があります。

<subgroups>
    <!-- Can only have 3 items in a subgroup-->
    <subgroup id="esri_core_editBtns" size="MediumThenSmallWhenSmall" 
                                          verticalAlignment="Center" >
      <button refID="esri_core_editCutButton"/>
      <button refID="esri_core_editCopyButton"/>
      <button refID="esri_core_editCopyPaths"/> 
    </subgroup>
</subgroups>

verticalAlignment は、「Center」または「Top」（デフォルト）を設定できます。

サイズは次のいずれかになります。

Large

Medium

Small

グループ内で複数のサブグループを宣言できます。

<subgroups>
  <subgroup id="esri_datasourcesraster_georefAdjustSubGroup1" 
         verticalAlignment="Top" size="Default">
    <button refID="esri_datasourcesraster_georefAutoFitToRefButton"/>
    <button refID="esri_datasourcesraster_georefImportControlPointsButton"/>
    <button refID="esri_datasourcesraster_georefAddControlPointsButton" 
          separator="false" />
  </subgroup>
  <subgroup id="esri_datasourcesraster_georefAdjustSubGroup2" 
         verticalAlignment="Center" size="LargeThenSmallWhenMedium">
    <gallery refID="esri_datasourcesraster_georefXformTypesGallery"/>
    <button refID="esri_datasourcesraster_georefAutoAdjustButton" 
          separator="false" />	
  </subgroup>        
  <subgroup id="esri_datasourcesraster_georefAdjustSubGroup3" 
         verticalAlignment="Top" size="MediumThenSmallWhenSmall">
    <button refID="esri_datasourcesraster_georefUpdateDisplayButton"/>
    <button refID="esri_datasourcesraster_georefResetXformButton"/>	
  </subgroup> 
</subgroups>

次に、各サブグループを目的のグループに配置できます。

<group id="esri_datasourcesraster_georefAdjustGroup" caption="Adjust" 
  smallImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/RasterGeoRefTransform16.png">
  <subgroup refID="esri_datasourcesraster_georefAdjustSubGroup1"/>
  <subgroup refID="esri_datasourcesraster_georefAdjustSubGroup2"/>
  <subgroup refID="esri_datasourcesraster_georefAdjustSubGroup3"/>
</group>

group DAML 要素には sizePriorties プロパティがあり、アプリケーションを縮小するときにグループの折りたたみを優先するために使用できます。デフォルトでは、グループ内のコントロールは右から左に縮小し始めます。このデフォルトの動作は、グループ要素の sizePriorties 属性を構成することで変更できます。

優先度が低い（大きなコントロール）ほど、サイズのバリエーション（大、中、小、折りたたみ）が早く適用され、優先度が高い（小さなコントロール）ほど、バリエーションが後で適用されます。優先順位番号は他のグループに関連しているため、特定の番号は何の意味も持たず、単に高いか低いかです。配列の最初の数値が比較に使用されます。優先順位は、大から中、中から小、そして最後に小から折りたたみです。グループの折りたたみ方法を制御するには、subgroups を使用することをお勧めします。

以下の DAML コード スニペットでは、3 つのグループが定義されています。ID が SizePrioritiesTesting_Group2 のグループ要素は、sizePriorities 属性値の配列（10,70,110）の最初の番号が 10 で最小であるため、3 つのグループの中で最も低い優先度を持っています。したがって、このグループは縮小する最初のグループになります。その後に SizePrioritiesTesting_Group1 という ID を持つグループが続きます。最後に縮小するグループは、ID が SizePrioritiesTesting_Group3 のグループです。

      <groups>
        <group id="SizePrioritiesTesting_Group1" caption="2nd to shrink" sizePriorities="20,60,100">
          <subgroup refID="sub1a" />
          <subgroup refID="sub1b" />
        </group>
        <group id="SizePrioritiesTesting_Group2" caption="1st to shrink" sizePriorities="10,70,110" >
          <subgroup refID="sub2a" />
          <subgroup refID="sub2b" />
        </group>
        <group id="SizePrioritiesTesting_Group3" caption="Last to shrink" sizePriorities="30,80,120">
          <subgroup refID="sub3a" />
          <subgroup refID="sub3b" />
        </group>
      </groups>
      <subgroups>
        <subgroup id="sub1a" size="Default">
        ...

リボン グループは、ツールバーへのコントロールの内部コレクション/グループ化をサポートします。ツール バーは純粋に宣言型であり、その定義は、リボンで使用可能なスペースの量に応じてツール バーがどのように見えるかを示します。ツール バーは、1つの長いコントロールとして描画するように設計されています。サイズの制約がある場合、ツールバーはそのグループを積み重ねてスペースを節約します。たとえば、ユーザーがメイン ウィンドウを展開したときなど、リボンに多くのスペースがある場合、ツール バーのすべてのグループが 1 つの長い行に表示されます。アプリケーションが縮小すると、ツール バーは連続するグループを相互に移動します。グループで宣言するツール バーは1つだけです。次の例は、いくつかのコンボ ボックスとボタンを備えたツール バーを示しています。

  <toolbars>
    <toolbar id="esri_mapping_labelTextSymbolFontToolbar">
      <group>
        <comboBox refID="esri_mapping_labelTextSymbolFontFamilyComboBox" />
        <comboBox refID="esri_mapping_labelTextSymbolFontSizeComboBox"/>
        <button refID="esri_mapping_labelTextSymbolIncreaseSizeButton"/>
        <button refID="esri_mapping_labelTextSymbolDecreaseSizeButton" />
      </group>
      <group>
        <comboBox refID="esri_mapping_labelTextSymbolFontStyleComboBox" />
        <customControl refID="esri_mapping_labelTextSymbolColorPicker"/>
      </group>
    </toolbar>
  </toolbars>

ArcGIS Pro のリボン内のアプリケーション タイトルの横にある「コマンド検索コントロール」を使用して、コントロールにある編集ボックスにキーワードを入力することで、コマンドをすばやく見つけて実行できます。ボタンやツール コントロールなどのプラグインがアドインを使用して Pro の UI に追加されると、それらはアプリケーションのリボンのコマンド検索コントロールによって自動的に「検索可能」になります。

下のスクリーンショットでは、アドインを使用して、Pro のリボンの SDK タブに「Create Multi-Point Graphics」ボタンが追加されています。 ボタン コントロールは、検索文字列（この場合は DAML ボタン ID）がコントロールに提供されると、コマンド検索コントロールの結果にリストされます。 注: プラグインの DAML ID、キャプション、またはツール チップは、コマンド検索コントロールの検索文字列として使用できます。

コマンド検索結果にコマンドが表示されないようにするには、daml 属性 hidden="true" を使用します。 これはオプションの属性で、デフォルト値は「false」です。 アドインによって作成されたボタンとツールは、コマンド検索コントロールによって自動的に「検索可能」になります。

<button id="CommandSearchTesting_Multi_Point_Graphics" hidden="true" caption="Create Multi-Point Graphics" 
                className="CommandSearchButton" loadOnClick="true" 
                smallImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/EvilGenius16.png" 
                largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/EvilGenius32.png">
 <tooltip heading="Create Multi-Point Graphics">Sketch a line to create multi-point graphics<disabledText />
 </tooltip>
</button> 

コマンド検索の詳細については、Pro Guide Command Search を参照してください。

クリックまたはタブでコマンド検索コントロール内に最初にフォーカスを移動すると、最近使用したコマンドと提案されたコマンドの複合リストが表示されます。リストされているサジェスト項目は、現在アクティブなタブによって異なります。

サジェストされるコマンドのリストは、アプリケーションが置かれている状態により適切に調整されたリストを提供するために、DAML を静的に使用するのではなく、実行時に決定されます。各リボン タブはモジュールのスコープ内で宣言され、サジェストされるコマンド リストを決定するのは親モジュールです。特定のタブには、さまざまな機能（他のモジュールに関連付けられている）に関連付けられたグループが含まれている場合がありますが、すべてのグループの代表として機能し、適切なリストを提供することは、を最初にタブを 宣言 したモジュールの責任です。

モジュールは、モジュール クラスの GetSuggestedCMDIDs オーバーライドを通じてサジェスト コマンド リストを提供するようにコーディングされています。このメソッドは、ユーザーがアクティブなリボン タブを切り替えるたびに、適切なモジュールで呼び出されます。現在アクティブなタブに関連付けられているモジュールがこのオーバーライドを実装していない場合、（アプリケーションによって静的に定義された）グローバル デフォルト リストがユーザーに表示されます。ユーザー エクスペリエンスを向上させるには、開発者がこのオーバーライドを実装して適切なリストを提供することが重要です。

以下の例は、指定されたタブ ID に応じて異なるサジェスト リストを提供するモジュールを示しています。

  public override string[] GetSuggestedCMDIDs(string activeTabID) 
  {
    if (string.Compare(activeTabID, "CommandSearchTesting_Tab1", true) == 0)
    {
      return new[] { "CommandSearchTesting_Multi_Point_Graphics", 
                     "esri_core_showOptionsSheetButton", "esri_mapping_clearSelectionButton" };
    }
    else
    {
      return new string[] { "esri_core_openProjectButton", "esri_core_showProjectView" };
    }
  }

ArcGIS Proには、アドインと構成で使用できる UI コントロールがいくつかあります。それらは以下にリストされています。

ハンバーガー ボタンは、設定や高度な機能のためのメニューです。通常、ドッキング ペインの右隅にあります。このコントロールは、{ArcGIS Pro インストール フォルダー}\bin フォルダーの ArcGIS.Desktop.Shared.WPF.dll に依存しています。

xmlns:frameworkControls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
            <frameworkControls:BurgerButton>
                <frameworkControls:BurgerButton.PopupMenu>
                    <ContextMenu>
                        <MenuItem Header="Item 1"/>
                        <MenuItem Header="Item 2"/>
                    </ContextMenu>
                </frameworkControls:BurgerButton.PopupMenu>
     </frameworkControls:BurgerButton>

円形アニメーション コントロール は、単純なアニメーション コントロールです。異なる透明度の円の輪です。リングを回転させるとアニメーションが発生します。

xmlns:controls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
<controls:CircularAnimationControl Foreground="Maroon" SpeedRatio="0.5" Visibility="Visible"/>

DateTimePickerControl は、日付/時刻を表示または選択するための UI を提供します。DateTimePicker コントロールを使用すると、ユーザーは日付/時刻をテキスト フィールドに入力するか、カレンダーのドロップ ダウンを使用して選択できます。

xmlns:mapping="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
<mapping:DateTimePickerControl x:Name="DateTimePickerControl" />

このコントロールは、日付のみ、日付と時刻のみを表示するように構成したり、選択した日付のテキスト ボックスを表示したりすることもできます。ShowDate、ShowTime および ShowTextBox は、 これらの構成を可能にする DateTimePickerControl のパブリック プロパティです。

Info ボタン コントロール は、シンプルなツール チップを表示する「詳細情報」ボタンです。

xmlns:controls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
<controls:InfoButton Margin="5" Header="Max Scale" 
   Description="This is the maximum amount of detail available at that extent for vector tile layers"/>

ArcGIS メッセージ ラベル コントロール は、エラー、警告、確認、および情報メッセージを表示するためのカスタム ラベル コントロールです。

xmlns:frameworkControls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"

<frameworkControls:MessageLabel MessageType="Confirmation" Severity="High" ShowHelp="True" 
Content="Please enter an integer" Width="300" Visibility="Visible" />

検索テキストボックス コントロール はオプションの検索履歴メニューを提供する ArcGIS.Desktop.Framework.dll のカスタム検索コントロールです。

xmlns:controls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
<controls:SearchTextBox InfoText="Search features" SearchMode="Manual" 
    Search="SearchTextBox_Search" Width="200"/>

xmlns:controls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
<controls:SearchTextBox InfoText="Search features" SearchMode="Auto" ShowHistory="True" Search="SearchTextBox_Search" Width="200" />

Proは、コンテンツ ペインで TabIndicator topic20582.html を使用して、画像のコレクションを表示します。これらの画像は、カスタム インジケーターの装飾が施されたドッキング ペインの上部に水平方向のビューで表示されます。画像をクリックすると、その選択肢のオプションが表示されます。

独自のコンテンツ ペイン（ドッキング ペインなど）を作成し、TabIndicator カスタム コントロールを含めて、ArcGIS Pro と同じルック アンド フィールを取得できます。TabIndicator は、アイテムのコレクションを画像とともに表示します。

  ...
 <UserControl.Resources>
   <ResourceDictionary>
      <!--Datatemplate to view the items in the  Sub Panel Indicator list box control-->
      <DataTemplate x:Key="SubPanelListItem" DataType="{x:Type localMenu:OptionsMenuItem}">
         <Image Stretch="Fill" Width="24" Height="24" Source="{Binding Path=ImageSource}" >
            <Image.ToolTip>
              <ToolTip Content="{Binding Path=OptionString}"/>
            </Image.ToolTip>
          </Image>
       </DataTemplate>
  ...
...
 <Grid>
        <StackPanel Grid.Row="0">
            <frameworkControls:TabIndicator HorizontalAlignment="Stretch"
                    Margin="0,0,6,0"
                    HorizontalContentAlignment="Left"
                    ItemTemplate="{StaticResource SubPanelListItem}"
                    ItemsSource="{Binding OptionsMenu}" 
                    SelectedItem="{Binding SelectedOption}">
            </frameworkControls:TabIndicator>
...

待機カーソル コントロールは ArcGIS.Desktop.Framework.dll のカスタム待機インジケーター コントロールです。アニメーションは、コントロールがロードされると開始し、非表示またはアンロードされると停止します。

ArcGIS Pro の WebViewBrowser コントロールは、Microsoft の WebView2 コントロールをベースにした薄いラッパーであり、アドインの UI で使用するために提供されます。このコントロールを使用するには、以下のようにします。

• 以下の ArcGIS Pro Microsoft WebView2 アセンブリへの参照を追加します (WebView2 NuGet は使用しないでください)。
  • <ArcGIS Pro Install Folder>\bin\Microsoft.Web.WebView2.Core.dll
  • <ArcGIS Pro Install Folder>\bin\Microsoft.Web.WebView2.Wpf.dll

アセンブリ参照の Copy Local = false を設定します。注：ArcGIS Pro で使用されている現在の WebView2 固定バージョンのランタイムについては、Pro bin\WebView フォルダー内の WebView2 マニフェストを参照してください。

• 必要に応じて、アドイン UI xaml に Pro WebViewBrowser コントロールへの参照を追加します（例：ドッキング ペイン上）。

 <UserControl x:Class="..."
   ...
   xmlns:fwk="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
   ...>
   <UserControl.Resources>...</UserControl.Resources>
   <Grid>
     <Border BorderBrush="Red" BorderThickness="2,2">
       <fwk:WebViewBrowser Source="{Binding SourceUri, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}" />
     </Border>
   </Grid>
 </UserControl>

そして、そのコード ビハインド（View Model）。

private const string StartUri = "https://www.esri.com";
private Uri _sourceUri = new Uri(StartUri);
/// <summary>
/// SourceUri is used to interface with the WebViewBrowser control
/// </summary>
public Uri SourceUri
{
	get { return _sourceUri; }
	set
	{
		SetProperty(ref _sourceUri, value, () => SourceUri);
		if (_sourceUri.AbsoluteUri != _navInput)
		{
			_navInput = _sourceUri.AbsoluteUri;
			NotifyPropertyChanged(() => NavInput);
		}
	}
}

private string _navInput = "https://www.esri.com";
/// <summary>
/// NavInput is used to provide a text input field for navigation in the UI
/// </summary>
public string NavInput
{
	get { return _navInput; }
	set
	{
		SetProperty(ref _navInput, value, () => NavInput);
	}
}

注: WebViewBrowser Control のクッキー、パーミッション、キャッシュされたリソースなどのユーザー データは、ユーザーのデータ フォルダーに入ります。各ユーザー データ フォルダーはユーザーに固有のもので、Microsoft の WebView2 によって自動的に作成されます。WebView2 のユーザー データ フォルダーは、通常、\{LocalApplicationData}\{ProductName}\WebView になります。ArcGIS Pro における WebView のユーザー データのフォルダーは、C:Users\{UserName}\AppDataLocal\ArcGISPro\WebView となります（{LocalApplicationData} フォルダーのパスに依存します）。

WebViewBrowser コントロールを使用したサンプルは、WebViewBrowser コントロール にあります。

高解像度モニターをより適切にサポートするために、ラスターよりもはるかに優れたスケーリングを行うため、ArcGIS Pro はベクター アイコン イメージ（xaml）を使用して、リボンにコンテンツを表示します。高解像度モニターは、使用可能な場合は常に xaml アイコンを使用しますが、低解像度モニターは、スケーリングが 125 ％以上に設定されている場合、xaml アイコンを使用します。アドイン開発者は、通常どおり、ArcGIS Pro リボンの UI コントロールのアイコンとして png（ラスター）画像を引き続き使用できます。

次の手順では、例として DAML <button ...> を使用して、リボンのアドインでベクター xaml アイコンを使用する方法について説明します。完全な例は、 XAML-Icons サンプル にあります。

1. ベクター ベースの xaml アイコンとしてアイコンを作成します。例：XAML-Icons サンプル の EvilGenius16.xaml と EvilGenius32.xaml。これらは、ArcGIS Pro のリボンのカスタム ボタンで使用するアイコンです。ArcGIS Pro の暗色テーマと淡色テーマをサポートするには、2 つのバージョンの xaml アイコンが必要です。
2. 暗色テーマの xaml アイコンを DarkImages フォルダーに追加します。淡色テーマの xaml アイコンを Images フォルダーに追加します（Visual Studio のアドインまたは構成プロジェクトには Images フォルダーと DarkImages フォルダーの両方が含まれます）。低解像度のシナリオをサポートするには、通常の png も追加する必要があります。
3. これらの xaml ファイルのビルド アクション プロパティを「Content」に設定します。
4. プロジェクトの Config.daml で、button 要素を見つけます。ボタン要素の smallImage 属性と largeImage 属性を SDK テンプレートで設定されたデフォルトから Images\<ベクター イメージ><16 または 32>.xaml に変更します（注：DarkImages フォルダーではなく Images フォルダーの xaml アイコンを参照してください。パス区切り文字に \ を使用していることにも注意してください）。

 <controls>
  <!-- add your controls here -->
  <!--This button uses a vector based XAML Icon-->
  <button id="XAML_Icons_XAMLIcons" caption="Button 1" className="XAMLIcon" 
           loadOnClick="true" smallImage="Images\EvilGenius16.xaml" 
                              largeImage="Images\EvilGenius32.xaml">
    <tooltip heading="XAML Icon">This button uses a vector based XAML Icon<disabledText/>
    </tooltip>
   </button>
 </controls>

ArcGIS Pro がアドインを読み込むと、ベクター xaml アイコンが付いたボタンが作成されます。アドインの Images と DarkImages フォルダーには、淡色テーマと暗色テーマとのベクター xaml アイコンが含まれているため、ボタンには、アプリケーションで使用されているテーマの正しいアイコンが自動的に表示されます。

（指定されたセッションの）すべてのプローブされたアドインのメタデータを問い合わせたい場合は、ArcGIS.Desktop.Framework.AddinInfo のコレクションを返す FrameworkApplication.GetAddInInfos() メソッドを使用できます。

それぞれの AddinInfo が、アドインごとに次のメタデータを提供します。

public class AddInInfo : PropertyChangedBase
  {
    public AddInInfo();

    public string Name { get; set; }        //<AddInInfo ..><Name>
    public string Description { get; set; } //<AddInInfo ..><Description>
    public string ImagePath { get; set; }   //<AddInInfo ..><Image>
    public string Author { get; set; }      //<AddInInfo ..><Author>
    public string Company { get; set; }     //<AddInInfo ..><Company>
    public string Date { get; set; }        //<AddInInfo ..><Date>
    public string Version { get; set; }     //<AddInInfo version="...">
    public string FullPath { get; set; }    //The well-known folder location
    public string DigitalSignature { get; set; } //the signature or "None"
    public bool IsCompatible { get; set; } 
    public bool IsDeleted { get; set; }
    public string TargetVersion { get; set; } //<AddInInfo desktopVersion="...">
    public string ErrorMsg { get; set; }
    public string ID { get; set; }            //<AddInInfo id="...">
    public ImageSource Image { get; set; }
  }

システムにアドインが含まれていない場合、返されるリストには単一の null エントリを含めることができます。適切な処理を示す例を次に示します。

  //retrieve add-in metadata for the current session:
  var addin_infos = FrameworkApplication.GetAddInInfos();
  StringBuilder sb = new StringBuilder();

  foreach (var info in addin_infos)
  {
     if (info == null)
        break;//no addins probed

     //Get the add-in metadata
     sb.AppendLine($"Addin: {info.Name}");
     sb.AppendLine($"Description {info.Description}");
     //etc
  }
  MessageBox.Show(sb.ToString(), "Addin Infos");

フレームワークは、アプリケーション内の疎結合コンポーネント間の通信を可能にするイベント メカニズムを提供します。このメカニズムにより、パブリッシャーとサブスクライバーは、相互に直接参照することなく、イベントを介して通信できます。これは、アプリケーションのモジュール化に役立ちます。

フレームワークは、サブスクリプション時にサブスクライバーのハンドラーへの弱いデリゲート参照を維持します。これは、フレームワークがサブスクライバーに対して保持する参照が、サブスクライバーのガベージ コレクションを妨げないことを意味します。弱いデリゲート参照により、サブスクライバーは、適切なガベージコレクションを有効にするためにサブスクライブを解除する必要がなくなります。これはセーフティ ネットと見なされるべきです。しかしながら、サブスクライバーはサブスクライブを解除することをおすすめします。

パブリッシャーは、EventAggregator からイベントを取得し、Publish メソッドまたは PublishAsync メソッドを呼び出すことによってイベントを発生させます。 たとえば、次のコードは、LayerSelectionChanged イベントのパブリッシュを示しています。

  LayerSelectionEventArgs layerSelectionChangedArgs = new LayerSelectionEventArgs(
                                                        _layer, _toc.LayerSelection);
  
  FrameworkApplication.EventAggregator.GetEvent<LayerSelectionChangedEvents>().Publish(
                                                              layerSelectionChangedArgs);

PublishAsync メソッドは、すぐに処理する必要のないタスクを呼び出し元に返します。これは、イベント シンクがイベントに応答して非同期呼び出しを行う必要があり、パブリッシャーとしてのあなたがすべての子タスクが完了して応答するまで待ってから続行する必要がある場合に役立ちます。

最小またはデフォルト サブスクリプションの場合、サブスクライバーは、イベント通知を受信する適切な署名を使用してコールバック メソッドを提供する必要があります。たとえば、LayerSelectionChangedEvent のハンドラーでは、次のようにメソッドが文字列パラメーターを受け取る必要があります。

  FrameworkApplication.EventAggregator.GetEvent<LayerSelectionChangedEvents>().Subscribe(
                                                                  OnLayerSelectionChanged);
  
  public void OnLayerSelectionChanged(LayerSelectionEventArgs e)
  {
    …
  }

短期間に複数のイベントを発生させていて、それらのパフォーマンスの問題に気付いた場合は、強力なデリゲート参照を使用してサブスクライブし、サブスクライバーを破棄するときにイベントから手動でサブスクライブを解除する必要があります。

  bool keepSubscriberReferenceAlive = true;
  
  FrameworkApplication.EventAggregator.GetEvent<LayerSelectionChangedEvents>().Subscribe(
                                   OnLayerSelectionChanged, keepSubscriberReferenceAlive);

Model-View-ViewModel（MVVM）プログラミング パターンの重要なコンポーネントの1つは、コマンドです。コマンドを使用すると、データ バインディングを介して、ビュー（ユーザー インターフェイス）とコマンド ハンドラー メソッドを分離できます。コマンドは、.NETFramework の一部である Microsoft の ICommand インターフェイスを実装します。ArcGIS Pro フレームワークは、コマンドの「Execute」と「CanExecute」機能を実装するための RelayCommands クラスtopic10252を提供します。

フレームワークの RelayCommand 実装は、デフォルトで Pro アプリケーションのメイン メッセージ ポンプにコマンドを追加するという点で他の RelayCommand 実装とは異なります。つまり、その CanExecute 関数（topic10265）は 1 秒間に数回自動的に呼び出されます。この動作が必要ない場合 supportsOnUpdate は、適切なコンストラクターでパラメーターを false に設定します。この動作を使用する場合は、ダイアログが閉じたときにポンプからのコマンド Disconnect（topic10266） を確認してください。

RelayCommands は、プライマリ ワーカー スレッドがビジー状態になると自動的に無効になります。この動作をオーバーライドするには、適切なコンストラクターで disableWhenBusy パラメーターを false に設定します。

Pro アプリケーションがシャットダウンを開始すると、メッセージ ポンプの RelayCommands は自動的に無効になることに注意してください。

Pro アプリケーションが同時使用ライセンス を使用しているシナリオの場合、ライセンス アドインは、ライセンスの共有プールとの間でそれぞれライセンスをチェック アウトおよびチェック インできます。

同時使用シナリオでのライセンス管理は、ArcGIS.Core.Licensing.LicenseInformation 静的クラスによって提供されます。LicenseInformation を使用して、ライセンスの可用性と有効期限を確認し、それらをチェック アウトおよびチェック インします。非同時使用環境でライセンスをチェック アウトおよびチェック インするための LicenseInformation の呼び出しは無視されます。

次の例では、使用可能なすべてのライセンスが LicenseInformation.CheckoutLicense 経由でチェック アウトされ、ライセンスのリストに保存されます。チェック アウトされたライセンスのリストと、チェック アウトに失敗したライセンスのリストを示すメッセージ ボックスが開きます。ユーザーがメッセージ ボックスを確認すると、チェック アウトされたすべてのライセンスが LicenseInformation.CheckinLicense を介して再度チェック インされます。

using ArcGIS.Core.Licensing;

internal class CheckoutButton : Button
{
  protected override void OnClick()
  {
    StringBuilder sb = new StringBuilder();
    StringBuilder sb2 = new StringBuilder();

    List<LicenseCodes> checkedOut = new List<LicenseCodes>();
    foreach (LicenseCodes lc in Enum.GetValues(typeof(LicenseCodes)))
    {
      var count = LicenseInformation.GetAvailabilityCount(lc);
      if (count > 0)
      {
        if (LicenseInformation.CheckoutLicense(lc))
        {
          checkedOut.Add(lc);
          sb.AppendLine($"{lc.ToString()} successfully checked out");
        }
        else
        {
          sb2.AppendLine($"{lc.ToString()} IsAvailable but check out failed");
        }
      }
    }
    //User must acknowledge messagebox
    System.Windows.MessageBox.Show(sb.ToString() + "\r\n\r\n" + sb2.ToString(),
                                                       "Extensions checked out");

    //check all the licenses back in again
    foreach (var lc in checkedOut)
      LicenseInformation.CheckinLicense(lc);

  }
}

次のようなメッセージ ボックスが表示されます。正確な内容は、個々の同時ライセンス設定によって決定されます。

Undo/Redo（元に戻す/やり直し）フレームワークに参加するには、操作を作成して適切な ArcGIS.Desktop.Framework.OperationManager に追加する必要があります。アプリケーション内で、各ペインとドッキング ペインは、操作の管理方法を決定する独自の OperationManager を持つことができます。たとえば、異なるマップには独自の操作スタックがあります。フォーカスが別のマップに切り替わった場合、あるマップのフィーチャを削除しても元に戻すことはできません。各ペインとドッキング ペインには独自 OperationManager を提供する機会が与えられますが、特定のタイプのほとんどのペインは同じペインを共有することを選択します。たとえば、すべてのマップ ペインは、Map オブジェクトによって管理される OperationManager に依存しており、同様に、レイアウトペインはLayoutオブジェクトによって管理されるOperationManagerを共有します。このように、同じマップのすべてのマップペインと同じレイアウトのすべてのペインは、それぞれ同じOperationManager を共有します。たとえば、フィーチャを削除すると、そのマップを表示しているすべてのマップ ペインの Undo/Redo スタックに表示され、同様に、レイアウトから要素を削除すると、そのレイアウトを表示しているすべてのレイアウト ペインのUndo/Redoスタックに表示されます。

操作を作成するには、Operation から派生するクラスを追加し、該当する OperationManager で Do() または DoAsync() を呼び出します。操作にデータが必要な場合は、コンストラクター オーバーライドを使用してこれを渡します。

特定のカテゴリにのみ属する操作を元に戻すことができるように、操作を分類することもできます。たとえば、ArcGIS Pro には編集およびマッピング操作があります。これらの操作が混在している場合、ユーザーは編集操作を元に戻し、マッピング操作をスキップすることを選択できます。分類された操作は、相互に排他的である必要があります。

ドラッグ アンド ドロップとは、通常、マウス（またはその他のポインティング デバイス）を使用して 1 つ以上のオブジェクトを選択し、これらのオブジェクトをユーザー インターフェイス（UI）の目的のドロップ ターゲットにドラッグして、それらにドロップするデータ転送方法を指します。ドラッグ アンド ドロップの動作には、常に 2 つの関係があります。ドラッグされているソース オブジェクトの発信元である ドラッグ ソースと、（ソースの）目的の受信者である ドロップ ターゲットです。ドラッグ ソースとドロップ ターゲットは、同じウィンドウでも異なるウィンドウでもかまいません。ドラッグ アンド ドロップを最初から実装する方法の詳細については、 Drag and Drop in WPFを、追加の背景情報については、 Drag and Drop Overview を参照してください。

アドイン内でのドラッグ アンド ドロップに対する Pro のサポートの詳細は次のとおりです。

ペインとドッキング ペインは、ArcGIS.Desktop.Framework.Contracts.PaneBase から2つの仮想メソッド OnDragOver と OnDrop を継承します。ペインの場合、OnDragOver と OnDrop は常に呼び出されます。ただし、ドッキング ペインは、DAML 宣言に isDropTarget="true" を追加して、自身をドロップ ターゲットとして明示的に設定する必要があります。

 <!-- declaring a drop-able dockpane in the config.daml -->
  <dockPanes>
    <dockPane id="DragAndDrop_DropDockpane1" caption="Drop Dockpane" className="..." 
           ... isDropTarget="true">
          <content className="DropDockpane1View" />
        </dockPane>
      </dockPanes>

*isDropTarget="true" はドッキング ペイン全体をドロップ ターゲットとして設定します。個々のコントロールをドロップ ターゲットとして構成するには、コントロールにドロップ を参照してください（この場合、isDropTarget="false"）。

OnDragOver

OnDragOver を使用すると、マウス カーソルがペインまたはドッキング ペインの上部を通過したときに、ドラッグされたデータを UI でプレビューできます。ドラッグされているものはすべて dropInfo.Data パラメータに含まれます。たとえば、ファイル ジオデータベース フォルダーの削除をサポートしている場合は、データを調べて、ファイル ジオデータベース フォルダーへのパスが含まれているかどうかを確認できます。さらに、ドラッグが（Windows エクスプローラーからではなく）Pro アプリケーション内で発生した場合、関連付けられた dropInfo.DragInfo はドラッグのソースに関する情報を提供できます。ペイロードが関連していない場合アドインは dropInfo.Effects を DragDropEffects.None に設定する必要があります。それ以外の場合は、それに応じて dropInfo.Effects を設定する必要があります。

OnDrop

DropInfo.Effects が OnDragOver で DragDropEffects.None 以外に設定されていて、ペイロードがペイン/ドッキング ペインに「ドロップ」されているとすると、OnDrop(DropInfo dropInfo) が呼び出されます。 アドインは通常、OnDrop 実装で 2 つの潜在的なデータ ソースを処理します。Pro カタログからドラッグされたデータと Windows エクスプローラーからドラッグされたデータです。Pro カタログからドラッグされたデータは、1つ以上の ArcGIS.Desktop.Core.ClipboardItem としてフォーマットされます。Windows エクスプローラーからドラッグされたデータは、1 つ以上の文字列で構成されます。各文字列には、（ドラッグされている）ソース データへのフルパスが含まれます。データは dropInfo から抽出され、必要に応じてアドイン ロジックによって処理されます。OnDrop は、dropInfo.Handled = true を設定して、ドロップがそれ以上処理されないようにする必要があります。

OnDragOver および OnDrop オーバーライドの例を次に示します。

  //just assume we handle it
  public override void OnDragOver(DropInfo dropInfo) {
      dropInfo.Effects = DragDropEffects.All;
  }

 public override async void OnDrop(DropInfo dropInfo) {
   //check for List<ClipboardItem> - this is a drag originating with Catalog
   string data_path = "";
   if (dropInfo.Data is List<ClipboardItem> clipboardItems)
   {
     //in this example, we handle just the first item if there are multiples being dragged
     var thisItem = clipboardItems.First();
     data_path = thisItem.CatalogPath;
   } 
   //Dragged from Windows Explorer?
   else if (dropInfo.DragEventArgs.Data.GetDataPresent(DataFormats.FileDrop))
   {
     data_path = dropInfo.Items[0].Data.ToString();//just the first in this example
   }
   if (string.IsNullOrEmpty(data_path))
     return;//we don't handle this
   //TODO
   //process the drop
   ...

   //set to true indicating we handled the drop
   dropInfo.Handled = true;
}

ドッキング ペインには、ドロップ ターゲットをドッキング ペイン自体全体にするか、テキスト ボックス、リスト ボックス、ツリー ビュー、リスト ビューなどの 1 つ以上の「内部」コントロールに限定するオプションがあります。ドロップ ターゲットを 1 つ以上の特定のコントロールに限定するには、

1. config.daml のドッキング ペイン宣言で isDropTarget = false を設定します。
2. ドロップをサポートするドッキング ペインの各コントロールに、アタッチされたプロパティ DragDrop.IsDropTarget と DragDrop.DropHandler（ArcGIS.Desktop.Framework.DragDrop 名前空間から）を追加します。DragDrop.DropHandler は、OnDragOver と OnDrop の実装を提供するドッキング ペインのプロパティにバインドする必要があります。これは、ドッキング ペイン自体、または ArcGIS.Desktop.Framework.Contracts.DropHandlerBase から派生した別のクラスにすることができます。

ドッキング ペインが「DropHandler」実装を提供すると仮定します。

<UserControl x:Class="DropDockpane1View"  ...
   xmlns:dragDrop="clr-namespace:ArcGIS.Desktop.Framework.DragDrop;
                   assembly=ArcGIS.Desktop.Framework">
  ...
  <!-- we allow drop on a text box - the dockpane implements OnDragOver and OnDrop-->
  <TextBox MinWidth="250" Text="{Binding ...}" 
          dragDrop:DragDrop.IsDropTarget" Value="True"
          dragDrop:DragDrop.DropHandler" Value="{Binding}" />

  //drop is implemented by the dockpane (OnDragOver and OnDrop)
  //drop allowed on the textbox only so isDropTarget=false in the config.daml
  internal class DropDockpane1 : DockPane {
    public override void OnDragOver(DropInfo dropInfo) {
       ...
    public override void OnDrop(DropInfo dropInfo) {

この例では、「DropHandler」実装がドッキング ペインではなく別の DropHandlerBase 実装によって提供されていると想定しています（DropHandler Binding ステートメントの違いに注意してください）。

  <!-- we allow drop on a text box - a DropHandlerBase implements OnDragOver and OnDrop-->
  <TextBox MinWidth="250" Text="{Binding ...}" 
          dragDrop:DragDrop.IsDropTarget" Value="True"
          dragDrop:DragDrop.DropHandler" Value="{Binding DropHandler}" />

  //provide a DropHandlerBase implementation in the add-in
  public class MyCustomHandler : DropHandlerBase {
     
    public override void OnDragOver(DropInfo dropInfo) {
       ...
    public override void OnDrop(DropInfo dropInfo) {

  //expose the DropHandlerBase on the dock pane
  //drop allowed on the textbox only so isDropTarget=false in the config.daml
  internal class DropDockpane1 : DockPane  {
         ...
         public MyCustomHandler DropHandler => _dropHandler;

OnDragOver と OnDrop の実装は以前と同じです。

アタッチされたプロパティを個々のコントロールに直接追加するのではなく、コントロール タイプごとのスタイル内に配置し、代わりにスタイルを参照することもできます。どのアプローチを使用するかは、実際には好みの問題です。次に、スタイルを使用して、添付されたドロップ プロパティをテキスト ボックスに割り当てる例を示します。

 <!-- define drop support as a style. Apply the style to the textbox -->
 <Style x:Key="MyTextBoxStyle" TargetType="{x:Type TextBox}">
        <Setter Property="dragDrop:DragDrop.IsDropTarget" Value="True" />
        <Setter Property="dragDrop:DragDrop.DropHandler" Value="{Binding}" />
 </Style>

 <!-- any Textbox that is to support drop references the style -->
 <TextBox MinWidth="250" Text="{Binding ...}" Style="{StaticResource MyTextBoxStyle}" />

ドッキング ペインのドラッグ アンド ドロップも ProGuide Dockpanes でカバーされています。

フレームワークは、Pro ウィンドウ（ダイアログなど）でのドラッグ アンド ドロップ操作もサポートしています。手順は上記の手順と似ていますが、この場合、添付されたプロパティを Pro ウィンドウ自体またはその中の 1 つ以上の子コントロールに追加します。

  <controls:ProWindow x:Class="DropExample.CustomProWindow"
               xmlns:dragDrop="clr-namespace:ArcGIS.Desktop.Framework.DragDrop;
				assembly=ArcGIS.Desktop.Framework"
               ...>
    <Grid>...
      <TextBox Text={Binding ...} dragDrop:DragDrop.IsDropTarget="True"
               dragDrop:DragDrop.DropHandler="{Binding WindowDropHandler}" .../>

Proウィンドウは、OnDragOver および OnDrop オーバーライドを提供しない ArcGIS.Desktop.Framework.Controls.ProWindow から派生しています。 したがって、Pro ウィンドウのドロップ動作は、ウィンドウのビュー モデルのプロパティとして公開されているドロップ ハンドラーの実装を介して処理する必要があります。

  //provide a DropHandlerBase implementation in the add-in
  public class MyCustomHandler : DropHandlerBase {
     //implemented as before with the dockpane
     ...
 
 //expose the drop handler on the window view model.
 public partial class CustomProWindow: ProWindow, INotifyPropertyChanged {

    public CustomProWindow() {
      InitializeComponent();
      (this.Content as FrameworkElement).DataContext = this;
      ...

   //drophandler referenced in the xaml via dragDrop:DragDrop.DropHandler
   public MyCustomHandler WindowDropHandler => _dropHandler;

カスタム ドロップ ハンドラーを config.daml 内に登録して、Pro のペインやドッキング ペインのデフォルトのドロップ動作をオーバーライドできます。これは、Pro でマップにドロップしたときに、独自のデータ型または「out of the box」で処理されない空間データ型を処理するように、アドインでマップのデフォルトのドロップ動作を強化する場合に役立ちます。カスタム ドロップ ハンドラーは、サポートするデータ型（通常はファイル サフィックスのコレクション）を config.daml 内に登録します。その指定されたファイルタイプのファイルが Pro 上にドラッグされている場合、カスタム ドロップ ハンドラーが基になる Pro ペインの前に呼び出され、ドロップを処理、または、処理しません。OnDragOver および OnDrop の処理について前述したものと同じルールが適用されます。ハンドラーがドロップを処理しない場合は、下にあるペインまたはドッキング ペインに渡されます。

この例では、Excel データ型のカスタム DropHandler が config.daml に登録されています。

  <dropHandlers>
    <insertHandler id="DragDropExample_ExcelDropHandler" 
         className="ExcelDropHandler" dataTypes=".XLSX|.xlsx|.XLS|.xls" />
  </dropHandlers>

Excel データのカスタム ハンドラーの完全な実装は、Pro SDK の ExcelDropHandler サンプルにあります。

注：Pro SDK は、Config.daml エントリを自動的に生成し、関連する DropHandlerBase 実装をスタブ化するアイテム テンプレート ArcGIS Pro ドロップ ハンドラーを提供します。

ドラッグ サポートは、ArcGIS.Desktop.Framework.DragDrop.IDragSource の実装と組み合わせて、DragDrop.IsDragSource および DragDrop.DragHandler の添付プロパティを使用して、ドッキング ペイン（またはペインですが、それは稀です）および/またはドッキング ペインの個々のコントロールに追加できます。 IDragSourceは、ドッキング ペインに直接実装することも、別のカスタム ドラッグ ハンドラーに実装することもできます（必要に応じて、DropHandlerBase 基底クラスを介してドロップ動作を実装するのと同じクラスにすることができます）。IDragSource は任意のクラスに追加でき、drop の場合のように特定の継承階層を必要としません。

IDragSource.StartDrag ドラッグが開始されると、ドラッグ ソースで呼び出されます。StartDragIDragSource を使用すると、IDragSource は dragInfo.SourceItem プロパティを介して（または独自のコンテキスト メカニズムを介して）ドラッグされているものを確認できます。ドラッグ ソースがサポートするものでドラッグが開始されている場合は、IDragSource で続行できます。それ以外の場合は、ドラッグが停止します。 ドラッグの続行が許可されたときに dragInfo.Data が正しく設定されていることを確認するのは、IDragSource の責任です。dragInfo.Data は、StartDrag コールバックに渡されると null になります。dragInfo.Data は任意の形式に設定できますが、ドッキング ペインから Pro のドッキング ペインまたはペイン（マップ、カタログなど）の 1 つへのドラッグをサポートするには、データ ペイロードを ClipboardItem のリストとしてフォーマットする必要があります。StartDrag は、dragInfo.Effects を System.Windows.DragDropEffects.None 以外に設定する必要もあります。dragInfo.Effects を DragDropEffects.None （デフォルト）に設定したままにしておくと、ドラッグが効果的に終了します。

以下の例では、ファイル ジオデータベース内に含まれるフィーチャ クラスとテーブルを表示しているカスタム ドッキング ペインにツリー ビューがあると想定します。ツリー ビューのアイテムは、GDBBaseItem アドインで定義されたカスタム クラスによって表されます。それぞれの GDBBaseItem が、ツリー ビューに表示されるフィーチャ クラスまたはテーブルへのパスと名前を提供します。

ユーザーは、ファイル ジオデータベースをカスタム ドッキング ペインにドラッグして、ツリー ビューにデータを入力します。同様に、ユーザーは任意のフィーチャ クラスまたはテーブルをツリー ビューからマップにドラッグできます。マップのデフォルトのドロップ ハンドラーは、ドロップされたデータをレイヤー（またはスタンドアロン テーブル）として追加します。

 <!-- enable drag on our treeview -->
 <TreeView ItemsSource="{Binding GDBItems}" ...
           dragDrop:DragDrop.IsDragSource="True"
           dragDrop:DragDrop.DragHandler="{Binding}">

コード ビハインド：

  //our custom wrapper of a feature class or table for the treeview
  public class GDBBaseItem {
      public string Path ...
      public string Name ...

      //get an iteminfovalue for use with the ClipboardItem
      public virtual ItemInfoValue GetItemInfoValue() {
         var uri = Path + @"\" + Name;  //i.e. a "catalog" path format
         var gdb_item = ItemFactory.Instance.Create(uri);

         //ClipboardItem needs an ItemInfoValue
         return new ItemInfoValue() {
            name = gdb_item.Name,
            title = gdb_item.Name,
            catalogPath = gdb_item.Path,
            type = gdb_item.Type,
            typeID = gdb_item.TypeID,
            isContainer = "false"
         };
       }
    
 //Custom drag for the dockpane - note the IDragSource declaration
 internal class DragDockpane1ViewModel : DockPane, IDragSource {

   //IDragSource implementation
   public void StartDrag(DragInfo dragInfo)
    {
      if (dragInfo.SourceItem == null)
        return;
      var gdbItem = dragInfo.SourceItem as GDBBaseItem;
      ...
      //Add the drag content as a List<ClipboardItem>
      List<ClipboardItem> clip_items = new List<ClipboardItem>();
      clip_items.Add(new ClipboardItem() {
        ItemInfoValue = gdbItem.GetItemInfoValue()
      });
      dragInfo.Data = clip_items;
      dragInfo.Effects = DragDropEffects.Copy;
    }

上に示したドラッグ アンド ドロップの完全なサンプルは、DragAndDrop からアクセスできます。

注：添付プロパティ DragAdornerTemplate を設定することにより、ドラッグされているデータのプレビューを表示する透明な画像であるドラッグ装飾をオプションで変更できます。

  dragDrop:DragDrop.DragAdornerTemplate="{StaticResource LayerDragAdorner}"

トースト通知は、画面の右上隅に一時的なポップアップとして表示され、システムの変更をユーザーに知らせるために使用されます。通知は、ソフトウェア内の複数のポイントから受信でき、最大 4 レベルでスタックされ、短時間またはユーザーが通知をクリックするまで表示されます。通知はキューに入れられるため、短期間に 4 つを超える通知が届いた場合でも、最終的にはすべて通知が表示されます。

通知は、タイトル、キャプション、および画像に関連付けることができます。また、クリック通知を処理して、トーストがクリックされたときに特定のアクションを実行するようにします。ArcGIS.Desktop.Framework.Notification クラス（topic10177.html）を使用して通知を作成します。静的な ArcGIS.Desktop.Framework.FrameworkApplication.AddNotification() メソッド（ topic10141.html）を介して Pro に通知を追加します。

  Notification toast = new Notification();
  toast.Title = "Attention!";
  toast.Message = "This is an example notification";
  toast.ImageSource = Application.Current.Resources["ToastLicensing32"] as ImageSource;

  FrameworkApplication.AddNotification(toast);

ArcGIS Pro 3.1 では、より複雑なコンテンツをトースト通知エリア内に表示できます。これには、ハイパー リンク、さまざまなスタイル、サイズ、カラーが適用されたテキストが含まれます。

  Notification toast = new Notification();
  toast.Title = "Attention!";
  toast.Message = "{\\rtf1{\\colortbl ;\\red33\\green181\\blue54;}" +
                "This is a message\\par{\\b {\\field{\\*\\fldinst{HYPERLINK \"https://www.esri.com/\" }}" +
                "{\\fldrslt{\\ul\\cf1 Hyperlink\\cf0 }}}}}";
  toast.ImageSource = Application.Current.Resources["ToastLicensing32"] as ImageSource;           
  
  FrameworkApplication.AddNotification(toast);

クイック アクセス ツールバー（QAT）は、アプリケーションによって指定された、またはユーザーによって選択されたコマンドのコレクションを公開する、小さくカスタマイズ可能なツールバーです。ツールバーはデフォルトでアプリケーションの左上隅に表示されますが、ユーザーはリボンの下に移動できます。QAT には、ユーザーがツールバーのコマンドを非表示（または表示）できるプル ダウン メニューもあります。

QAT は、クイック アクセス ツールバーのカスタマイズ QAT メニューを介してインタラクティブに変更されます。[その他のコマンド...] を選択すると、プロジェクト オプション プロパティ ページが開き、QAT に追加する追加のコマンドを選択したり、既存のコマンドを削除したりできます。

ConfigurationManager.OnCreateQuickAccessToolbar コールバックをオーバーライドすることで構成内の QAT を変更することは可能ですが、QAT を DAML 経由で変更することはできません。詳細については、ProConcepts Configurations OnCreateQuickAccessToolbar を参照してください。

通知ドッキング ペインは、ユーザーがアプリケーションとプロジェクトの通知を表示するための中心的な場所を提供します。通知は Pro 全体で使用され、ソフトウェアの更新、表示の警告、レイヤーとパッケージの更新、および一般的なメッセージが含まれます。 通知は、アプリケーションとプロジェクトの 2 つのカテゴリに分類されます。通知ドッキング ペインに通知を送信するには、 ArcGIS.Desktop.Framework.NotificationItem クラス（topic18271）を使用し、NotificationManager.AddNotification()（topic18300.html）を介して、NotificationItem を ArcGIS.Desktop.Framework.NotificationManager に追加します。NotificationItems は、メッセージ、より詳細なメッセージ、画像、日付、アクション（つまり、コールバック）、さらにはコンテキスト メニュー項目を指定できます。カスタム コールバック（指定されている場合）は、通知がクリックされたときに何が起こるかを制御します。 NotificationManfager が通知を受信すると、Pro アプリケーションの右上隅にある[通知]ボタンに、通知が利用可能であることを示す青い点が表示されます。通知ドッキング ペインがまだ表示されていない場合は、ボタンをクリックすると通知ドッキング ペインが表示されます。ArcGIS Pro Notifications を参照してください。

このコード例では、プロジェクト レベルの通知アイテムと、通知アイテムがクリックされたときのカスタム デリゲートを作成します。通知項目をクリックすると、デリゲートが呼び出されます（この特定のケースではメッセージ ボックスが表示されます）。

   //delegate is custom - your design (name, params, functionality, etc)
    public delegate void MyCustomDelegate(int x);

   ...
    //Elsewhere....the callback itself for when the notification item is clicked
    private void ShowMessage(int x)
    {
      System.Windows.MessageBox.Show("This is the delegate. Param x: " + x.ToString());
    }
    ...
   
    //Create a Notification Item in response to whichever event or circumstance
    //
    var custom_delegate = new MyCustomDelegate(ShowMessage);//optional - for callback

    //Note: 2nd param: isApplicationLevel = true for application level, 
    //                 isApplicationLevel = false for Project level
    var ni = new NotificationItem("Module1_CustomNotification", false, "Custom Item", 
                                  NotificationType.Custom, "some details here", true, 
                                  DateTime.Now, "", "View Item", custom_delegate, 
                                  new object[] { 3 }));

    //add the notification item to the manager
    //a blue dot will appear on the notifications icon on the Pro ribbon
    NotificationManager.AddNotification(ni);
    ...
    

ArcGIS Pro は、次のコマンド ライン スイッチを介して有効にする診断モードをサポートしています。

/enablediagnostics

このモードは、シンプルな単一アプリケーション全体のロギング機能（ファイル ベース）を提供します。ログに記録される各イベントは、タイム スタンプとタイプ（警告、エラー、または情報）を含む単純な文字列です。ログの形式と使用法は Windows イベント ログに似ていますが、独立した XML ファイルに保存されます。イベント文字列にはキャリッジ リターンを含めることができ、それに応じて XML ログ ファイル内で適切にフォーマットされます（以下の例を参照）。

イベント ログに書き込まれるイベントは、外部ユーザーまたは開発者が問題を診断するのを支援することを目的としているため、確実で明確である必要があります。例外文字列と同様に、診断モードのイベント文字列は英語のみです。

注意：識別情報、パスワード、または機密情報を含む可能性のある文字列をイベントログに記録しないでください。

新しい空のログ ファイルは、アプリケーションを起動するたびに作成されます。ログ ファイルは、ArcGIS\Diagnostics サブフォルダーの下のユーザーのドキュメント フォルダー内に作成されます。ログ ファイル自体は ArcGISProLog.xml と呼ばれます。ログが 10MB を超えると、古いエントリはログから削除されます。

ログの内容の例：

<?xml version="1.0"?>
<EventLog ver="1">
  <Event time="Wed Oct 14 10:12:31 2015" type="Info">Application startup.</Event>
  <Event time="Wed Oct 14 10:12:38 2015" type="Error">
      An error was encountered when importing document “junk.mxd”.
      One or more layers were invalid.
  </Event>
</EventLog>

サード パーティは、ArcGIS.Desktop.Framework.Utilities から公開された EventLog 静的クラスを使用して、独自の出力をイベント ログに追加できます。EventLog.Write() 診断モードが有効になっていない場合、呼び出しは無処理であることに注意してください。したがって、診断モードであるかどうかを判断するために、アドインにロジックを書き込む必要はありません。ログに書き込まれたイベントは、アプリケーションのシャット ダウン時にディスクにフラッシュされます（例外によってアプリがダウンした場合でも）。ただし、アプリケーションの実行中にログ ファイルに表示する場合は、すぐに書き込むオプションがあります。

  //class located in ArcGIS.Desktop.Framework.Utilities
  public static class EventLog
  {
    public enum EventType
    {
      Debug,
      Error,
      Warning,
      Information 
    }

    public static bool IsEnabled
    public static void Write(EventType type, string entry, bool flush)
    public static void Write(EventType type, string entry, uint elapsed, bool flush)
    public static void Write(EventType type, string entry, string func, string code, uint elapsed, bool flush)
  }

さらに、Write メソッドのオーバーロードを使用して、3 つのオプションの引数を書き込むことができます。

• elapsed：イベントに関連付けられた操作の実行に経過したミリ秒数を含む符号なし整数。
• func: イベントに関連付けられた関数の名前。
• code: 指定された関数に関連付けられた汎用コード。

指定した場合、これらのオプションの情報ビットは、イベント エントリの属性として表示されます。可能な場合は常に、同様の情報を information 引数にエンコードする代わりに、これらのイベントを使用する必要があります。これにより、形式が標準化され、後でログ分析中にこれらのフィールドに基づいてクエリを実行するのがはるかに簡単になります。

  EventLog.Write(EventLog.EventType.Warning, 
    String.Format(
      "Add-In {0} has been disabled due to an exception thrown during component initialization.", 
         id));

EventLog クラスには、カウント（または数値）を名前付きカウンターに関連付けることができる診断カウンター メソッドも含まれています。診断モードで実行されているアプリケーションが終了すると、現在登録されているすべてのカウンターがログの最後のレポートに表示されます。

EventLog.IncrementCounter("MyCounterName");

ArcGIS Proは、複数の実行コアを備えた最新のCPU/GPUを活用するように設計されたマルチスレッド アーキテクチャで構築されているという点で、既存の ArcGIS for Desktop アプリケーションとは大きく異なります。ArcGIS Pro を拡張するアドイン開発者にとって、これはプログラミング モデルの変更と、最初は不可解に見えるかもしれないいくつかの新しい概念に精通する必要があることを意味します。新しいものと同様に、これらのパターンでの作業は徐々に簡単になり、マルチスレッドの利点はますます明らかになります。詳細については、Pro Concepts Asynchronous Programming in ArcGIS Pro を参照することもできます。

次の 4 つの主な違いは、ArcGIS Pro を含むマルチスレッド アプリケーションを、従来のシングルスレッド アプリケーションと区別します。

• 応答性の高いユーザー エクスペリエンスを確保するには、グラフィカル ユーザー インターフェイス（GUI）スレッドがユーザーからの入力を受け取り、中断することなくスムーズにグ​​ラフィック出力を生成できる必要があります。つまり、コード化されたアクションの実行は、別々のワーカー スレッドで非同期に実行する必要があります。GUI スレッドは、いかなる種類の作業やブロック待機も実行しないでください。これは、ほとんどの作業が単一の GUI スレッドで直接実行される既存の ArcGIS for Desktop アプリケーションとは対照的です。

• 作業がバックグラウンド スレッドで実行されている間、ユーザーには論理的に一貫性のある有益なユーザー インターフェイスを提示する必要があります。コマンド、ツール、およびユーザー インターフェイスの他のさまざまな部分は、実行中の操作に基づいて適切に有効または無効にし、適切なフィードバックを提供する必要があります。長時間実行されている操作が論理的にキャンセル可能な場合は、キャンセルするオプションを提供する必要があります。

• 競合する操作は同時に実行するべきではなく、常に適切な論理シーケンスで実行する必要があります。たとえば、マップを含むプロジェクトがまだロード中の間は、マップの操作を実行できません。また、選択自体が完全に処理されるまで、選択したフィーチャのセットを削除することはできません。ユーザー操作によって開始されるほとんどの操作は、論理的順序に依存するため、順次実行する必要があります。

• 揮発性状態へのアクセス、つまりプログラム内の非定数変数へのアクセスが、そのような状態がスレッド間で共有されるときに適切に同期されるように注意する必要があります。たとえば、コレクション オブジェクトがワーカー スレッドと GUI スレッドの間で共有されている場合、両方のスレッドがコレクションへのアクセスを調整して、一方のスレッドがコレクションからアイテムを読み取らないようにし、もう一方のスレッドが同時にアイテムを追加または削除するようにする必要があります。この種の保護コーディングは、すべての種類のマルチスレッド プログラミングに共通であり、通常はロックを使用して実行されます。複数の独立した関係者がアプリケーションの動作を拡張できるアプリケーションでは、コンポーネントの連携方法を管理するための共通のフレームワークがないと、調整操作が機能しなくなる可能性があります。

マルチスレッド プログラミングの完全な取り扱いはこのドキュメントの範囲を超えていますが、以下の情報では、Esri の API とスレッド モデルを使用して前述の各課題に取り組む方法とともに、最も一般的なパターンについて説明します。

Esri のエンジニアは、新しいマルチスレッド アーキテクチャで ArcGIS Pro を可能な限り簡単にプログラミングできるようにすることを最優先しています。この目的のために、ArcGIS Pro には、コーディングの複雑さを軽減するように調整された新しいアプリケーション固有のスレッドインフラストラクチャとともに、Microsoft の最新の非同期言語機能が組み込まれています。

ほとんどの場合、アドイン開発者は、ユーザー インターフェイス スレッドと、アプリケーションによって提供される単一の専用ワーカー スレッドの 2 つのスレッドとのみ競合する必要があります。内部的には、ArcGIS Pro は、ラスタライズ、グラフィック レンダリング、データの読み込み、並列処理を活用して計算を高速化するジオプロセシング アルゴリズムの選択などの目的で、多数のスレッドを使用します。これらすべてのアクティビティをスムーズに、競合することなく実行し続けるには、かなりの量の調整とそれに関連する複雑さが必要です。このため、これらのスレッドは完全に内部にあり、パブリック SDK の実装内の開発者から分離されています。パブリック API のメソッドが呼び出されると、内部実装は、該当する場合、操作を分割し、フラグメントをこれらの特殊な内部スレッドの1つ以上に委任する場合があります。

ArcGIS Pro SDK内のメソッドは、次の3つのカテゴリに分類されます。

• 任意のスレッドで呼び出すことができる非同期メソッド。このタイプのメソッドは、Async サフィックスを使用して名前が付けられ、通常はタスクを返します。場合によっては、メソッドの同期バージョンと非同期バージョンの両方が提供されることがあります。

• ワーカー スレッドでのみ呼び出す必要がある同期メソッド。このタイプのメソッドは API リファレンス内で注釈が付けられており、メソッドにカーソルを合わせるとコードのヒントが表示されます。

• GUI スレッドでのみ呼び出す必要のある同期メソッド。これらのタイプのメソッドは通常、WPF に関連付けられています。

特定のオブジェクトのメソッドが間違ったスレッドで呼び出された場合、その呼び出しによって ArcGIS.Core.CalledOnWrongThreadException 例外が生成されます。特定のケースについて不明な点がある場合は、SDK コンポーネントのヘルプまたは Microsoftが提供するヘルプを参照して、特定のメソッドまたはプロパティに制限があるかどうかを判断できます。

SDK 内（特に ArcGIS.Core 名前空間内）では、ワーカー スレッドにバインドされたメソッドとプロパティは非常にきめ細かい傾向があります。スケジューリングとスレッドコンテキスト スイッチに関連するオーバーヘッドを減らすために、これらのメソッドは同期的であり、タスクを使用してコーディングする必要があります。

Microsoft の .NET タスク並列ライブラリ TPL と、タスク非同期パターン TAP と呼ばれる関連するプログラミング パターンにより、マルチスレッド アプリケーション内での非同期コードの作成が簡素化されます。Task クラスは、非同期で実行される操作を表すために使用されます。

次の例では、PrintReportAsync メソッドが呼び出され、すぐに Task オブジェクトが呼び出し元に返されます。その間、印刷機能は別のスレッドのバックグラウンドで実行され続けます。

  private void Button_Click(object sender, RoutedEventArgs e)
  {
    Task t = PrintReportAsync("HP1");
    // Wait until the task is done.
    t.Wait();
    MessageBox.Show("Printed report is ready!");
  }

例の作成者は、印刷が完了したときにメッセージを表示したいと考えており、返された Task オブジェクトで Wait メソッドを使用して、タスクが完了するまで呼び出しスレッドを一時停止します。このアプローチには 2 つの大きな問題があります。1 つは、呼び出し元のスレッドが待機中に他に何もできないため、実際には、単に同期バージョンの print 関数を呼び出すよりも効率が悪いことです。次に、この場合、呼び出し元のスレッドは GUI スレッドであるため、ユーザー インターフェイスがフリーズします。中断されたスレッドは、明らかにユーザー入力を処理したり、グラフィック要素をレンダリングしたり、そのことに関して何もすることはできません。これらの理由から、GUI スレッドで Wait メソッドを使用しないでください。

幸いなことに、.NETは言語機能 async と await を導入しました。async修飾子はメソッドをマークして、コンパイラーがメソッドが非同期であり、await演算子を使用することを認識できるようにします。await演算子は、メソッドを非同期で呼び出した後、呼び出し元のスレッドを自動的に次の行に戻し、非同期操作が完了したら実行を継続するために使用されるため、最も役立ちます。呼び出し元のスレッド（通常は GUI スレッド）はブロックされず、ワーカー スレッドのタスクの実行中に他のアクションを自由に実行できます。

作成者はほとんど変更を加えることなく元の目標を達成しましたが、ユーザー インターフェイスをハング アップさせないことに注意してください。

  private async void Button_Click(object sender, RoutedEventArgs e)
  {
    Task t = PrintReportAsync("HP1");
    // Wait (without blocking) until the task is done.
    await t;
    // Return here when task is done.
    MessageBox.Show("Printed report is ready!");
  }

非同期関数が使用できない場合は、1 つ以上の同期メソッドを内部的に実行する独自のラッパー関数を簡単に作成できます。次のサンプルでは、​​静的Runメソッドを使用して、関数WorkFuncの実行をタスク スレッド プール内のランダム スレッドにキューイングします。WorkFunc がワーカー スレッドで実行を継続している間、click メソッドはすぐに呼び出し元に戻ることに注意してください。

  private void Button_Click(object sender, RoutedEventArgs e)
  {
    Task t = Task.Run((Action)WorkFunc);
  }
  private void WorkFunc()
  {
    // Do Work
  }

別の関数を使用する代わりに、ラムダと呼ばれる無名関数を使用できます。ラムダを使用すると、ワーカー コードが同じ関数内に保持され、ラムダ内で引数とローカル変数を、それらが含まれている関数の一部であるかのように使用できます。

  private void Button_Click(object sender, RoutedEventArgs e)
  {
    int steps = GetSteps();
    Task t = Task.Run(() =>
    {
      // I can use the variable “steps” here even though I'm in a
      // different function running on a different thread!
      // Do work
    });
  }

ラムダが計算した結果として、タスクをパラメーター化して特定の型を返すこともできます。

  Task<double> t = Task.Run<double>(()=>
  {
    double result;        
    // Compute floating point result here...
    return result;
  });

await 演算子をインラインで使用して、非同期関数の結果を取得することもできます。返されたタスクから結果を抽出する必要はありません。

  private async void Button_Click(object sender, RoutedEventArgs e)
  {
    double computedValue = await Task.Run<double>(()=>
    {
      double result = 42.0;        
      // Compute floating point result here...
      return result;
    });
    // Execution automatically resumes here when the Task above completes!
    MessageBox.Show(String.Format("Result was {0}",  computedValue.ToString()));
  }

await に関連するオーバーヘッドは小さいため、await を使用して多くの非同期関数を呼び出すよりも、独自のラムダ内で複数の同期メソッドを呼び出す方が常に効率的です。これは、コーディングループの場合に特に当てはまります。この場合、数百または数千回の反復でawaitを使用するコストがかなり大きくなります。

タスクはアドイン コード内の通常のフィクスチャですが、タスクは従来の TAP とは異なる方法で ArcGIS Pro にディスパッチする必要があります。フレームワークは、ArcGIS Pro SDK 内の同期メソッドを呼び出すタスクをディスパッチするときに使用する必要があるカスタム タスク スケジューラを提供します。ただし、アドイン開発者はTask.Runを呼び出すのではなく、代わりに QueuedTask.Run を呼び出す必要があります。

  Task t = QueuedTask.Run(()=>
  {
    // Call synchronous SDK methods here
  });