AutoCAD アドオン開発者のためのRevit API入門～アドイン

概説に続いて、Revit API を用いた実装形態の 1 つである アドインアプリケーションについてご紹介します。アドインも、AutoCAD でアドオン、3ds Max でプラグインと呼ぶものと同じロードモジュールで、API を利用してデスクトップ製品を拡張する能力を提供します。

Revit API を用いたカスタマイズの目的には、AutoCAD と同じようにカスタムコマンドの作成を挙げることが出来ます。コマンドは Revit でも機能実行の最小単位であり、Revit を利用する設計者は、Revit に標準で組み込まれたコマンドをリボンインタフェースから選択して、モデルやシートを作成していきます。このコマンドを定義するためには、単に Revit API をアドインの中で利用する必要があります。

ここで言うアドインとは、AutoCAD 用に AutoCAD .NET API を使ってビルドしたアドオンアプリケーション（DLL アセンブリ）と同じ意味合いを持ちます。アドインを開発するためには、基本的に Revit 製品自身を利用する .NET Framework と同じバージョンを用いたアセンブリをビルドする、Visual Studio が必要となります。Revit 2014 の場合には、Visual Studio 2010 がサポートバージョンとなります。

さて、AutoCAD のコマンドに実行コンテキストによる区分がありましたが、Revit には、別の区分が存在しています。それが、外部コマンド と 外部アプリケーション です。Revit にはAutoCAD のようなコマンドプロンプトウィンドウは存在しないので、コマンドを直接入力して実行することは出来ません。いずれのタイプのコマンドも、Revit 上のユーザインタフェース（ボタンまたはメニュー）から起動して実行することになります。

外部コマンド

アドインで外部コマンドを定義すると、Revit 上では [アドイン] リボンパネルの [外部ツール] ボタンの下に、コマンド名が表示されることになります。ソースコード上で外部コマンドを定義するには、IExternalCommand インタフェースから派生したクラスを定義します。次の例は、C# 言語で記述された外部コマンドのスケルトンコードです。

[Transaction(TransactionMode.Manual)]
public class HelloWorld : IExternalCommand
{
public Result Execute(ExternalCommandData commandData,
ref string message,
ElementSet elements)
{

// 実装を記述

return Result.Succeeded;
}
}

この例では、HellowWorld というクラス名で外部コマンド用のクラスを定義しています。このクラスで実際に実行される外部コマンドは、Execute メソッド（必須）になります。

AutoCAD .NET API の場合、コマンド定義関数の前にコマンド属性を記述して、そこでコマンド名やコマンドグループ、コマンドフラグといった情報を与えますが、Revit ではコマンド属性にトランザクションモード（後述）を与えるのみです。

[外部コマンド] ボタンの下に表示されるコマンド名は、Visual Studio 上で記述したソースコード上の文字列ではなく、後述するアドインマニフェストで記述したものが表示されます。AutoCAD と同じように、1 つのアドインには複数の外部コマンドを定義することが出来ます。また、起動中の Revit には、それぞれ外部コマンドを定義した複数のアドインをロードすることが出来ます。そのような場面では、AutoCAD のプルダウンメニューのようなかたちでコマンドが表示されることになります。

外部アプリケーション

外部コマンドを沢山登録してしまうと、使用したいコマンドがどこにあるのかわかり難くなってしまいます。そこで、専用のアイコンを持ったボタンやリボンパネル、また、リボンタブを用意したいと考えるのが一般的です。外部コマンドには、そのような独自のユーザインタフェースを実装する機能がありません。ただし、外部アプリケーションなら可能です。

次の例は、C# 言語で記述された外部アプリケーションのスケルトンコードです。どこにもコマンドに必要な属性情報の設定がないことがわかります。また、IExternalApplication インタフェースから派生したクラス内に、OnStartup() と OnShutdown() があり、引数として UIControlledAppication オブジェクトが渡されています。

class App : IExternalApplication
{
public Result OnStartup(UIControlledApplication a)
{
return Result.Succeeded;
}

public Result OnShutdown(UIControlledApplication a)
{
return Result.Succeeded;
}
}

