Shims, Loader and Add-in Express .NET Setup projects

Seems, not many people really understand shims. Hopefully, this article will help them to forget about shims at all.

What is a shim? What is the Add-in Express .NET Loader?

There must be some software located between Office applications that are COM applications and your add-ins that are .NET libraries. Otherwise, Office apps will not know of your .NET add-ins. If we exclude mcoree.dll from the list, that software takes two forms: shim and loader. Naturally, that software must be a) adapted for your add-in, b) included in the add-in setup project. This software is called a shim.

Mscoree.dll is a universal shim included in the .NET Framework. You don’t need to include it in your setup projects.

The Add-in Express .NET shim is personalized for your add-in by placing your add-in assembly attributes to some constants. That means that the shim project must be built when the setup project for your add-in is created.

The Loader included in Add-in Express .NET v.2.7 is a compiled shim that can be tailored for your add-in with the help of the manifest file. Being a compiled assembly, it doesn’t require compilation when the setup project for your add-in is created.

Of course both the Add-in Express .NET shim and the Loader must be included in the setup project. When starting a new add-in project, the Add-in Express .NET wizard allows choosing between the shim and Loader approaches. It also provides the automatic generation of the setup project.

If you choose the shim and automatic setup project generation, the Add-in Express .NET wizard does the following:

• Creates add-in, shim and setup projects.
• Adds the shim project’s Primary Output to the setup project.
• Writes the shim’s ProgID to the ShimProgId property of the Add-in Module.
• Adds the add-in Primary Output to the setup project.
• Adds AddinExpress.Install.2003.dll or AddinExpress.Install.2005.dll to the setup project.
• Generates custom actions that reference AddinExpress.Install.2003.dll or AddinExpress.Install.2005.dll.

If you choose the Loader and automatic setup project generation, the Add-in Express .NET wizard does the following:

• Creates add-in and setup projects.
• In the add-in project folder, creates the Loader folder and places the adxLoader.dll in it.
• Generates adxLoader.dll.manifest and places it into the Loader folder.
• Adds the add-in Primary Output to the setup project.
• Adds the adxLoader.dll and adxLoader.dll.manifest files to the setup project.
• Generates custom actions that reference adxLoader.dll.

You can go through all the steps above manually if you use the Deployment Guide at www.add-in-express.com/projects/deploymentguide.zip.

As you see now, to move your existing add-in from shim to Loader you need to perform the following:

• Remove the shim’s Primary Output from the setup project.
• Clear the ShimProgId property of the Add-in Module.
• Create the Loader folder and copy adxLoader.dll from the Redistributables subfolder of the ADX installation directory to the Loader folder.
• Create adxLoader.dll.manifest and save it to the Loader folder (see details below).
• Add adxLoader.dll and adxLoader.dll.manifest to the Application Folder of the setup project.
• Edit custom actions (see details below).

Creating adxLoader.dll.manifest

The manifest file has the following format:
<?xml version=”1.0″ encoding=”utf-8″?>
<configuration>
<assemblyIdentity name=”<the name of the add-in assembly>, PublicKeyToken=<public key token of the add-in assembly>” />
</configuration>

E.g.
<?xml version=”1.0″ encoding=”utf-8″?>
<configuration>
<assemblyIdentity name=”MyAddin10, PublicKeyToken=4590b35563ddbf3d” />
</configuration>

The name attribute of the assemblyIdentity node includes the name of you add-in assembly (without ‘.dll’) and PublicKeyToken of your add-in assembly. The latter can be found in the setup project (that must be already built) – click on your add-in primary output in the setup projects and, in the Properties window, expand the KeyOutput property and see the PublicKeyToken property value.

Loader custom actions

When using the Loader you will have to edit the setup project custom actions for your add-in to install and uninstall correctly. You need to do the following:
Delete the setup actions which refer to the AddinExpress.Install.2003.dll or AddinExpress.Install.2005.dll files
For the Install, Rollback and Uninstall custom actions, to add adxLoader.dll and edit its EntryPoint property values according to the following table

Registry entries for add-ins

What follow below are the values of the InprocServer32 node for different add-in registration entries in the System Registry: