The Merge Automation API enables you to control it 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.
If you are using a .NET-capable language and you do not need to present the Merge user interface to the user, you may wish to use the Merge .NET assembly rather than the Automation API.
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
Automation API example scripts and programs
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 Virtual File System (VFS) 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.
If you require assistance with using the Automation API or developing a plugin file system, please feel free to contact Araxis.
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
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.
||Imports type definitions into the namespace
||Imports type definitions into the global namespace. Use
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
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.
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
Busy property at regular intervals until it returns
The second approach is to register an interest in the
ComparisonComplete event that is fired by Merge when the folder comparison is completed.
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.