Creating WiX setup project for Office add-ins on Visual Studio 2012 using Add-in Express

If you’ve switched to Visual Studio 2012, you might have noticed that Microsoft has sneakily removed all Visual Studio Installer project types. Instead of the usual Setup Project, Setup Wizard, CAB Project and Merge Module Project templates, the only option we now have is to use the limited edition of InstallShield.

The Visual Studio setup projects are quite literally a thing of the past, as Visual Studio 2010 was the final release that includes the templates.

Add-in Express supports building your setup project with InstallShield, but what to do if you do not have InstallShield installed? A good alternative is the WiX Toolset. It is a free and open source collection of tools with which you can build Windows Installer packages using XML. Another good thing about WiX is that the newly released version 7 of Add-in Express for Office and .net supports it!

Creating a setup project for your Office extension

When you need to create a setup project for your Office extension (whether it is an add-in for Outlook, Excel, Word, PowerPoint or other Office apps supported by Add-in Express) in Visual Studio 2012, all you need to do is right-click on your project in the Visual Studio Solution Explorer and select Create Setup Project from the context-menu.

Add-in Express will then show you a New Setup Project wizard and you can choose to create one of the following installers:

• Visual Studio Installer
• InstallShield
• WiX

If you’re using Visual Studio 2012, the Visual Studio Installer option will never be enabled, and you need to install InstallShield and/or WiX in order for their radio buttons to be enabled.

I only have WiX installed, so in this example, I’ve selected WiX; and Add-in Express will create and add the setup project to the Visual Studio solution.

At first glance, it might look like something did not work properly since the only file in the setup project is Product.wxs. Don’t worry, the WiX source file (.wxs) is the only file you require to create a simple WiX installer!

The insight of the Windows Installer XML (WiX) project

Add-in Express has already added most of the elements you need to the WiX source file, so all you really have to do is to build the setup project for your Office add-in, browse to its bin\Debug folder and run the .msi file. This in turn will start a standard setup program for your addin.

Next, let’s take a look at the Product.wxs file and I’ll explain some of the elements within the file. Each WiX source file needs to start with an XML declaration and a WiX element. All other elements go inside this element.

Inside the WiX element, there should be a Product element, which in turn has a Package child element.

Product element of the WiX setup project

The Product element is used to describe the software inside the installer i.e. your Office Add-in. You can specify the name of your application, the default language (LCID), version number and the manufacturer. Most of these properties should stay the same for all builds, except when you want to increase the version number of your application.

<Package 
  InstallerVersion="200" 
  Compressed="yes" 
  InstallScope="perUser"
  Description="A handy add-in for Office"
  Manufacturer="Add-in Express"
  Languages="1033"
  SummaryCodepage="1252" 
  InstallPrivileges="limited"      
/>

It is, however, a good idea to specify the other attributes, such as the InstallerVersion, which specifies which version of Windows Installer is required for your setup program. InstallScope specifies whether the add-in will be installed per Machine or per User and finally the InstallPrivileges attribute specifies what privileges are required to install the add-in on Windows Vista and above e.g. limited or elevated permissions.

Media element

The file in the setup project is bundled into CAB files. Each Media element in your WiX source file will have its own CAB file. As a rule CAB files should not be larger than 2GB and you can choose whether to embed the CAB file into your .MSI file or not by changing the EmbedCab attribute. This is primarily used for very LARGE setups where you would like to split your installation media over multiple disks.

<ComponentGroup Id="ProductComponents" >
  <Component Id="ProductComponent" Guid="e0e8a9c7-6ebb-486b-9a28-91878c9c38c1" 
    DiskId="1" Directory="INSTALLFOLDER" >
    <RegistryKey Root="HKCU" Key="Software\[Manufacturer]\[ProductName]">
      <RegistryValue Type="string" Name="Installed" Value="[INSTALLFOLDER]" KeyPath="yes" />
    </RegistryKey>
    <File Id="_$(var.OfficeAddIn.TargetName)_dll" Name="$(var.OfficeAddIn.TargetFileName)"
      Source="$(var.OfficeAddIn.TargetPath)" />
    <File Id="_adxloader_dll_manifest" Name="adxloader.dll.manifest"
      Source="$(var.OfficeAddIn.ProjectDir)Loader\" />
    <File Id="_adxloader_dll" Name="adxloader.dll"
      Source="$(var.OfficeAddIn.ProjectDir)Loader\"  />
    <File Id="_adxloader64_dll" Name="adxloader64.dll" 
      Source="$(var.OfficeAddIn.ProjectDir)Loader\" />
    <File Id="_AddinExpress_MSO_2005_dll" Name="AddinExpress.MSO.2005.dll" 
      Source="C:\Program Files (x86)\Add-in Express\Add-in Express for .NET\Bin\" />
    <File Id="_Extensibility_dll" Name="Extensibility.dll"
      Source="C:\Windows\assembly\GAC\Extensibility\7.0.3300.0__b03f5f7f11d50a3a\" />
    <File Id="_Microsoft_Office_Interop_Excel_dll" Name="Microsoft.Office.Interop.Excel.dll"
      Source="$(var.OfficeAddIn.TargetDir)" />
    <File Id="_Microsoft_Vbe_Interop_dll" Name="Microsoft.Vbe.Interop.dll"
      Source="$(var.OfficeAddIn.TargetDir)" />
    <File Id="_Office_dll" Name="Office.dll"
      Source="$(var.OfficeAddIn.TargetDir)" />
  </Component>
</ComponentGroup>

Feature element

This element is used to specify which feature of your Office add-in must be installed and contains a reference to a ComponentGroup element that specifies which files need to be installed with the selected feature.

<UIRef Id="WixUI_FeatureTree"/>

UIRef element

The WiX toolset supports a number of pre-built UI’s, as listed below:

• WixUI_Minimal;
• WixUI_Advanced;
• WixUI_FeatureTree;
• WixUI_InstallDir; and
• WixUI_Mondo.

If you would like to show your own license agreement in your plug-in, all you need to do is add the following WixVariable element to your WiX Source file:

<CustomAction Id="RegisterDll" BinaryKey="adxregistrator_exe" Execute="deferred"
  ExeCommand='/install="[INSTALLFOLDER]$(var.OfficeAddIn.TargetFileName)" /privileges=user /returnExitCode=false'
  Impersonate="yes" />
<CustomAction Id="UnregisterDll" BinaryKey="adxregistrator_exe" Execute="immediate"
  ExeCommand='/uninstall="[INSTALLFOLDER]$(var.OfficeAddIn.TargetFileName)" /privileges=user'
  Impersonate="yes" Return="ignore" />

There is a host of standard custom actions for WiX that will assist you in creating SQL server databases, run database scripts as well as configuring IIS websites and virtual directories to name but a few.

The final word

As you can see, WiX is a very powerful and flexible toolset for creating Windows based installers (MSI) for your Office add-ins. I have barely scratched the surface of what is capable with this toolset and I strongly encourage you to have a look at the WiX documentation.

I’m not the greatest fan of having to edit XML by hand and having some decent tooling for the WiX toolset in Visual Studio would be a tremendous help. Who knows, maybe we’ll see something along these lines in the near future…

Thank you for reading. Until next time, keep coding!

Updated on 21-Feb-2013:

Guys, if you want to convert your Visual Studio setup projects (vdproj) to WiX literally in 1 click, check out VDProj to WiX Converter.

Available downloads:

This example was developed using Add-in Express for Office and .net:
Sample Office add-in with WiX installer