この例が示すとおり、外部アプリケーションとは、ボタンやリボンパネル、リボンタブといったユーザインタフェース要素やイベントの追加や削除の処理に使用するもので、コマンドそのものを定義するものではありません。別の言い方とすると、外部アプリケーションで作成したボタンなどがクリックされた際に、どの外部コマンドを実行するのかを定義するのが外部アプリケーションの役割です（ボタンと外部コマンドの関連付け）。

外部アプリケーションと外部コマンドは、同じアドインモジュールの中に定義することが可能です。また、外部アプリケーションを定義したアドインから、別のアドインが定義した外部コマンドを呼び出すようなことも出来ます。

次の例は、RevitLookup.dll アセンブリで定義された外部コマンド HelloWorld を、独自のリボンパネル上に配置したボタンで実行させる処理の例です（パスなどは省略しています）。この記事の最初に表示した外部アプリケーションのボタンが、このコードが実現する処理の結果となります。

class App : IExternalApplication
{
public Result OnStartup(UIControlledApplication a)
{
    RibbonPanel ribbonPanel =
a.CreateRibbonPanel("NewRibbonPanel");
    PushButton pushButton = ribbonPanel.AddItem(
new PushButtonData("HelloWorld",
"HelloWorld",
@"C:\RevitLookup.dll",
"RevitLookup.HelloWorld")
) as PushButton;
    Uri uriImage = new Uri(@"C:\earth.ico");
    BitmapImage largeImage = new BitmapImage(uriImage);
    pushButton.LargeImage = largeImage;
    return Result.Succeeded;
}

public Result OnShutdown(UIControlledApplication a)
{
    return Result.Succeeded;
}
}

外部アプリケーションと外部コマンドの違いは、独自のユーザインタフェースを持つか否かであって、AutoCAD のドキュメント実行コンテキストとアプリケーション実行コンテキストの違いとは全く別物と考えることが出来ます。

コマンド内のトランザクション

AutoCAD の ObjectARX や .NET API と同じように、Revit API でもトランザクションを指定して要素を操作することが出来ます。AutoCAD のように、明示的にオープンモードを指定するのではなく、アンドゥ時に表示されるアンドゥの単位に名前を付けることが出来ます。

1 つの外部コマンド内の処理に、複数のトランザクションを設けてることも可能です。この処理は、AutoCAD の UNDO コマンドでグループ化を指定するような処理と同じです。AutoCAD では、ObjectARX でも、.NET API でもアンドゥの細かい制御機能が API で公開されていませんが、Revit API では可能という訳です。

さて、Revit API では、外部コマンドの定義の際にコマンド属性としてトランザクションモードを指定する、という説明をしました。細かいアンドゥ処理を可能にするには、トランザクションモードを TransactionMode.Manual に指定する必要があります。

トランザクションモード（TransactionMode）には、Manual の他に Automaric と ReadOnly がありますが、アンドゥなどの利便性から Manual の利用が推奨されています。詳細は後日、別のブログ記事でご紹介する予定です。

アドインの開発

Revit 2014 アドインの開発には、前述のとおり Visual Studio 2010 を利用します。Revit API は .NET Framework をベースにしているため、Visual Studio がサポートする .NET 言語であれば、どの言語を選択していただいけも結構です。ただ、Revit SDK に用意されているのは、C# と VB.NET に限定されていますので、この2つの言語のいずれかの利用をお勧めしています。他の言語を使った事例は、ほとんどありません。

Visual Studio を利用する開発では、最初にプロジェクトを作成する必要があります。これは、AutoCAD .NET API とも同じですが、Revit API にもスケルトンプロジェクトを作成する Wizard が用意されています。ただし、Revit 2014 用の Wizard は、Revit SDK にではなく、次のブログ記事上に C# 用と VB.NET 用が記載されています。

http://thebuildingcoder.typepad.com/blog/2013/05/add-in-wizards-for-revit-2014-1.html

ここに記載された Wizard には、残念ながらインストーラは含まれていませんが、セットアップは簡単です。ダウンロードした ZIP ファイルを、言語別のフォルダにコピーするだけでセットアップが完了します。Visual Studio 2010 を再起動すると、言語カテゴリ毎にテンプレートアイコンが表示されるはずです。

