◀ 17.

Revit API 外部コマンド・外部アプリ｜IExternalCommand/Application・RibbonPanel・PushButton・ExternalEvent

編集
Revit API · 17

外部コマンド／アプリ

アドインの「入口」と「UI」を作るのが外部コマンドと外部アプリです。リボンに自分のボタンを並べ、ダイアログから安全にモデルを操作する。本格的な拡張ツールに欠かせない仕組みを解説します。

この記事の要点

  • IExternalCommand はボタン実行型。Execute を実装し、結果を Result で返す
  • IExternalApplication は起動時常駐型。OnStartup で初期化、OnShutdown で後始末する
  • リボン UI は OnStartup 内で RibbonPanel を作り、PushButton を追加して構築する
  • モードレスダイアログから安全にモデルを操作するには ExternalEvent（外部イベント）を使う

この記事は Revit カテゴリの一部です。開発の前提は 開発環境構築、API の全体像は Revit API 概要 を参照してください。

1外部コマンド（IExternalCommand）

IExternalCommand は、リボンのボタンなどから 1 回実行される処理を表すインターフェースです。実装するのは Execute メソッドだけで、処理の成否を戻り値で返します。

Result.Succeeded正常終了。変更がコミットされる
Result.Cancelledユーザーがキャンセル。変更は取り消される
Result.Failedref string message にエラー文を入れると Revit が表示する

戻り値が Cancelled / Failed の場合、自動トランザクションモードでは変更がロールバックされる点を覚えておきましょう。

2外部アプリ（IExternalApplication）

IExternalApplication は Revit 起動時にロードされ、セッション中ずっと常駐するアドインです。リボンの構築やイベント購読など「最初に一度だけ行う初期化」を担います。

OnStartupUIControlledApplication app
  • 起動時に呼ばれる
  • リボンタブ／パネル／ボタンの作成
  • ドキュメントイベントの購読
OnShutdownUIControlledApplication app
  • 終了時に呼ばれる
  • イベントの購読解除など後始末

どちらも成功時は Result.Succeeded を返します。.addin マニフェストでは Type="Application" として登録します。

3リボン UI（RibbonPanel と PushButton）

独自のボタンは OnStartup の中で構築します。タブ → パネル → ボタンの順に組み立て、ボタンに外部コマンドのクラスを紐づけます。

using Autodesk.Revit.UI;

public Result OnStartup(UIControlledApplication app)
{
    string tab = "MyTools";
    app.CreateRibbonTab(tab);
    RibbonPanel panel = app.CreateRibbonPanel(tab, "ユーティリティ");

    string asm = System.Reflection.Assembly
                    .GetExecutingAssembly().Location;

    PushButtonData data = new PushButtonData(
        "btnHello", "Hello",
        asm, "MyAddin.HelloWorldCommand");
    panel.AddItem(data);

    return Result.Succeeded;
}

PushButtonData の第 3 引数にアセンブリのパス、第 4 引数に呼び出すコマンドの完全修飾クラス名を渡します。アイコン画像やツールチップは PushButton のプロパティで設定できます。

4外部イベント（ExternalEvent）とモードレス

Revit API には「API はトランザクション可能なコンテキスト（Revit の操作中）からしか呼べない」という制約があります。モーダルダイアログ（操作をブロックするウィンドウ）なら問題ありませんが、画面を見ながら操作できる「モードレス」ダイアログから直接 API を呼ぶと例外になります。

これを解決するのが ExternalEvent（外部イベント）です。IExternalEventHandler を実装したハンドラを登録し、モードレス UI 側からは ExternalEvent.Raise() を呼ぶだけにします。すると Revit が安全なタイミングでハンドラの Execute を実行し、その中でトランザクションを伴うモデル操作ができます。

要素役割
IExternalEventHandlerExecute(UIApplication app) と GetName() を実装する。実際のモデル操作はここに書く
ExternalEvent.Create(handler)ハンドラからイベントを生成（通常 OnStartup 時）
Raise()モードレス UI のボタン等から呼ぶ。実行要求をキューに積む

常駐パネルやドッキングウィンドウを持つ本格的なツールでは、この外部イベントの仕組みが必須になります。逆に言えば、単純なボタン 1 つで完結する処理ならモーダルダイアログで十分で、外部イベントを持ち出す必要はありません。常駐ウィンドウから選択や入力を受け取りながらモデルを書き換える、といった対話的なツールに進む段階で初めて、ExternalEvent の出番になると考えておくとよいでしょう。

入口を整えて「ツール」にする

処理ロジックができても、それを呼び出す入口がなければツールになりません。1 回実行なら IExternalCommand、常駐＆UI 構築なら IExternalApplication。リボンに PushButton を並べれば操作性が一気に上がり、モードレス対応が必要なら ExternalEvent でトランザクション制約を回避します。これらを組み合わせることで、配布できる完成度のアドインに仕上がります。

UI まで作れれば、Revit API の基本サイクルは一通り押さえたことになります。要素の集め方や編集を振り返るなら 要素の取得とフィルタ や トランザクションと要素編集 へ。

2つの入口のライフサイクル IExternalApplication（常駐型） OnStartup Revit 起動時に1回 リボン UI を構築 RibbonPanel に PushButton 追加 OnShutdown 終了時に後始末 IExternalCommand（実行型） リボンのボタンを押す Execute 押すたびに呼ばれる Result を返す Succeeded / Cancelled / Failed ボタンに紐づけ
図: 2つの入口 — IExternalApplication は起動時 OnStartup でリボン UI を構築し終了時 OnShutdown で後始末する常駐型。IExternalCommand はボタンを押すたび Execute が呼ばれ Result を返す実行型。

→次に読む

Revit API · 13開発環境構築 カテゴリRevit トップ
編集
Post Share
子ページ

子ページはありません

同階層のページ
  1. Revitとは
  2. ファミリ（システム/ロード/インプレイス）
  3. カテゴリ・タイプ・インスタンス
  4. パラメータ（プロジェクト/共有/グローバル/ファミリ）
  5. レベルと通り芯
  6. ビューとビューテンプレート
  7. シートと図面化
  8. スケジュール表（集計表）
  9. ワークシェアリングと中心ファイル
  10. フェーズとデザインオプション
  11. リンクと座標連携
  12. Dynamo入門
  13. 開発環境構築（Visual Studio ＋ .addin マニフェスト）
  14. Revit API 概要
  15. Revit API：要素の取得とフィルタ
  16. Revit API：トランザクションと要素編集
  17. Revit API：外部コマンド／アプリ
2026-06-29 15:02:35 atom 2

人気ページ

最近更新/作成されたページ