This topic examines the requirements for client applications that use XLL wrapper assemblies.

This topic contains the following sections.

.NET clients

The XLL wrapper assembly is a well-behaved .NET assembly. It can be used just like any other .NET DLL assembly.

References

Applications that use wrapper objects need two references: one for the wrapper library, and one for the XLL+ wrapper support classes. In each case the reference should be to the assembly (.dll) file.

In Visual Studio, Use the Add Reference... menu to open the Add Reference dialog. Select the Browse tab, and navigate to the directory containing the assembly.

The wrapper objects' assembly will be in the wrapper project's output directory (either bin\release or bin\debug), and will have the extension .dll, e.g. MyAddin.dll.

A copy of the XLL+ wrapper support classes' assembly, XllPlus.ComWrappers.Runtime.dll, can be found in the same directory as the wrapper assembly.

Initializing the engine

You should initialize the engine using Create. Remember that the engine will create an invisible instance of Excel, so do not create and destroy When you have finished with the engine, call Destroy.

CopyC#
using XllPlus.ComWrappers.Runtime;

ExcelWrapperEngine engine = new ExcelWrapperEngine();
engine.Create();
engine.LoadXll(theXllFile);

// ... Use the engine ...

engine.Destroy();
Caution:

Remember that the engine will create an invisible instance of Excel, so do not create and destroy engines more often than necessary.

.NET wrapper classes

After creating an instance of a wrapper class, remember to set its Engine property to an initialized engine:

CopyC#
using XllPlus.ComWrappers.Runtime;

ExcelWrapperEngine engine = new ExcelWrapperEngine();

ApiTest api = new ApiTest();
api.Engine = engine;

// ... Use the wrapper class ...

api.Dispose();

Wrapper classes are lightweight, and they support IDisposable, so it is often convenient to put them within a using block:

CopyC#
using XllPlus.ComWrappers.Runtime;

ExcelWrapperEngine engine = new ExcelWrapperEngine();

using (ApiTest api = new ApiTest())
{
    api.Engine = engine;

    // ... Use the wrapper class ...
}

The wrapper object will be disposed automatically at the end of the using block.

For more details see the ApiTest sample.

COM clients

Wrapper assemblies are COM-visible, and all their public methods are also legal COM methods. The instructions below are for COM clients written in Microsoft C++; the implementation details will vary for other client environments and languages.

References

Applications that use wrapper objects need two references: one for the wrapper library, and one for the XLL+ wrapper support classes. In each case the reference should be to the type library (.tlb) file, not to the assembly (.dll) file.

The XLL+ wrapper support classes' type library file, XllPlus.ComWrappers.Runtime.tlb, can be found in the bin sub-directory of the XLL+ installation (e.g. C:\Program Files\Planatech\XllPlus\6.0\VS9.0\bin\XllPlus.ComWrappers.Runtime.tlb). A line such as the following will import it to the C++ application:

CopyC++
#import "C:\Program Files\Planatech\XllPlus\6.0\VS9.0\bin\XllPlus.ComWrappers.Runtime.tlb"

Alternatively, you may prefer to make a copy of the type library in your client project directory, so that you can simply write:

CopyC++
#import "XllPlus.ComWrappers.Runtime.tlb"

The wrapper objects' type library will be in the same directory as the assembly, and will have the extension .tlb, e.g. MyAddin.tlb. You can use code like the following to import it:

CopyC++
#import "..\ApiTestLib\bin\Release\ApiTestLib.tlb"

Initializing the engine

You should initialize the engine using Create. Remember that the engine will create an invisible instance of Excel, so do not create and destroy When you have finished with the engine, call Destroy.

Note:

As usual with COM objects, your pointers should reference the primary interface of the object, i.e. IExcelWrapperEngine.

CopyC++
using namespace XllPlus_ComWrappers_Runtime;

IExcelWrapperEnginePtr engineInstance(__uuidof(ExcelWrapperEngine));
engineInstance->Create();
engineInstance->LoadXll(theXllFile);

// ... Use the engine ...

engineInstance->Destroy();
Caution:

Remember that the engine will create an invisible instance of Excel, so do not create and destroy engines more often than necessary.

COM wrapper classes

The wrapper classes each implement a default interface. The interface's name is, by default, the class name prefixed with I, e.g. IMyAddin for a class MyAddin. As usual in C++ COM programming, your pointers should be to the default interface, not the object.

Special consideration is also needed for the Engine property. You must cast the IExcelWrapperEngine interface to a IWrapperEngine interface explicitly. Take care to drop the reference when it is no longer required.

CopyC++
using namespace XllPlus_ComWrappers_Runtime;

IExcelWrapperEnginePtr engineInstance(__uuidof(ExcelWrapperEngine));
engineInstance->Create();
engineInstance->LoadXll(theXllFile);

// Create IWrapperEngine pointer
IWrapperEnginePtr engine(engineInstance);

try
{
    ApiTestLib::IApiTestPtr api(__uuidof(ApiTestLib::ApiTest));
    api->Engine = engine;

    // ... Use the wrapper object ...
}
catch(_com_error e)
{
    _tprintf(_T("%s\n"), (LPCTSTR)e.Description());
}

engine.Detach();
engineInstance->Destroy();

For more details see the ApiTest sample.

VBA clients

Visual Basic for Applications (VBA), provided as part of Office and Excel, as well as some other applications, requires slightly different handling from standard COM clients.

References

Modules that use wrapper objects need two references: one for the wrapper library, and one for the XLL+ wrapper support classes. In each case the reference should be to the type library (.tlb) file, not to the assembly (.dll) file.

Use the Tools/References... menu to open the References dialog. Then use the Browse... button to navigate to the directory containing the type library.

The XLL+ wrapper support classes' type library file, XllPlus.ComWrappers.Runtime.tlb, will be in the bin sub-directory of the XLL+ installation (e.g. C:\Program Files\Planatech\XllPlus\6.0\VS9.0\bin\XllPlus.ComWrappers.Runtime.tlb).

The wrapper objects' type library will be in the same directory as the assembly, and will have the extension .tlb, e.g. MyAddin.tlb.

Initializing the engine

If you are calling the wrapper library from Excel VBA, then you should initialize the engine using Attach, passing the existing instance of Excel. When you have finished with the engine, call Detach.

CopyVBA
Dim engine As New ExcelWrapperEngine
engine.Attach Application
engine.LoadXll strXllFile

'... Use the engine ...


engine.Detach
Important Note:

You should not call Create from Excel VBA. This will create a new hidden instance of Excel instead of using the current instance.

VBA wrapper classes

VBA supports only a subset of COM's capabilities, so methods designed for use in VBA have to provide special handling for (among other things) arrays and dates. Alongside each wrapper class, a second version, designed only for use from VBA is also generated. If the standard wrapper class is named MyAddin, then the VBA version will be named MyAddinVba.

CopyVBScript
Dim engine As New ExcelWrapperEngine

'... Initialize the engine ...


Dim wrapper As New ApiTestVba
Set wrapper.engine = engine

'... Use the wrapper object ...

For more details see the ApiTest sample.

See Also