Introduction to the Automation API

The Automation API enables you to control Merge from JScript, Visual Basic (including VBScript), C#, C++, and many other programming languages and environments. Using Automation, you can tightly integrate Merge with other applications, or make it part of your workflow.

The API supports both early-binding and late-binding (via IDispatch), and can therefore be used by a majority of Windows Automation clients. The API’s event model supports the connection point, native interface, and Windows Scripting Host ConnectObject models.

Automation API example scripts and programs

The AutomationSamples directory within the Merge installation directory contains a wealth of complete Automation API programming examples. Many of these perform valuable tasks; others will give you ideas for how you could use Merge to provide solutions for your own environment.

The examples are in a variety of languages – mostly JScript and CSharp, but also VBScript and Visual Basic. The C++ source code to a number of the command-line utilities (such as compare.exe) included with Merge is also provided.

Remember that Merge offers direct access to various SCM repositories via its File-System Plugins. Thus, for example, you can use Automation to create a report of the changes in your SCM system between two dates, branches or revisions. The FolderComparisonPerforceChangeListReport.js example shows how this may be done for Perforce.

Support

If you require assistance with using the Automation API or developing a plugin file system, please feel free to contact Araxis.

Licensing

The End-User Licence Agreement for Araxis Merge Software has specific provision for both desktop use and for Merge to be deployed as a component of a server application that provides services to multiple users. In summary, deployment as a server component requires the purchase of two Merge licences rather than the one required for normal desktop use, though you are referred to the full EULA for the definitive terms.

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 Studio .NET 2005 and later (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) 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");

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();

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");

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 */

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.