VSTO App Deployment using NSIS – Part 1

For a little over a year, we’ve been working on a very sophisticated Microsoft Excel 2003 Document Level Customization project. We have nothing but pride towards the ingenuity of this application. But, there was one aspect that consistently overshadowed its success: Deployment.

Visual Studio Deployment Projects help you generate a setup app quickly and easily. It has the ability to look up source projects and determine all the components that need to be deployed. This makes things remarkably easy when you want a rudimentary installation. But, for anything out of the ordinary,  you will find that this offers you very limited help. To workaround these limitations you have to pick up a tool called Orca. Now, here’s where things get really dirty.

To use Orca, you have to have some semblance of the MSI database format. That isn’t actually so bad. A simple search on the Internet will fetch you loads of information regarding the subject. But, figuring out the format is just the beginning. You then have to weed your way using some ugly hacks. That’s not all; you have to reapply those hacks with each build. If you are willing to live with the inconveniences, there’s still a lot you can achieve using Orca. Musical Nerdery has a neat example on the subject.

Anyway, the point is we got sick and tired of working within these constraints and started looking for alternatives. After some serious considerations we opt to go with NSIS (Nullsoft Scriptable Installer Suite). We were mostly excited about its low footprint and its powerful scripting language.

This post is the first of a series in which I’m going to guide you through the steps involved in migrating your existing VSTO deployment package to NSIS. Before we begin, I should point out a few of the downsides to using NSIS.

1. NSIS doesn’t understand VS Projects. It cannot scan through your projects and determine which components are relevant. You have to figure out all the files/dependencies you must deploy on to the client PC. Easiest way to do this is by creating a VS Deployment Project and let it tell you which files you need.
2. It cannot perform automatic rollbacks. If you want the user to be able to cancel the installation midway (after some files have already been deployed), you have to roll back the installation yourself using scripts. I’d argue that this is only a minor concern.

Since basic tutorials on NSIS scripting are widely available, I’m going to skip over the basics. You can learn about them here if you need to.

Step 1: Add a Visual Studio Deployment Project to your VSTO Solution

For the purpose of this tutorial I’ll be using a really simple Excel 2003 Document Level Customization project called NsisDemo. All it does is display a message box saying “NSIS Rocks!!!” You can download it here or use your own VSTO project and include a VS Deployment Project as I have done.

Step 2: Begin your NSIS Script

Now, fire up your favorite text editor. I tend to prefer Notepad++ which offers syntax highlighting for NSIS scripts. Create the basic skeleton of a NSIS script in a sub folder of your main solution folder. If you need help getting started check out HM Nis Edit to generate a script for you, or use this one: Sample NSIS Start Script (2.4KB).

Step 3: Include Files that will be Copied to Client Machine

Open your VS Deployment Project. Go to the File System Editor and take a look at the file list under Application Folder.

Lets go ahead and add these files to our script. You’d need to modify the main installer section as well as the uninstaller section.

Section "MainSection" SEC01
    File "..\NsisDemo\bin\Debug\NsisDemo.xls"
    File "..\NsisDemo\bin\Debug\NsisDemo.dll"

    ; Following lines are shortened for better display
    File "C:\WINDOWS\assembly\GAC\..\Microsoft.Office.Interop.Excel.dll"
    File "C:\WINDOWS\assembly\GAC\..\Microsoft.Office.Interop.SmartTag.dll"
    File "C:\WINDOWS\assembly\GAC_MSIL\..\Microsoft.Office.Tools.Common.dll"
    File "C:\WINDOWS\assembly\GAC_MSIL\..\Microsoft.Office.Tools.Excel.dll"
    File "C:\WINDOWS\assembly\GAC\..\Microsoft.Vbe.Interop.dll"
    File "C:\..\Microsoft.VisualStudio.OfficeTools.Controls.ManagedWrapper.dll"
    File "C:\..\Microsoft.VisualStudio.Tools.Applications.Runtime.dll"
    File "C:\..\Microsoft.VisualStudio.Tools.Applications.Runtime.tlb"
    File "C:\WINDOWS\assembly\GAC\..\office.dll"
    File "C:\WINDOWS\assembly\GAC_MSIL\..\VSTOStorageWrapper.Interop.dll"
SectionEnd

Section Uninstall
    Delete "$INSTDIR\NsisDemo.xls"
    Delete "$INSTDIR\NsisDemo.dll"
    Delete "$INSTDIR\uninst.exe"
    Delete "$INSTDIR\VSTOStorageWrapper.Interop.dll"
    Delete "$INSTDIR\office.dll"
    Delete "$INSTDIR\Microsoft.VisualStudio.Tools.Applications.Runtime.tlb"
    Delete "$INSTDIR\Microsoft.VisualStudio.Tools.Applications.Runtime.dll"
    Delete "$INSTDIR\Microsoft.VisualStudio.OfficeTools.Controls.ManagedWrapper.dll"
    Delete "$INSTDIR\Microsoft.Vbe.Interop.dll"
    Delete "$INSTDIR\Microsoft.Office.Tools.Excel.dll"
    Delete "$INSTDIR\Microsoft.Office.Tools.Common.dll"
    Delete "$INSTDIR\Microsoft.Office.Interop.SmartTag.dll"
    Delete "$INSTDIR\Microsoft.Office.Interop.Excel.dll"
    RMDir "$INSTDIR"

    DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}"
    SetAutoClose true
SectionEnd

Note that all the non-user files (files other than NsisDemo.xls and NsisDemo.dll) are part of the Office 2003 PIAs. You might chose to deploy these files properly using the PIA installer. But, for now lets keep things simple and stick to copying them to the install directory.

At this point you may compile the script to generate an executable installer file. However, the VSTO application deployed through it will fail at run time as there are lot more missing pieces we need to stitch in to it.

Up next: Part 2