Andrew Whitechapel : Automation add-ins

Managed Automation Add-ins

andreww — Thu, 24 Jan 2008 05:11:00 GMT

I've been thinking more about calling unmanaged XLL UDFs from managed code than about managed automation add-ins lately, but an automation add-in issue came up the other day, and I thought I'd throw it out there. If you want to build managed UDFs without going to the extreme of managed XLLs, you have a couple of simple choices:

· You can use a VBA wrapper approach as described in Paul Stubbs' post here:

· Or build an automation add-in instead, as described by Eric Carter here:

… and if you’re going to build a managed automation add-in, you’ll want to shim it, which you can do with the COM Shim Wizard v2.3, described here:

I've blogged about managed UDFs via automation add-ins many times in the past, including the following:

· Implementing IDTExtensibility2 in an Automation Add-in

· Example Shimmed Automation Add-in

· Volatile Managed UDFs

· Optional Volatile UDFs

· Excel Interop Types in Shimmed Automation Add-ins

If you want to build a simple managed automation add-in that does not implement IDTExtensibility2, Eric's excellent post covers the basic procedure. If you do choose this approach, there are a few additional issues you should bear in mind:

· ProgId limitations

· Add-in Manager limitations

· Function Wizard limitations

· Default interface limitations.

Let's take each of these in turn. First, ProgIds. It is common practice in managed code to specify namespaces and typenames that are verbose, but this can easily exceed the maximum allowed length of a ProgId (39 characters). If you do this, there's no indication of the problem until you try to register the add-in with Excel – and even then, Excel simply tells you that the add-in is invalid, without providing any more detail. To avoid this problem, you should always specify a ProgId explicitly, using the ProgId attribute. Also remember that underscores are legal in managed code, but illegal in ProgIds.

Second, Excel's Add-in Manager lists automation add-ins by their registered ProgId, and there is no way to change this behavior. This is an Excel limitation on automation add-ins.

Third, Excel's Function Wizard lists each automation add-in as its own separate function category. The category name is the add-in's ProgId, and you cannot specify a different category name for UDFs in automation add-ins. You also cannot specify function descriptions, argument descriptions, or help for automation add-in UDFs. These are limitations imposed by Excel on automation add-ins, and are described here.

