Getting Started with the Automation API

The Merge Automation API provides a simple way to communicate with Araxis Merge. The API supports both early-binding and late-binding (via IDispatch), and can therefore be used by a majority of automation clients. The API’s event model supports both connection point, native interface, and Windows Scripting Host’s ConnectObject models.

Referencing the Automation API

For client languages that use early-binding (or stongly-typed) access to the API’s COM objects, you will need to add a reference to the Automation API to your project. Scripting languages (VBScript and JScript for example) typically use late-binding, so this step is not required.

Visual Basic v6.0

To use the Merge Automation API in Visual Basic v6.0, you must add a reference to the Merge Type Library:

Once the reference has been added, the Merge automation objects and types are found in the Merge70 namespace.

Visual Studio .NET 2005 (managed projects)

To use the Merge Automation API in Visual Studio.NET 2005 managed projects, you can either Add a reference to the pre-built COM interop assemblies (Interop.Merge70.dll and Interop.Merge70.dll) included in the Merge installation folder, or you can add a reference to the Merge Type Library as follows:

Once the reference has been added, the Merge automation objects and types are found in the Merge70 namespace.

Visual C++ (unmanaged projects)

You can reference either the pre-compiled type library (Merge.tlb) file or IDL-generated header file (Merge.h) that ships with Merge. Both files can be found in in the Merge installation folder, typically C:\Program Files\Araxis\Araxis Merge.

Using the Automation API

The root object of the Merge automation library is the Application object. This object provides access to objects that can be used to set options, and to perform file and folder comparisons.

Creating an instance of the Application object

All of the examples below create an instance of an Application object and place a reference to it into the variable 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();

Performing a text file comparison

To perform a text file comparison, you need to obtain a TextComparison object from the Application object. The Application object exposes a property called TextComparison. This property returns a new instance of a TextComparison object each time it is accessed, so you will typically want to store the property’s value in a variable. Once you have an instance of a TextComparison object, you call call the Compare method to compare two files and generate an HTML report of the comparison results.

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.IFileComparison 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.IFileComparison
tc = app.TextComparison
tc.Report("html", Merge70.LineEndingStyle.lesCRLF,
  "c:\temp\report.htm")

Merge70::IFileComparisonPtr 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<IFileComparison> tc;
hr = app->get_FileComparison(&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 */

Once the file comparison has been performed, you can use the methods and properties provided by the TextComparison object to examine the results, or to perform further processing of the results – report generation, printing, or file saving, for example.

Performing a folder comparison

The file and folder comparison automation objects have a very similar interface. However, the Compare method behaves differently for folder comparisons. For file comparisons, the Compare method is synchronous, which means that comparison results are available from the point when the method completes. For folder comparisons, the Compare method is asynchronous. This means that there will almost always be a delay between the method completing and the results becoming available. There are two approaches that can be used to wait for the results to become available. The first approach is to test the value of the FolderComparison object’s Busy property at regular intervals until it returns 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");

The second approach is to register an interest in the ComparisonComplete event that is fired by Merge when the folder comparison is completed.

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;
}

This latter approach can be used to perform tasks in response to other events fired by the file or folder comparison object, for example, in response to the user closing a comparison window.

Controlling the user interface

By default, the Merge user interface does not appear when you access the Automation API. To make the main Merge window appear on screen, you should set the Application object’s Visible property to True. To make the window active, set the Active property to True. Merge will normally shut down when the last reference to an automation object is released. If you want the user interface for an object to remain longer so that the user can interact with it, call the GiveUserControl method on an Application, TextComparison, BinaryComparison, ImageComparison, or FolderComparison object.

Complete Automation API examples

Source code for examples in a variety of languages is available.