This is the fifth part in a series of tutorials aimed at guiding novice developers though building a "Hello World" Windows Home Server Add-In, using only freely-available tools (including Visual Studio Express).
In Part 5, the last part of our tutorial, we'll wrap our Add-In as part of an MSI package so we can deploy it using the Windows Home Server Console.
For this tutorial, we're building a Windows Home Server Add-In that detects changes to Shared Folder permissions. You can access the other parts of the tutorial, or download the code I'm using in the screenshots, using the links below.
- Part 1: Installing and configuring your development environment
- Part 2: Designing a GUI and initial deployment test
- Part 3: Responding to Windows Home Server Notifications (code)
- Part 4: Using FancyListView and comparing permissions (code)
- Part 5: Building an installer package using WiX (code)
Note: The code samples below don't copy and paste very well directly into Visual Studio. If you don't want to type them out by hand, copy the sample into WordPad, and then copy from WordPad into Visual Studio.
Part 1: Add a new XML file
Creating an installer package for our Add-In is relatively straightforward. We just need to create a new XML file as part of our solution that contains the metadata needed by WiX to build the correct MSI file.
Right-click our project and add a New Item. Choose XML File and name the file installer.wxs.
You'll be presented with a new, blank, XML file. The easiest way to build WiX files is to reuse an existing one, so we'll use the same XML data I use for WHS Disk Management.
You'll want to change the Manufacturer information, of course. Also, where you see GUIDs (UpgradeCode and Component Guid), you'll want to generate your own unique values (use the same tool as last time: http://www.famkruithof.net/uuid/uuidgen).
Since we're only adding a single file, the XML isn't too complex. Note the Component Source directory path; you'll want to make sure this is correct on your development machine (you're probably not logged in as Administrator, for example).
The other critical section is the Property identified as WHSLogo. The Windows Home Server Console checks this value to determine if your MSI file is a valid WHS Add-In, so make sure you set it to 1.
Name="My First Add-In"
Manufacturer="Sam Wood - Tentacle Software"
Manufacturer="Sam Wood - Tentacle Software"
<Media Id="1" Cabinet="MyFirstAddIn.0.0.0.1.cab" EmbedCab="yes" />
<Condition Message="[ProductName] requires Windows Home Server. For more information, please refer to the User Guide.">VersionNT = 502</Condition>
<Directory Id="ProgramFilesFolder" Name="PFiles">
<Directory Id="WHS" Name="Windows Home Server">
Source="C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\My First Add-In\My First Add-In\bin\Release\HomeServerConsoleTab.My_First_Add_In.dll"
<Feature Id="ProductFeature" Title="MyFirstAddIn" Level="1">
<ComponentRef Id="HomeServerConsoleTab.My_First_Add_In" />
Part 2: Create a batch file
If you're lucky enough to own a copy of Visual Studio (that isn't the Express edition), WiX will integrate with your development environment. That means you can build MSI packages from within Visual Studio as part of your normal project build process.
Because we're using Visual Studio Express, we don't get that integration. We'll have to use the WiX command-line tools to get the job done.
To make things easier, we'll create a batch file so that we don't have to type the same commands over and over (trust me, you'll be doing a lot of MSI building if you're a WHS developer!). Right-click the project and add a New Item. This time, we'll create a text file.
Call it installer.bat.
Visual Studio creates a text file with an encoding that doesn't quite work. That's OK, it just means that the first line in our batch file will error out; we'll make sure our first line doesn't really matter.
Add the following text to our batch file and save it. Again, note our paths pointing to the \bin\release folder of our project; make sure they match the paths on your development machine. The quotes are important too, don't forget them!
"C:\Program Files\Windows Installer XML v3\bin\candle" -out "C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\My First Add-In\My First Add-In\bin\Release\install.wixobj" "C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\My First Add-In\My First Add-In\installer.wxs"
"C:\Program Files\Windows Installer XML v3\bin\light" "C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\My First Add-In\My First Add-In\bin\Release\install.wixobj" -out "C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\My First Add-In\My First Add-In\bin\Release\MyFirstAddIn.0.0.0.1.msi"
Once you're done, save the file. Navigate to your project's directory and run the installer.bat file. You should see candle and light building the MSI package.
When the command prompt disappears, check the \bin\release folder of your project for the new MSI package.
If it's not there, you might be missing some errors that candle or light are throwing; you can add another pause at the end of the batch file to stop the command prompt closing until you press a key.
Step 3: Installing the Add-In
You'll want to clean up our test Add-In file from the previous tutorials so that we can verify our installer is actually installing files. Delete HomeServerConsoleTab.My_First_Add_In.dll from C:\Program Files\Windows Home Server\ on your server.
Copy the MSI file to \Software\Add-Ins on your server.
Now, open the WHS Console, click Settings and change to the Add-Ins tab. Under Available Add-Ins, our Add-In should be listed. Let's install it now.
When the installation is complete, WHS will prompt you to restart the console. Log in again, and, through the magic of television, our Add-In has been installed and is working correctly!
Try uninstalling the Add-In through Settings, and verify that our MSI package can be uninstalled as expected.
Well, that's it for this tutorial. You've created and deployed a Windows Home Server Add-In completely from scratch, and it actually works! Congratulations.