いろいろな Revit API の機能を試してみたい場合など、この Wizard を使うと便利です。本格的なプロジェクトを作成する場合には、Revit API Developers Guide にある手順に沿って、手動でプロジェクトを作成していくのもいいかも知れません。そのほうが、ファイル名などの命名規則に沿ったプロジェクトを作成することが出来るはずです。

アドインのロード処理

作成したアドインアセンブリを Revit にロードさせるには、アドインマニフェストと呼ばれる XML 形式の定義ファイルを、Revit がインストールされたコンピュータの指定されたフォルダに配置する必要があります。アドインマニフェストは、外部コマンドと外部アプリケーション毎に登録する必要があります。1 つのファイルにまとめて記述することも出来ます。

アドインマニフェストには、ロードすべきアセンブリファイルのパスなどのほか、外部コマンドのコマンド名、会社情報などを指定することが出来ます。外部コマンドを登録した場合には、<Text> タグの値で指定された文字列が、コマンド名として [外部ツール] ボタン下に表示されることになります。

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
<AddIn Type="Command">
    <Text>HelloWorld</Text>
    <Description>Some description for HelloWorld</Description>
    <Assembly>HelloWorld.dll</Assembly>
    <FullClassName>HelloWorld.Command</FullClassName>
    <ClientId>d7da1e85-ebae-4f91-bd41-5fc50512dc16</ClientId>
    <VendorId>Autodesk</VendorId>
    <VendorDescription>Autodesk, http://www.autodesk.co.jp</VendorDescription>
</AddIn>
<AddIn Type="Application">
    <Name>Application HelloWorld</Name>
    <Assembly>HelloWorld.dll</Assembly>
    <FullClassName>HelloWorld.App</FullClassName>
    <ClientId>426c9e14-49a7-4245-8e41-288336d18177</ClientId>
    <VendorId>Autodesk</VendorId>
    <VendorDescription>Autodesk, http://www.autodesk.co.jp</VendorDescription>
</AddIn>
</RevitAddIns>

アドインマニフェストに登録する外部コマンドや外部アプリケーションは、GUID によって一意に識別されて Revit にロードされます。このため、<ClientId> タグ（または <AddInId> タグ）の値が他の外部コマンドや外部アプリケーションと重複してはいけません。

アドインマニフェストで利用するタグのリファレンスとマニフェストファイルの配置場所については、Revit API Developers Guide の こちら に記載されています。

アドインファイルのロードは、Revit SDK に用意された Addin-Manager を利用する場合を除き、ここで紹介したアドインマニフェストを使う以外、他にはありません。AutoCAD のような多彩なロード手法が用意されていないので、逆に迷ってしまうことはなくていいのかも知れません。

アドインのバージョン互換性

AutoCAD API と違って、Revit API はバージョンアップ毎に互換性が崩れます。このため、アドインを新バージョンに対応させるためには、基本的に毎回、移植作業が必要になってります。諸説ありますが、互換性を維持しない理由には、次のような理由が挙げられています。

Revit がデータファイルや API の後方互換性（古いバージョンとの互換性）を注力せずに、新バージョンへ向けた開発リソースを集中しているため。
Revit API の書式の整合性や一貫性の保持、クリーンナップを毎バージョン実施して、分かり易い API を目指しているため。

実際、新バージョンの Revit がリリースされる度に、新バージョン用の Revit SDK が用意されます。この時、旧バージョンで利用できた一部のクラス、メソッドやプロパティなどが、Obsolete（旧式）にマークされて、ビルド時に新しいクラス、メソッドやプロパティを利用するよう、警告メッセージが表示されることがあります。

Obsolete（旧式）に指定された Revit バージョンでは、警告メッセージがビルド時に出るものの、コードそのものは問題なく実行できます。ただ、更に次のバージョンがリリースされた時点で、Obsolete（旧式）だったクラス、メソッドやプロパティが完全に削除されていますので、なるばく早めに移植作業（コードの書き直し）を完了しておくことが推奨されています。

同様に、Revit のプロジェクトファイル（.rvt）などのデータファイルは、一度、最新バージョンにマイグレートしてしまうと、旧バージョン用に保存し直すことが出来ません。

DWG 図面ファイル形式やアドオンアプリケーションの互換性を、3 バージョン間維持するようにバージョンアップを繰り返す AutoCAD は、CAD 製品としては特殊なのかも知れません。

By Toshiaki Isezaki