オートメーション API 入門

Merge オートメーション API は、さまざまなプログラミング言語および環境から Araxis Merge と通信する簡単な方法を提供します。

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

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

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

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

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

プラグインを開発したい場合は、仮想ファイル システム プラグイン自体のソース コードも利用できます。これを取得する場合は、Araxis のお問い合わせ先までご連絡ください。

サポート

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

Automation API の参照

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

Visual Basic v6.0

Visual Basic v6.0 で Merge オートメーション API を使用するには、Merge タイプ ライブラリへの参照を追加する必要があります。

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

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

Merge のオートメーション API を Visual Studio.NET 2005 マネージ オブジェクトで使用するには、Merge インストール フォルダーに含まれるプレビルト COM 相互接続アセンブリ（Interop.Merge70.dll および 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");

Dim app As New 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<IApplication> app;
  HRESULT hr = app.CoCreateInstance(__uuidof(Application));
  if (FAILED(hr))
    /* ... handle error */
  // ...
}
CoUninitialize();

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

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

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

Dim tc As Merge70.TextComparison
Set tc = app.TextComparison
tc.Compare "c:¥temp¥test1.txt", "c:¥temp¥test2.txt"
tc.Report "html", Merge70.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<ITextComparison> 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 つの方法があります。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 ウィンドウをスクリーンに表示させるには、Application オブジェクトの Visible プロパティを True に設定します。ウィンドウをアクティブにするには Active プロパティを True に設定します。通常 Merge はオートメーション オブジェクトに対する最後の参照がリリースされたときにシャットダウンします。オブジェクトのユーザー インターフェイスをユーザーが操作できるように残しておきたい場合は、GiveUserControl メソッドを Application、TextComparison、BinaryComparison、ImageComparison および FolderComparison オブジェクトから呼び出してください。