Lastly (as in Eric's post), you can simply attribute the UDF class with ClassInterfaceType.AutoDual. This generates a class interface, which in other contexts is usually frowned upon. A class interface is a generated interface that exposes all public methods, properties, fields and events of the managed type. The basic problem with this is that any changes in a future version to the layout of the type or any base types will break (early-bound) COM clients that bind to the interface. For details see here and here. I discussed the use of class interfaces in automation add-ins in an earlier post. In the specific case of automation add-ins, where the early-bound vtbl interface is not used, the inherent fragility of class interfaces is not in practice a problem. However, there is another problem: display of unwanted methods in the Function Wizard.

Your automation add-in class will implicitly derive from System.Object (all managed classes do). Making the class ComVisible and attributing it with ClassInterfaceType.AutoDual will expose the underlying System.Object methods, Equals, GetHashCode, ToString and GetType. These will be in the typeinfo for the add-in, and will therefore show up in Excel's Insert Function dialog. One approach to prevent these members from showing up is to override them and make them ComVisible(false), as shown below:

[ComVisible(false)]

public override bool Equals(object obj)

{

return base.Equals(obj);

}

[ComVisible(false)]

public override int GetHashCode()

{

return base.GetHashCode();

}

[ComVisible(false)]

public override string ToString()

{

return base.ToString();

}

The problem with this approach is that System.Object.GetType is non-virtual so we cannot override it. So, even if we hide the other 3 methods this way, we'll still be left with GetType.

A second approach is to avoid using a class interface. Instead, specify the UDF interface explicitly, and make it ComVisible(true). Also, attribute your add-in class with ClassInterfaceType.None. A sample class that uses this approach (and suitable explicit ProgId and GUID) is shown below:

[ComVisible(true)]

public interface ISimpleUDFs

{

double MultiplyTwo(double x, double y);

}

[ClassInterface(ClassInterfaceType.None)]

[ComVisible(true)]

[Guid(SimpleUDFs.Guid)]

[ProgId("SimpleAutomationAddIn.SimpleUDFs")]

public class SimpleUDFs : ISimpleUDFs

{

public SimpleUDFs()

{

}

#region Automation Add-in Registration

internal const string Guid = "C426EC79-2F31-44bf-BB0A-BE9A357FA5B3";

const string SubKeyName = @"CLSID\{" + Guid + @"}\Programmable";

[ComRegisterFunction]

public static void RegisterFunction(Type type)

{

Registry.ClassesRoot.CreateSubKey(SimpleUDFs.SubKeyName);

}

[ComUnregisterFunction]

public static void UnRegisterFunction(Type type)

{

Registry.ClassesRoot.DeleteSubKey(SimpleUDFs.SubKeyName);

}

#endregion

public double MultiplyTwo(double x, double y)

{

return x * y;

}

Bear in mind, however, that without a class interface, the default interface on the add-in class will be the first one implemented (that is, ISimpleUDFs in the example above). That means that if your add-in class implements additional interfaces, they will not be visible to automation clients, and any methods defined in such interfaces will not be available as UDFs. That may be a limitation you can live with – after all, you could work around this by simply implementing one interface per class, and exposing multiple classes from your add-in. It may also, of course, be a deliberate part of your design.

If you want to shim your automation add-in (which you should do), you can either write your own shim, or use the COM Shim Wizard. If you want to use the COM Shim Wizard, you need to implement IDTExtensibility2 in your add-in class – this is because the Wizard searches explicitly for this interface when generating a shim for any add-in (both regular COM add-ins and automation add-ins). If you don't need IDTExtensibility2 in your add-in for anything else, then you can simply implement each of its methods in the default manner generated by Visual Studio, for example:

public void OnConnection(

object Application, ext_ConnectMode ConnectMode,

object AddInInst, ref Array custom)

{

throw new Exception("The method or operation is not implemented.");

}

On the other hand, if you do need IDTExtensibility2 (perhaps because you want to get access to Excel's exposed COM OM from your automation add-in), then you're back to generating a class interface for your add-in class (so that you can expose more than one real interface via the combined class interface).

Excel Interop Types in Shimmed Automation Add-ins

andreww — Sun, 23 Jul 2006 22:00:00 GMT

In my previous posts on shimming Excel automation add-in UDFs, I've used simple examples where the methods tended to take and return standard types such as doubles and ints. Someone asked a question recently - what about Excel types as parameters? In other words, how do you write the shim for a method that takes say an Excel Range object as a parameter?

So, here's an example.

The simplest process to adopt is to build a regular COM add-in (that implements IDTExtensibility2), and then shim it. This way, you can use the COM Shim Wizards to generate the shim code. You can always remove the IDTExtensibility2 implementation from the add-in and shim later, if you don’t want them. That said, it is generally useful to implement IDTExtensibility2 in your automation add-in, if only because Excel then gives you an Excel.Application object up front – which is otherwise somewhat difficult to get.

In my managed automation add-in assembly, I declare my UDF in a custom interface. Note that I’m using standard Excel interop types, such as Excel.Range:

namespace RangeUDF

{

[GuidAttribute("73570AB7-89E3-45e4-B605-B6DDFFE7C437")]

public interface IRangeCalc

{

double SumValues(Excel.Range r);

}

…and implement it in a class like this:

[GuidAttribute("3C8ED961-B58B-4580-AB67-A45648E2A7B7"),

ProgId("RangeUDF.Connect"),

ClassInterface(ClassInterfaceType.AutoDual)]

public class Connect :

Object, Extensibility.IDTExtensibility2, IRangeCalc

{

#region Standard IDTExtensibility2 stuff

public Connect(){}

public void OnConnection(object application,

Extensibility.ext_ConnectMode connectMode,

object addInInst, ref System.Array custom)

{

xl = (Excel.Application)application;

addInInstance = addInInst;

}

public void OnDisconnection(

Extensibility.ext_DisconnectMode disconnectMode,

ref System.Array custom) { }

public void OnAddInsUpdate(ref System.Array custom){}

public void OnStartupComplete(ref System.Array custom){}

public void OnBeginShutdown(ref System.Array custom){}

private Excel.Application xl;

private object addInInstance;

#endregion

#region IRangeCalc Members

public double SumValues(Excel.Range r)

{

double sum = 0;

for (int row = 1; row <= r.Rows.Count; row++)

{

for (int col = 1; col <= r.Columns.Count; col++)

{

sum += Convert.ToDouble(

((Excel.Range)r.Cells[row, col]).Value2);

}

return sum;

}

#endregion

}

Note: make sure you know what the GUID is for your assembly. The simplest way to do this is to go to the properties for the project, then the Application tab, and click on Assembly Information. Specify a new GUID in the GUID field. This ends up in the assemblyinfo.cs. At the same time, check the box to make the assembly COM-visible, and on the build tab, check the box to register it for COM interop. For example, in my assemblyinfo.cs, I end up with this declaration:

[assembly: GuidAttribute("917E2CFA-D16C-41b4-BD33-6EE0254C98FD")]

...this is the GUID for the assembly (and therefore, eventually, the COM typelib).

So far, nothing unusual.

Now for the shim. You can use the COM Shim Wizards to generate the basic COM add-in shim code as usual. Then, you need to modify the code to turn it into an automation add-in shim.

The first critical change is to import the typelib for the managed assembly into the shim project. If you look at the stdafx.h, you’ll see #imports for the mscorlib an msaddndr typelibs, which give you the declarations of _AppDomain and IDTExtensibility2, respectively. For your shim, add another #import for the typelib of your managed assembly, eg:

// Imports the typelib for the RangeUDF add-in assembly.

#import "libid:917E2CFA-D16C-41b4-BD33-6EE0254C98FD" raw_interfaces_only named_guids

Recall that the stdafx.h is used for the precompiled headers. This #import will import the typelib and therefore generate a .TLH. You should get intellisense for this typelib in your project straight away. If you want to see a persisted copy of the .TLH, you can build your project at this point.

In the ConnectProxy.h, update the proxy class so that it implements your custom interface in addition to (or instead of) IDTExtensibility2. As soon as you type the namespace for the custom interface (and the double colon), intellisense/autocomplete should give you a dropdown list of members from the typelib:

class ATL_NO_VTABLE CConnectProxy :

public CComObjectRootEx<CComSingleThreadModel>,

public CComCoClass<CConnectProxy, &CLSID_ConnectProxy>,

public IDispatchImpl<AddInDesignerObjects::_IDTExtensibility2,

&AddInDesignerObjects::IID__IDTExtensibility2,

&AddInDesignerObjects::LIBID_AddInDesignerObjects, 1, 0>,

public IDispatchImpl<RangeUDF::IRangeCalc,

&RangeUDF::IID_IRangeCalc,

&RangeUDF::LIBID_RangeUDF, 1, 0>

{

As well as (or instead of) the IDTExtensibility2 pointer that the wizard gives you, add a declaration for your custom interface pointer:

protected:

RangeUDF::IRangeCalc *m_pRangeCalc;

Initialize your custom interface pointer in the constructor:

CConnectProxy() : m_pConnect(NULL), m_pCLRLoader(NULL), isShutdownInProgress(false), m_pRangeCalc(NULL)

{

}

Note that the isShutdownInProgress field is specific to the VS 2005 version of the COM Shim Wizards.

Update the COM map to (a) include your custom interface, and (b) route queries for IDispatch through your custom interface:

BEGIN_COM_MAP(CConnectProxy)

//COM_INTERFACE_ENTRY2(IDispatch, AddInDesignerObjects::IDTExtensibility2)

COM_INTERFACE_ENTRY(RangeUDF::IRangeCalc)

COM_INTERFACE_ENTRY2(IDispatch, RangeUDF::IRangeCalc)

COM_INTERFACE_ENTRY(AddInDesignerObjects::IDTExtensibility2)

END_COM_MAP()

If you’re using the VS 2005 version of the COM Shim Wizards, update the OnDisconnection proxy to clean up your custom interface pointer:

STDMETHOD(OnDisconnection)(

AddInDesignerObjects::ext_DisconnectMode RemoveMode, SAFEARRAY **custom )

{

HRESULT hr = S_OK;

if (m_pConnect)

{

hr = m_pConnect->OnDisconnection(RemoveMode, custom);

if (SUCCEEDED(hr))

{

m_pConnect->Release();

m_pConnect = NULL;

m_pRangeCalc->Release();

m_pRangeCalc = NULL;

// Only try to unload the AppDomain if the host application

// has not started a shutdown.

if (!isShutdownInProgress)

{

if (m_pCLRLoader)

{

// Unload the AppDomain, and null the pointer to make

// sure we only do this once.

hr = m_pCLRLoader->Unload();

m_pCLRLoader = NULL;

}

return hr;

}

If you’re implementing IDTExtensibility2 in your shim, you can leave the rest of the IDTExtensibility2 methods just as the wizard generated them.

Next, implement your custom interface method(s), as illustrated below. Once you have the .TLH for your custom typelib, all the types declared in it become available to intellisense. So, for example, declaring an Excel Range parameter turns out to be pretty simple:

//IRangeCalc implementation:

STDMETHOD(SumValues)(RangeUDF::Range *r, double *pRetVal)

{

return m_pRangeCalc->SumValues(r, pRetVal);

}

Finally, in the ConnectProxy.cpp, find the implementation of FinalConstruct. The wizard-generated code will give you everything you need to set up the shim and connect it to the managed assembly. You need to add a line to get from the IDTExtensibility2 pointer to the custom UDF interface, via QueryInterface, eg:

HRESULT CConnectProxy::FinalConstruct()

{

HRESULT hr = S_OK;

// Create an instance of a managed addin

// and fetch the interface pointer

m_pCLRLoader = CCLRLoader::TheInstance();

IfNullGo(m_pCLRLoader);

IfFailGo(m_pCLRLoader->CreateInstance(AssemblyName(), ConnectClassName(),

__uuidof(IDTExtensibility2), (void **)&m_pConnect));

// Initialize the RangeCalc pointer.

IfFailGo(m_pConnect->QueryInterface(

__uuidof(RangeUDF::IRangeCalc), (void **)&m_pRangeCalc));

Error:

return hr;

}

The last step is to build everything, make sure the managed assembly lives in the same folder as the shim DLL, make sure the shim is registered, and make sure the add-in typelib is registered. You should configure your setup project to do all these things, and/or custom build steps for your shim project. Alternatively, for the registration pieces, you can write a simple .REG file and merge it into the registry:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\RangeUDF.Connect]

@="RangeUDF.Connect"

[HKEY_CLASSES_ROOT\RangeUDF.Connect\CLSID]

@="{3c8ed961-b58b-4580-ab67-a45648e2a7b7}"

[HKEY_CLASSES_ROOT\CLSID\{3c8ed961-b58b-4580-ab67-a45648e2a7b7}]

@="RangeUDF.Connect"

[HKEY_CLASSES_ROOT\CLSID\{3c8ed961-b58b-4580-ab67-a45648e2a7b7}\InprocServer32]

@="C:\\Temp\\RangeUDF_shimmed\\RangeUDFShim\\Debug\\RangeUDFShim.dll"

"ThreadingModel"="Apartment"

[HKEY_CLASSES_ROOT\CLSID\{3c8ed961-b58b-4580-ab67-a45648e2a7b7}\ProgID]

@="RangeUDF.Connect"

[HKEY_CLASSES_ROOT\CLSID\{3c8ed961-b58b-4580-ab67-a45648e2a7b7}\Programmable]

[HKEY_CLASSES_ROOT\CLSID\{3c8ed961-b58b-4580-ab67-a45648e2a7b7}\TypeLib]

@="{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}"

[HKEY_CLASSES_ROOT\TypeLib\{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}]

[HKEY_CLASSES_ROOT\TypeLib\{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}\1.0]

@="RangeUDF"

[HKEY_CLASSES_ROOT\TypeLib\{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}\1.0\0]

[HKEY_CLASSES_ROOT\TypeLib\{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}\1.0\0\win32]

@="C:\\Temp\\RangeUDF_shimmed\\RangeUDFShim\\Debug\\RangeUDF.tlb"

[HKEY_CLASSES_ROOT\TypeLib\{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}\1.0\FLAGS]

@="0"

[HKEY_CLASSES_ROOT\TypeLib\{917E2CFA-D16C-41b4-BD33-6EE0254C98FD}\1.0\HELPDIR]

@="C:\\Temp\\RangeUDF_shimmed\\RangeUDFShim\\Debug\\"

As you can see, I’m putting the managed assembly, its typelib and the shim all in the same folder and registering them there. Build everything, run Excel and register the automation add-in shim via Tools | Add-ins | Automation, and you’re done.