Building a WHS AddIn package using a (free) graphical authoring tool
It’s been a while since Windows Home Server MVP Sam Wood published his excellent five-part WHS AddIn development tutorial over at the Tentacle Software Blog. His tutorial covers everything from setting up your development environment (using the free Visual Studio Express) to building your AddIn installation package (using the free WiX toolset).
The WiX (Windows Installer XML) toolset is a great tool for experienced Windows Installer package (MSI) authors but it comes with a steep learning curve. Unfortunately, Visual Studio Express does not contain support for creating setup projects. This feature is reserved for Visual Studio Professional and higher editions. If you want to create your MSI packages using a graphical tool you could of course do so by choosing tools from market leaders like InstallShield from Flexera or WISE Installer from Symantec, but these are quite pricey. A couple of weeks ago I stumbled across another tool for building MSI packages from a company called Caphyon Ltd. Its name is Advanced Installer and the best thing about it: it comes in a free edition that allows us to conveniently create our WHS AddIn Windows Installer package.
In this small tutorial I want to show you how you can package your Windows Home Server AddIn as a Windows Installer package (MSI) using the free edition of Caphyon Advanced Installer.
Step 1: Download and install Advanced Installer
Advanced Installer is small and lightweight. Simply download it from here and run the installation wizard.
Just click through the wizard and Advanced Installer will be set up in no time.
Step 2: Creating our installer project
Run Advanced Installer by finishing the installation wizard or from the shortcut the installer has placed on your desktop and you will be presented with the ‘New project’ dialog.
As you can see, Advanced Installer supports a variety of project types for all your installation needs. Only the ‘Simple’ project type is available in the free edition but this is not a problem as it offers all the functionality we will need to build our WHS AddIn package.
When you select the ‘Simple’ project type and click OK the ‘New Simple Project’ wizard is launched.
First enter the name of your AddIn and your company name. This information will later be displayed in the WHS settings dialog’s available AddIns tab.
Next, select the name and location of your Advanced Installer project file (.aip), the name for your AddIn MSI package and the folder where the MSI package should be placed when it’s being created by Advanced Installer.
Now point the wizard to the folder where your Visual Studio build output is located (your HomeServerConsoleTab.*.dll) and click ‘Finish’.
Step 3: Fine tune the package settings
When the wizard finishes you’ll be brought to the ‘Product Details’ sheet of your setup project. Here you can enter the product version number of your AddIn. Please note that the Windows Installer format for version numbers is major.minor.build which differs from the usual .NET assembly version format (major.minor.build.revision).
Use the navigation pane on the left to switch to the ‘Install Parameters’ sheet. Change the Application Folder to ‘[ProgramFilesFolder]Windows Home Server’. [ProgramFilesFolder] is a symbolic name for “C:\Program Files”. By using it in your application folder setting you can make sure that your AddIn will install properly on non-english versions of the operating system, where this folder is named differently (e.g. “C:\Programme” in German). You should also set the ‘Installation Type’ to ‘Per-machine only’ so only users with administrative privileges will be able to install the package (this is not absolutely necessary since the WHS console from where your AddIn is going to be installed from is running from the Administrator account, but still….).
Now under ‘Properties’ click the ‘New’ button to fire up the ‘New Property’ dialog and enter ‘WHSLogo’ as your property name and ‘1’ as your value. This setting is required for WHS to recognize your MSI package as a valid AddIn installation package. When you’re done the ‘Instal Parameters’ sheet should look like in the second screen here:
You can navigate to the ‘Upgrades’ sheet if you want to see what’s in there but since Windows Home Server does not make use of the automatic upgrade feature of Windows Installer for AddIns you should just leave the setting as it is.
On the ‘Launch Conditions’ sheet under ‘System Launch Conditions’ you should set the minimum Windows NT version to ‘Windows Server 2003 Service Pack 2’. This is the version of Windows Server that WHS v1 is based on and setting it as a requirement will prevent your users from accidentally installing your MSI package on their client machines. Since WHS v1 only comes as 32bit operating system you can disable the Windows NT 64-bit base version requirement.
If your AddIn targets .NET Framework 3.5 you can set it as the minimum .NET version on the ‘Software Launch Conditions’ tab. This way, installation of your AddIn will only be possible on WHS machines that already have .NET Framework 3.5 installed (version 3.5 of the .NET Framework is distributed to WHS via Windows Update so it should be ok to set this requirement).
You even can define your own launch conditions on the ‘Custom Launch Conditions’ tab but that’s beyond the scope of this tutorial. See this MSDN Library topic for more information about custom launch conditions.
Step 4: Complete the package definition
Now it’s time to define the real contents of your MSI package. Go to the ‘Files and Folders’ tab and review the list of files that got imported by the project creation wizard. It automatically should have imported your HomeServerConsoleTab.*.dll and the subfolders containing localization satellite assemblies (if any). You can add additional files by clicking ‘Add Files’ on the toolbar or the context menu.
If you want your installer to add or modify registry keys you can define these on the ‘Registry’ sheet.
Step 5: Building your MSI package
On the ‘Media’ tab’ you can review the output folder and MSI filename settings you made earlier in the project creation wizard (and modify them, if needed). All other settings are already correct and will result in the creation of a single MSI package, so that you don’t have to change anything here.
Now click ‘Build’ on the toolbar or the ‘Project’ menu and wait until Advanced Installer has finished building your MSI package.
If everything goes well the build should finish successfully and you should be able to click the link to your MSI package in the log window of the ‘Build project’ dialog. This will take you directly to the folder where your MSI package has been written to. You can now copy the MSI package to the \Software\Add-Ins share of your WHS test box to install it from the WHS console settings dialog.
Bonus Step: Build automation
If you want to create an up-to-date version of your MSI package every time you build your AddIn project in Visual Studio you’ll be happy to find that Advanced Installer supports build automation from the command line (if you don’t want to use this, just skip this step).
First, create a new .bat-file using Notepad (or whichever text editor you prefer) with this content:
cd /d “C:\Program Files\Caphyon\Advanced Installer 7.6.1\bin\x86″set MSIPROJECT=”C:\Temp\Sample WHS AddIn\SampleWHSAddIn.aip”
set MSIVERSIONFILE=”C:\Temp\Sample WHS AddIn\Sample WHS AddIn\bin\Release\HomeServerConsoleTab.SampleWHSAddIn.dll”
advinst.exe /edit %MSIPROJECT% /SetVersion -fromfile %MSIVERSIONFILE%advinst.exe /build %MSIPROJECT%
Set the correct path of your Advanced Installer installation in the first line. The second line must contain the path to your Advanced Installer project file (.aip) as defined in Step 2 of this tutorial. In line three you specify the full path of the assembly that carries the version number you want to use for your MSI package (your main assembly).
The first call of advinst.exe will instruct Advanced Installer to take the version number of the assembly you specified and set it as version number of your installer project. The second and last call of advinst.exe will then build your installation package (MSI).
Now save this .bat file as ‘autobuild.bat’ (for example) and put the full path to ‘autobuild.bat’ into the ‘Post-build event command line’ box on the ‘Build Events’ tab of your AddIn project properties window in Visual Studio:
Now every time you build your project in Visual Studio the ‘autobuild.bat’ script will be executed and your MSI package will be recreated incorporating your latest code changes.
As you have seen it’s pretty easy to create a professional MSI package of your Windows Home Server AddIn using the free edition of Caphyon Advanced Installer. I personally like this way better than fiddling around with XML and WiX. Of course there’s nothing wrong with using WiX but it’s good to know that there are other free alternatives out there for your personal (and professional) MSI packaging needs.
I’ve been working with the market leading (and quite pricey) InstallShield Premier (which has its share of annoyances and bugs) for years and I have to say that Advanced Installer has the potential to shake up the market for professional Windows Installer package creation tools. For one, this is because it comes with an ingeniously simple user interface which helps you to define your package parameters very easily. Second, it contains some productivity tools like the condition editor with condition validation functionality (not covered in this tutorial) which can be real time savers and which professional MSI developers will love (I don’t want to make this sound like a rant towards InstallShield, but condition validation is an outstanding feature InstallShield still does not have after years in the marketplace).
Now have fun exploring Advanced Installer! Stay tuned for a version of this tutorial covering the package creation for Windows Server Codename ‘VAIL’.