Deploy Office 2007-2000 add-in / plugin
Use shims and loader in C#, VB.NET, C++

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home > Add-in Express .NET > Online Guide > Deploying Office add-ins

Deploying Add-in Express projects

Shims in Add-in Express projects
Deploying Office COM add-in with Add-in Express ClickOnce solution
Creating setup projects manually

Shims in Add-in Express projects

You have three isolation options when creating Add-in Express .NET projects. You can see them in the Add-in Express Project Wizard window. Every isolation option uniquely determines the shim and this, in its turn, influences on the deployment of your project.

What are shims?

All Office applications are unmanaged while all Add-in Express .NET based add-ins are managed class libraries. Therefore, there must be some software located between Office applications and your add-ins. Otherwise, Office applications will not be able to learn about your .NET add-ins and other Office extensions. That software is called a shim. Shims are unmanaged DLLs that isolate your add-ins in a separate application domain.

When you install your add-in, the registry settings for the add-in will point to the shim. And the shim will be the first DLL examined by the host application when it runs your add-in or smart tags.

Add-in Express Loader

If, in the project wizard windows, you choose the Add-in Express Loader and automatic setup project generation options, the wizard goes through the steps listed in the Creating Setup Projects Manually and generates the solution that includes the Add-in Express Loader based add-in project and appropriate setup project.

Add-in Express Loader (adxloader.dll) is a compiled shim not bound to any certain Add-in Express project. Instead, the loader uses the adxloader.dll.manifest file containing a list of .NET assemblies that must be registered. The loader's files (adxloader.dll and adxloader.dll.manifest) must always be located in the Loader subdirectory of the main Add-in Express project directory. When an Add-in Express based project is being built, the loader files are copied to the project's output directory. You can sign the loader with a digital signature and create trusted COM extensions for Office. For Add-in Express loader based setup projects,, the loader provides ready-to-use Install, Uninstall, and Rollback custom actions.

The manifest is the source of configuration information for the loader. Below, you see the contents of a sample manifest file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <assemblyIdentity name="MyAddin14, PublicKeyToken=f9f39773da5c568a" />
  <loaderSettings generateLogFile="true" shadowCopyEnabled="true"
privileges="user" />
</configuration>

The manifest file allows generating the log file containing useful information about errors on the add-n loading stage. The log file is located here: My Documents\Add-in Express\adxloader.log. The manifest file allows you to disable the Shadow Copy feature of Add-in Express Loader, which is enabled by default (see Deploying - shadow copy). The privileges attribute accepts the "user" string indicating that the Add-in Express based setup projects can be run with non-administrator privileges. Please, note, any other value will require administrator privileges to install your project. You should be aware that the value of this attribute is controlled by the RegisterForAllUsers property value of the add-in and RTD module.

Also, you can run regsvr32 against the adxloader.dll. If the correct manifest file is located in the same folder, this will register all Add-in Express projects listed in the loader manifest.

VSTO Loader

VSTO Loader is a compiled shim that must be pre-installed on the PC as a part of the VSTO Run-time installation. The loader uses the vstoloader.manifest file that supplies VSTO loader with all the information it needs. The manifest must always be located in the Loader subdirectory of the main Add-in Express project directory. For VSTO loader based setup projects, Add-in Express supports the Install, Uninstall, and Rollback custom actions provided by a special .NET assembly called Add-in Registrator (adxregaddin.exe). It is located in the Redistributables folder of Add-in Express setup folder.

Starting from version 3.5, Add-in Express project wizard provides the VSTO Loader option. When using this option you should be aware of the following points.

Creating an add-in project

• VSTO Loader supports Office 2003 and 2007 only.
• You cannot use Version-Neutral PIAs in this case: they are not recognized by VSTO Loader.
• The AddinExpress.MSO.OfficeTools namespace is located in the AddinExpress.MSO.OfficeTools.dll; it is added to the setup project automatically.

Developing the add-in

The Loader folder contains the only file vstoloader.manifest generated automatically; it could resemble the following one:

<?xml version="1.0" encoding="utf-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1"
xmlns:asmv2="urn:schemas-microsoft-com:asm.v2" manifestVersion="1.0">
  <assemblyIdentity name="MyAddin12.dll" version="1.0.0.0" />
  <asmv2:entryPoint name="Startup" dependencyName="dependency0">
    <asmv2:clrClassInvocation class="MyAddin12.ADXAddinEntryPoint" />
  </asmv2:entryPoint>
  <asmv2:dependency asmv2:name="dependency0">
    <asmv2:dependentAssembly>
      <assemblyIdentity name="MyAddin12" version="1.0.0.0" />
      <asmv2:installFrom codebase="MyAddin12.dll" />
    </asmv2:dependentAssembly>
  </asmv2:dependency>
</assembly>

Add-in module in this case inherits from AddinExpress.MSO.OfficeTools.ADXAddin and not from AddinExpress.MSO.ADXAddinModule.

Registering / unregistering the add-in

When you run Build / Register Add-in Express Project menu command, Add-in Express creates the following code group: User / Code groups / All code / <Add-in Module GUID> <ProgId>, and grants it the "Full Trust" permission. You can find the group in Control Panel / Administrative Tools / .NET Framework 2.0 configuration. Note, the Add-in Registrator (adxregaddin.exe) provides exactly the same functionality.

Deploying the add-in

For the setup project, the functionality above is provided by the custom action DLL called adxregaddin.dll. See the use of this DLL in the Custom Actions view of any setup project created using the VSTO Loader and Create the Setup Project options.

Non-isolated Add-in Express projects

If you choose the Non Isolated option in the Add-in Express Project wizard, your add-ins are loaded into the host application with a universal shim called MSCoree.Dll. This shim is pre-installed with the version of .NET Framework required by your add-in. That is, you don't need to include it into your setup project.

Typically, you use this shim when your add-in doesn't have any special requirements to security. The main advantage of using this shim is its simplicity. However, you cannot sign it, and this is its main drawback. If the host application security is set to Medium, High or Very High (Tools | Macro | Security), MSCoree based add-ins will not start even if you sign them.

There is another drawback: if an MSCoree based add-in fires an unhandled exception, the user can opt to stop the add-in from loading for the next time and this will effectively stop all MSCoree based add-ins from loading. 

Shim comparison table

Back to Add-in Express .NET homepage