オートメーション API 入門

オートメーション API は、JScript、Visual Basic（VBScript を含む）、Visual C#、Visual C++、その他多くのプログラミング言語および環境から Merge を制御することができます。オートメーションを使って、Merge を他のアプリケーションと統合したり、ワークフローに組み込むことができます。

API は（IDispatch によって）事前バインディングと遅延バインディングの両方をサポートしているため、多くの Windows オートメーション クライアントから使用できます。API イベント モデルは、ネイティブ インターフェイスおよび Windows Scripting Host ConnectObject モデルの接続ポイントをサポートします。

オートメーション API スクリプトおよびプログラムの例

Merge インストール ディレクトリ内の AutomationSamples ディレクトリには、オートメーション API の完全なサンプル プログラムが豊富に収められています。これらの多くは役に立つ仕事をするほか、どのように Merge を使ったら、あなたの環境のソリューションを提供できるかについて、アイディアを提供してくれます。

サンプルはさまざまな言語にわたっています。主に JScript と CSharp ですが、VBScript および Visual Basic もあります。また、Merge に付属する多くのコマンドライン ユーティリティ（compare.exe など）の C++ ソース コードも提供されています。

Merge では、ファイルシステム プラグインを介して SCM リポジトリに直接アクセスできることを思い出してください。そのため、たとえばオートメーションを使用して、SCM システムの 2 つの日付、分岐、またはリビジョン間の変更のレポートを作成することができます。FolderComparisonPerforceChangeListReport.js サンプルは、これを Perforce で実現する方法を示しています。

サポート

オートメーション API を使用したり、プラグイン ファイル システムを開発したりすることで支援が必要な場合は、Araxis までお問い合わせください。

ライセンス

Araxis Merge ソフトウェア エンドユーザー ライセンス契約書には、デスクトップで使用する場合と、複数のユーザーにサービスを提供するサーバー アプリケーションのコンポーネントとして Merge を展開する場合のための、特定の条項があります。最終的な条件については完全な EULA を参照されるでしょうが、要約すると、サーバーコンポーネントとして展開するには、通常のデスクトップ使用に必要な 1 つのライセンスではなく、2 つの Merge ライセンスの購入が必要となります。

オートメーション API の参照

事前バインディング（または厳密な型指定）を使用して API COM オブジェクトにアクセスするクライアント言語の場合は、プロジェクトにオートメーション API への参照を追加する必要があります。スクリプト言語（たとえば VBScript と JScript）は一般に遅延バインディングを使用しますから、この手順は必要ではありません。

Visual Studio .NET 2005 以降では（マネージ プロジェクト）

Merge のオートメーション API を Visual Studio.NET 2005 マネージ オブジェクトで使用するには、Merge インストール フォルダーに含まれるプレビルト COM 相互接続アセンブリ（interop.Merge70.dll）への参照を追加するか、以下のように Merge タイプ ライブラリへの参照を追加することができます。

参照を追加すると、Merge オートメーション オブジェクトとタイプが Merge70 ネームスペースに現れます。

Visual C++ （アンマネージ プロジェクト）

プリコンパイルされたタイプ ライブラリ ファイル（Merge.tlb）または Merge に含まれる IDL によって生成されたヘッダ ファイル（Merge.h）を参照することができます。両ファイルは Merge のインストール フォルダーにあります。通常は C:\Program Files\Araxis\Araxis Merge です。

オートメーション API の使用

Merge オートメーション ライブラリのルート オブジェクトは Application オブジェクトです。このオブジェクトはオプションをセットして、ファイルとフォルダーの比較を行うために使用するオブジェクトへのアクセスを提供します。

Application オブジェクトのインスタンスの作成

下記のすべての例では、Application オブジェクトのインスタンスを作成して、その参照を変数 app に置きます。

var app = WScript.CreateObject("Merge70.Application");

Merge70.Application app = new Merge70.ApplicationClass();

Dim app As New Merge70.ApplicationClass

CoInitialize(0);
{
  Merge70::IApplicationPtr app;
  HRESULT hr = 
    app.CreateInstance(__uuidof(Merge70::Application));
  if (FAILED(hr))
    _com_raise_error(hr);
  // …
}
CoUninitialize();

CoInitialize(0);
{
  CComPtr app;
  HRESULT hr = app.CoCreateInstance(__uuidof(Application));
  if (FAILED(hr))
    /* … handle error */
  // …
}
CoUninitialize();

テキスト ファイル比較の実行

テキスト ファイルの比較を行うために、TextComparison オブジェクトを Application オブジェクトから得る必要があります。Application オブジェクトは TextComparison と呼ばれるプロパティを公開します。このプロパティは、アクセスされるたびに TextComparison オブジェクトの新しいインスタンスを返すため、概して、プロパティの値を変数に格納したくなります。TextComparison オブジェクトのインスタンスがあれば、Compare メソッドを呼び出して 2 つのファイルを比較し、その比較結果の HTML レポートを生成することができます。

var tc = app.TextComparison;
tc.Compare("c:\\temp\\test1.txt", "c:\\temp\\test2.txt");
tc.Report("html", 0/*lesCRLF*/, "c:\\temp\\report.htm");

Merge70.ITextComparison tc = app.TextComparison;
tc.Compare("c:\\temp\\test1.txt", "c:\\temp\\test2.txt", 0);
tc.Report("html", Merge70.LineEndingStyle.lesCRLF,
  "c:\\temp\\report.htm");

Dim tc As Merge70.ITextComparison
tc = app.TextComparison
tc.Compare("c:\temp\test1.txt", "c:\temp\test2.txt")
tc.Report("html", Merge70.LineEndingStyle.lesCRLF,
  "c:\temp\report.htm")

Merge70::ITextComparisonPtr tc = app->TextComparison;
tc->Compare(
  _variant_t("c:\\temp\\test1.txt"),
  _variant_t("c:\\temp\\test2.txt"),
  _variant_t());
tc->Report(
  _bstr_t("html"),
  Merge70::lesCRLF,
  _bstr_t("c:\\temp\\report.htm"));

CComPtr tc;
hr = app->get_TextComparison(&tc);
if (FAILED(hr))
  ;/* … handle error */
hr = tc->Compare(
  CComVariant("C:\\temp\\test1.txt"),
  CComVariant("C:\\temp\\test2.txt"),
  CComVariant());
if (FAILED(hr))
  ;/* … handle error */
hr = tc->Report(
  CComBSTR("html"),
  lesCRLF,
  CComBSTR("c:\\temp\\report.htm"));
if (FAILED(hr))
  ;/* … handle error */

ファイル比較を実行したら、TextComparison オブジェクトによって提供されるメソッドとプロパティを使用して、結果の調査や、結果のさらなる処理、たとえばレポートの作成、印刷、ファイル保存などが行えます。

フォルダー比較の実行

ファイル比較とフォルダー比較のオートメーション オブジェクトは非常に似たインターフェイスを持っています。しかし Compare メソッドはフォルダー比較では異なる動作をします。ファイル比較では Compare メソッドは同期です。メソッドが完了した時点から比較結果を利用できます。フォルダー比較では Compare メソッドは非同期です。ほとんどの場合、メソッドが完了してから結果が利用可能になるまでの間に遅れがあります。結果が利用可能になるのを待つために使用できる 2 つの方法があります。1 番目の方法は、FolderComparison オブジェクトの Busy プロパティが False を返すまで、一定の時間をおいてプロパティの値をテストすることです。

var app = WScript.CreateObject("Merge70.Application");
var fc = app.FolderComparison;

fc.Compare("c:\\temp\\FolderA", "c:\\temp\\FolderB");
while (fc.Busy)
  {
    WScript.Sleep(1000);
  }
fc.Report("html", 0, "c:\\temp\\folderreport.htm");

2 番目の方法は、フォルダー比較が完了したときに Merge が発生させる ComparisonComplete イベントの中で関心事を記録することです。

var app = WScript.CreateObject("Merge70.Application");
var fc = app.FolderComparison;
var completed = false;

WScript.ConnectObject(fc, "fc_");
fc.Compare("c:\\temp\\FolderA", "c:\\temp\\FolderB");

WScript.echo("waiting for completion");
while (!completed)
  {
    /* do other work */
    WScript.Sleep(1000);
  }
WScript.echo("completed…");
WScript.DisconnectObject(fc);

function fc_ComparisonComplete(resultCode)
{
  fc.Report("html", 0, "c:\\temp\\folderreport.htm");
  completed = true;
}

この 2 番目の方法は、ファイルやフォルダーの比較オブジェクトによって発生した他のイベントに応答してタスクを実行する場合に使用できます。たとえば、ユーザーが比較ウィンドウを閉じるのに応答する場合などです。

ユーザー インターフェイスの制御

オートメーション API にアクセスした場合、デフォルトでは、Merge ユーザー インターフェイスは現れません。メイン Merge ウィンドウを画面に表示させるには、Application オブジェクトの Visible プロパティを True に設定する必要があります。ウィンドウをアクティブにするには、Active プロパティを True に設定します。通常、Merge は、オートメーション オブジェクトへの最後の参照が解放されたときにシャットダウンします。オブジェクトのユーザー インターフェイスをユーザーが操作できるように残しておきたい場合は、Application、TextComparison、BinaryComparison、ImageComparison、または FolderComparison オブジェクトの GiveUserControl メソッドを呼び出してください。