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.

139-wix 140-wix

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.

141-wix 142-wix

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.

<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Product
    Name="My First Add-In"
    Id="*"
    UpgradeCode="{1a7c55f0-ceed-11dd-ad8b-0800200c9a66}"
    Manufacturer="Sam Wood - Tentacle Software"
    Version="0.0.0.1"
    Language="1033">
    <Package
      Manufacturer="Sam Wood - Tentacle Software"
      InstallerVersion="200"
      Languages="1033"
      Compressed="yes" />
 
    <Media Id="1" Cabinet="MyFirstAddIn.0.0.0.1.cab" EmbedCab="yes" />
 
    <Property Id="WHSLogo">1</Property>
 
    <Condition Message="[ProductName] requires Windows Home Server. For more information, please refer to the User Guide.">VersionNT = 502</Condition>
 
    <Directory 
      Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder" Name="PFiles">
        <Directory Id="WHS" Name="Windows Home Server">
          <Component 
            Id="HomeServerConsoleTab.My_First_Add_In" 
            Guid="{47d62350-ceed-11dd-ad8b-0800200c9a66}">
            <File 
              Id="HomeServerConsoleTab.My_First_Add_In.dll" 
              Name="HomeServerConsoleTab.My_First_Add_In.dll" 
              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" 
              Vital="yes" 
              KeyPath="yes" 
              DiskId="1"/>
          </Component>
        </Directory>
      </Directory>
    </Directory>
 
    <Feature Id="ProductFeature" Title="MyFirstAddIn" Level="1">
      <ComponentRef Id="HomeServerConsoleTab.My_First_Add_In" />
    </Feature>
  </Product>
</Wix>

 

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

143-wix

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!

pause
"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"

144-wix

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.

145-wix 146-wix

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.

147-wix 148-wix

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.

149-wix 150-wix

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.

151-wix

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.

posted on Sunday, December 21, 2008 1:59 PM | Filed Under [ Windows Home Server Development ]

Comments

Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (JammerX19 @ 12/21/2008 4:51 PM)

Thanks for writing this tutorial. I've enjoyed all five installments. One suggestion: when making the installer.bat, save yourself some text editing by creating an environment variable to contain the base path to the project folder, as follows:

pause
SET APP_PATH=C:\Documents and Settings\Jody\My Documents\Visual Studio 2008\Projects\My First Add-In\My First Add-In
"C:\Program Files\Windows Installer XML v3\bin\candle" -out "%APP_PATH%\bin\Release\install.wixobj" "%APP_PATH%\installer.wxs"
"C:\Program Files\Windows Installer XML v3\bin\light" "%APP_PATH%\bin\Release\install.wixobj" -out "%APP_PATH%\bin\Release\MyFirstAddIn.0.0.0.1.msi"
 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (Sam Wood @ 12/21/2008 5:11 PM)

Great suggestion, Jammer.
 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (TxDot @ 6/30/2009 2:40 PM)

Hi Sam,
Do you recommend adding a separate project to the solution for the install side of things or is simply adding a XML file to the main project sufficient. What are the pros & cons to each approach?

Thanks...TxDot
 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (Sam Wood @ 6/30/2009 3:00 PM)

Separate project for the installer if you're using Visual Studio Professional, or a separate Solution folder if you're using Visual Studio Express.

The WiX integration into Visual Studio 2005/2008 Professional requires a separate WiX project to build the MSI package. So if you're using the non-free version of Visual Studio, you should create a different project.

If you're not using Visual Studio Professional, I'd create a solution folder in the root of the Solution and keep the XML file there. It keeps your add-in project clean, and means you don't have to mark the XML file as no-copy/no-build.

 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (Matt @ 7/13/2009 7:16 AM)

Totally Kick @$$ tutorial! Been looking high and low for stuff like this.... This has to be one of the absolute best tutorials I've seen online, for any programming subject, ever. Couldn't be easier. Especially love the links to the preconfigured template and the detailed WiX walkthrough. Never heard of wix before, looks great!
 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (Sam Wood @ 7/13/2009 7:28 AM)

Thanks Matt, glad I was able to help.

 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (Bernd @ 8/15/2009 11:54 PM)

Thanks for this realy good tutorial!

Instead the installer.bat i've added two lines to Postbuild:

"C:\Program Files\Windows Installer XML v3.5\bin\candle" -out "$(TargetDir)install.wixobj" "$(ProjectDir)installer.wxs"

"C:\Program Files\Windows Installer XML v3.5\bin\light" "$(TargetDir)install.wixobj" -out "$(TargetDir)$(TargetName).msi"
 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (Sam Wood @ 8/19/2009 6:35 PM)

Great idea, Bernd.

 
Gravatar
# re: "Hello World" Windows Home Server Add-In: Part 5 (noor @ 5/13/2010 4:00 AM)

thiz like

Post Comment

Title *
Name *
Email
Url
Comment *  
Remember me
Please add 3 and 4 and type the answer here:

Search

Site Sections

Recent Posts

Archives

Post Categories

WHS Add-In Tutorial

WHS Blogs

WHS Development