Therefore Programming Interface 3.0

1

Start Microsoft Visual Studio and create a new class library project

2

Add a Reference to the Thereforeâ„¢ API

In the Solution Explorer right-click Reference and click on Add Reference.

In the .NET tab choose "The.API.Interop" and click OK.

If you cannot find "The.API.Interop" in your .NET you can also use "Therefore API 3.0 Type Library" in the COM tab, or open the Browse tab and select "The.API.Interop.dll" or "TheAPI.dll" in your Thereforeâ„¢ directory. Please see "Add Reference in Visual Studio" for details.

3

Add using/Imports statements for Therefore.API and System.Runtime.InteropServices

Open your AddIn class implementation file. In the beginning of the file add the following lines after other using or Imports statements.

C#

using System.Runtime.InteropServices;

using Therefore.API;

4

Create and Insert a GUID

Open the GUID creation tool (Tools / Create GUID).

Select "4. Registry Format" and click the Copy button.

Paste the created GUID above the AddIn class declaration. Now your class looks like this:

C#

[Guid("819D4F41-8AAE-43BF-BFA4-2EB848FDF703"), ComVisible(true)]

public class MyAddInClass : ITheAddIn

{

}

5

Implement ITheAddIn

In the implementation file right-click ITheAddIn and click on Implement Interface / Implement Interface.

Your implementation file should now look like this:

C#

using System;

using System.Collections.Generic;

using System.Text;

using System.Runtime.InteropServices;

using Therefore.API;

namespace MyAddInLibrary

{

    [Guid("819D4F41-8AAE-43BF-BFA4-2EB848FDF703"), ComVisible(true), ClassInterface(ClassInterfaceType.None)]

    public class MyAddInClass : ITheAddIn

    {

        #region ITheAddIn Members

        public void GetHandledEvents(TheClientType nClient, TheEventSet pEventSet)

        {

            throw new NotImplementedException();

        }

        public int HandleEvent(TheEvent pEvent)

        {

            throw new NotImplementedException();

        }

        #endregion

    }

}

6

Implement a Simple Test AddIn

Add a reference to System.Windows.Forms (in the Solution Explorer right-click References / Add Reference; in the .NET tab choose System.Windows.Forms and click OK) and make the following changes to your code:

C#

using System;

using System.Collections.Generic;

using System.Text;

using System.Runtime.InteropServices;

using System.Windows.Forms;

using Therefore.API;

namespace MyAddInLibrary

{

    [Guid("819D4F41-8AAE-43BF-BFA4-2EB848FDF703"), ComVisible(true), ClassInterface(ClassInterfaceType.None)]

    public class MyAddInClass : ITheAddIn

    {

        #region ITheAddIn Members

        public void GetHandledEvents(TheClientType nClient, TheEventSet pEventSet)

        {

            MessageBox.Show("MyAddInClass successfully registered.");

        }

        public int HandleEvent(TheEvent pEvent)

        {

            throw new NotImplementedException();

        }

        #endregion

    }

}

pEventSet.AddAll() will tell the Thereforeâ„¢ AddIn system that we want to receive all occurring events.

In HandleEvent we display a message box with a string representation of the incoming event. We return the default return code (0), thereby telling the AddIn system to continue as usual. Please check the various events for the event-specific meaning of different return codes.

7

Build your AddIn DLL

In Visual Studio click on the menu Build / Build Solution or Build / Rebuild Solution. Check the output window to make sure your DLL compiled successfully, if not debug your code and repeat this step.

8

Register the Assembly (RegAsm)

Open a Windows command prompt (click Start / Run - type "cmd" - click OK). Navigate to the directory containing your AddIn DLL. Type regasm <YourDLL>

(e.g. regasm myaddinlibrary.dll) The command prompt should say Types registered successfully.

   D:\TestProjects\MyAddInLibrary\MyAddInLibrary\bin\Debug>regasm myaddinlibrary.dll

   Microsoft (R) .NET Framework Assembly Registration Utility 2.0.50727.1433

   Copyright (C) Microsoft Corporation 1998-2004.  All rights reserved.

   Types registered successfully

9

Configure the AddIn in the Windows Registry

Open the Windows Registry Editor (Start / Run / regedit). Find or create the key HKEY_LOCAL_MACHINE/Software/Wow6432Node/Therefore/AddIns and/or HKEY_CURRENT_USER/Software/Therefore/AddIns and create the following subkeys: All, Capture, CategoryDialog, Navigator and Viewer.

10

Test your AddIn

Start Thereforeâ„¢ Navigator or Capture or Viewer and you should see a message box "MyAddInClass successfully registered.". Afterwards your application should run as usual.

This concludes your first test of the Thereforeâ„¢ AddIn system. Please read the remaining sections of this guide for more useful applications of the Thereforeâ„¢ AddIn system.