3 simple steps to target multiple Office Versions with a single COM-Add-In
Recently I was nearly driven crazy by the task to create an msi-setup for my version control add-in for Microsoft Access in Visual Studio 2013. I referenced the correct PIA assemblies in my Visual Studio project, but other versions of them ended up on the target machines. My add-in was not working properly on some computers. Actually it was not working at all then.
I finally managed to solve the problem to reliably target multiple versions of an Office Application (Access in my case) with a single add-in. But as it required a bit of research and a lot of trial and error, I am writing this down to help you preserve your sanity if to want to achieve the same.
1. Use the PIAs for the oldest application version you are targeting
The first important thing is to reference the PIAs (Primary Interop Assemblies) for the oldest Office Version you want to support. That is Access 2007 (version 12.0) in my case. Even without the technical requirement to do this to compile an assembly that will run with all intended version, it is helpful during coding, as it prevents you from accidentally using features, which are not available in the older versions of your targeted application.
Downloading and installing the PIAs is fairly straight forward. Referencing them is as well, but that is where the trouble starts. The msi-setup for the PIAs installs them right into the GAC (Global Assembly Cache). When adding the references to your project, you can select the version you need in your project. But if you have got a newer version of the same PIA installed on your machine as well, Visual Studio will automatically perform assembly binding redirection and relink the references to the newer Versions of the files. That is not what I wanted! And the properties of the reference in Visual Studio are somewhat confusing.
2. Put the PIAs in a separate folder specific to your project
To prevent this version mix-up and really compile your add-in with the old PIA-version you selected, you will have to export the PIAs from the GAC to another folder, specific to your project. - I used GACView for this. - Then reference the PIA-files from that folder into your Visual Studio project, using the “browse”- option when adding the references.
It would probably work equally well to disable the assembly binding redirection by editing the policy files in the GAC, as described in this stack-overflow-answer. But that would affect all projects that reference these files on your computer. Therefor I choose the option to put them in a separate folder for my project.
Even now Visual Studio will still write the version number of the highest available version of those files to your project file.
But that does not affect the build process. If you open the compiled assembly in ILDASM and take a look at the assembly manifest, you’ll see that the correct versions of the PIA are referenced there.
Now with the build issues solved we should take care of the setup/deployment process.
3. Explicitly include your local copies of PIAs in the installer project
I currently use a Visual Studio Installer Project to build an msi setup for the users to install my add-in on the target machines. I think this is the most convenient way to create a setup for simple projects. I probably will use WiX (Windows Installer XML toolset) for that end in the future. WiX gives you much more control over your setup project, but it has a much steeper learning curve as well.
When I first just referenced the Office 12.0 PIAs from the GAC in the add-in-project, I ended up with a reference to the 12.0 version, my assembly was linked to the 15.0 version and yet the installer project, automatically detecting dependencies, added the 14.0 (!?) version to the setup. – That was bound for failure.
After changing the things described in Step 1 and 2 it looks like the installer behaves now and is packing the correct versions. Still I want to take no chances anymore and control this myself instead of using the automatic dependency detection.
Therefore I explicitly exclude the automatically detected dependencies to the PIA files from the setup project and then add the files from the file system folder. That leaves no room for any excuse for VS to mess with my setup project.
Now I just build the solution and the installer project and upload the msi setup file to my website. Done!
As an afterthought, I would like to mention that there are some interesting alternatives to this approach that might prevent the whole problem.
You could use the NetOffice API instead of the PIAs to write add-ins for MS Office. NetOffice looks very promising and I actually tried to use it to address my problem. However I found a couple of Microsoft Access’ Enums and Methods (e.g. AcObjectType-Enum and the ControlType- and SourceObject-Properties) are not implemented yet. If you are writing an add-in for Word- or Excel you should definitely evaluate NetOffice as an option for you. These Office Applications are probably better supported by NetOffice as they are more widely used.
2. Embedded Types
Another option might be to use the CLR 4.0 and embed the types from the PIA you are using. This would have actually been my preferred solution, but my project needs to talk to some other APIs as well and those are having serious issues when called by a CLR 4.0 component.
Do you use another reliable approach to create and distribute COM-Add-Ins for Microsoft Office? – Let me know in the comments.