Though I don’t use WiX anymore, I do still follow the project. You may ask yourself why I don’t use it anymore since I created a series of WiX articles and apparently spent a lot of time with it? The answer is simple: I switched jobs about a year ago and MSI’s are overkill for deploying our current solutions (all web) to the web servers.

Back to the topic though. A few days ago Scott Hanselman published an interview with Rob Mensching (creator of WiX) that should be interesting to you if you’re using or planning to use MSI’s. One thing that was new to me though is that Rob actually created Orca as an intern at MS in 98! If you don’t know/use Orca you should really check it out (even though Rob says nobody uses it anymore ). It’s a great small tool that lets you peek inside and change the internal MSI database. Really helpful to find out what’s going on inside an MSI.

A bit late announcement from me, but 4th of July WiX version 3.0 was declared stable. You can also find updated documentation for v.3.

Regarding my focus on WiX lately I haven't done much in WiX for a while. I was planning to add some more posts to my WiX tutorials, but currently this has not been my priority after I changed job. I used to work for an ISV where deployment was very important. Where I currently work we're in full control of all servers we deploy to. I do however plan to do some stuff with WiX here as well, but that will have to be later.

A little self promotion Back in September last year, Einar Ingebrigtsen interviewed me about Agile, CI and other stuff I’ve been working on at Contiki. You can check out the podcast here: http://www.ingebrigtsen.info/post/2009/01/15/3cAgile-talk-with-Jon-Aril-Tc3b8rresdal-3e.aspx

Thanks Einar for doing this. Was very strange hearing myself talk. Don’t think I’ve done that since elementary school

Heath Stewart announced today that WiX 3.0 is officially in Beta. So what does that mean? Haven’t it been in Beta for a long time? Rob Mensching has this to say about that on his blog:

In this case the Beta release marks the turning point where all of the major features for this release are finished and the bug flow such is under control and on a solid downward trend.

That’s good to know. For me though I’ve found WiX 3.0 to be quite stable for a long time. Yes, I’ve found bugs, but not any that have scared me so that I’ve consider not using it for production. Yes, for production. Actually I’ve found WiX to be more stable than many of the existing commercial deployment products already out there. Not naming any names

So are you planning to or already playing with WiX? Go get the latest version (3.0.4805.0): http://sourceforge.net/project/showfiles.php?group_id=105970&package_id=168888

This is my fifth post in my WiX and DTF series. Here are some others I’ve written:

• An introduction 
• Using WiX to author MSI installations
• Using a bootstrapper to force elevated privileges in Vista
• Using a Custom Action to list available web sites on IIS

After working quite a bit with Custom Actions (CA’s) in managed code I thought it was about time to show how we can debug CA’s. Before DTF it was almost impossible to step into your code written in C++, VB Script or Java Script and debug. With DTF this is simple, but still not 100% intuitive or straight forward. You have two options mentioned in the DTF documentation for debugging your code and a third which is not mentioned:

1. Use environment variable MMsiBreak (not to be confused with MsiBreak)
2. Attach the debugger to the process via a message box
3. Use System.Diagnostics.Debugger.Launch

Using MMsiBreak

Here’s how to add MMsiBreak to your environment variables in Vista:

1. Start –> Right click Computer –> Properties (or navigate to Control Panel –> System)
2. Select Advanced system settings
3. Click Environment Variables…
4. In the System variables section click New…
5. Set Variable name = MMsiBreak
6. Set Variable value = Name of your custom action method

On my computer it looks like this:

In my example it will break for debugging when Windows Installer is executing the CA GetWebSites. When that happens you will get the following dialog:

Select Yes and you will be prompted to select a debugger to use. If you already have your solution open in VS, you will get the option of using that. Note however that on Vista admin privileges is required, so you need to have your Visual Studio running as admin in order for it to bee listed in the below screen:

When I select the running VS (as above I’ve done above) I get something in VS which I can’t quite explain. The first time this happened to me I thought it didn’t work. I get this message:

The thing is that the source code is of course already displayed, but I thought there was some problems with loading the symbols. However, if you just click Ok and hit F5 (Start debugging) in VS, your breakpoint will hit. Just a thing to be aware of if you get this.

Using Message Box

By using a message box you can accomplish the same thing, but this requires changes to your code and a recompile of both your CA project and you WiX project. Personally I prefer the above method, but it’s always nice to have options

In order to debug using message box you must:

1. Make sure you have a reference to System.Windows.Forms.dll.
2. Somewhere in your code (where you want to break) add some code for displaying your message box. Something like this:
   

   MessageBox.Show("Please attach a debugger.");

3. Add a breakpoint somewhere in your code below your message box code
4. Rebuild your CA project as well as you WiX project to get the new changes.
5. Run your MSI.
6. When the message box displays, go to Tools –> Attach to Process… (Ctrl + Alt + P)
7. Find the process named rundll32.exe and attach.
8. Click Ok on the message box in you installation.
9. The breakpoint you set earlier should now be activated in VS

Using Debugger.Launch()

This is exactly the same as using MMsiBreak except you trigger it from code instead of a environment variable. Just add this line to your code where you want to debug:

System.Diagnostics.Debugger.Launch();

This will give you the same “Unhandled exception” dialog as before and the rest is the same.

The MSI log file

If you’ve been working with MSI’s you know this already, but I think this is something every developer/it-expert should know about and in my experience most people don’t. Sometimes when you run an MSI and get an error that maybe causes a rollback and you can’t get the installation to install, you’re stuck with a cryptic error message. If you’re lucky you can Google it and maybe find the problem (or solution), but often this is not the case. Then this little command might come in handy:

msiexec /i NameOfMSI.msi /l*v C:\Temp\install.log

The above command uses msiexec.exe which is what Windows uses when you double click on an msi. Actually Windows does exactly like the above except from the /l*v part and that’s where you tell msiexec to log to a file. Here’s what it means:

/l = Log
* = Everything
v = Verbose

You can skip the v and you will get slightly smaller log file. Personally I use v all the time.

This is my fourth post in my WiX and DTF series. Here are some others I’ve written:

• An introduction 
• Using WiX to author MSI installations
• Using a bootstrapper to force elevated privileges in Vista
• Debug a Managed Custom Action and how to generate an MSI log

Intro

In this article I’ll cover how to allow a user to choose which web site to install an application to by listing available web sites in a list box in the MSI installation wizard. As mention in my previous articles I'm applying best practices (at the best of my knowledge) to have the installer pass the Vista certification, so hopefully that will be the case if you use any of this in production

When doing lookups in IIS using custom actions in the InstallUISequence (as we need to do in order to get available web sites), elevated privileges is required (at least in Vista SP1). This means we need the installation to run as admin. This is also an issue in the WiX extension for IIS as described in this bug report. See my previous article of a workaround for both the UI Sequence part and the bug: Using a bootstrapper to force elevated privileges in Vista

If you did not quite understand what I just said about the sequence stuff, elevated privileges etc., relax and keep reading, you will know by the end of this post and/or by clicking the link above

Overview

This article assume you’ve read my previous article about Using WiX to author MSI installations or that you are somewhat familiar with WiX. If you haven’t done so already and want to follow this article step-by-step, download the WiX project from my previous article here: SimpleWebApp.zip

There is another possibility of course If you’re lazy and just want the complete source for this article, you can download everything from here: SimpleWebApp_WSSelect.zip

Since this article became rather long I’ve structured it into 3 main sections with related sub sections, which hopefully will help you later if you need to look up something:

• Custom Actions
  • Get web sites
  • Add selected web site info to properties
• Create a new dialog
• Changes to Product.wxs (the main WiX file)
  • Custom Table - Storing web site info
  • Properties: Define, store and retrieve
  • Reference CA’s
  • Change the WebSite standard action
  • The complete Product.wxs
  • The End!

Now let’s dig into it!

Custom actions

To add a CA to your solution, do this:

1. Add a new class library project to your solution and name it IISCustomAction
2. Add a reference to Microsoft.Deployment.WindowsInstaller found in the WiX SDK
3. Add a reference to System.DirectoryServices
4. Rename the class created by VS to CustomAction.cs
5. Add the following using’s to CustomAction.cs:
   1. using System.DirectoryServices;
   2. using Microsoft.Deployment.WindowsInstaller;

When building your project a couple of things happens:

• The managed dll (IISCustomAction.dll) is created as expected by a class library
• MakeSfxCA.exe (which is automatically called when building in VS) is creating a new dll based on the managed dll named IISCustomAction.CA.dll (this is the one you need to use in your WiX project)

It’s MakeSfxCA.exe that does all the magic here. The output dll that MakeSfxCA has created is actually a Win32 DLL. Here’s what Christopher Painter says about this:

At runtime, MSI thinks it’s calling a Win32 DLL in it’s own sandbox but in reality the CLR is being fired up out of process and communicated with through a named pipe.

Read the complete article here.

A typical CA looks something like this:

[CustomAction]
public static ActionResult MyCustomAction(Session session)
{
    try
    {
        ...
    }
    catch (Exception ex)
    {
        session.Log("CustomActionException: " + ex.ToString());
        return ActionResult.Failure;
    }
    return ActionResult.Success;
}

The [CustomAction] attribute is needed to tag this method as a CA. The ActionResult returns either (in my case) Failure or Success allowing the installer to respond accordingly. The parameter for this method is a Session object. This object gives me access to the MSI database and the inner workings of Windows Installer allowing me to query the database, access MSI properties etc.

Now you have what you need to start writing CA’s for the Windows Installer, so let’s get cranking.

Custom action – Get web sites
Copy and paste the code below into the CustomAction.cs class in the project you created above:

[CustomAction]
public static ActionResult GetWebSites(Session session)
{
    try
    {
        View listBoxView = session.Database.OpenView("select * from ListBox");
        View availableWSView = session.Database.OpenView("select * from AvailableWebSites");
        DirectoryEntry iisRoot = new DirectoryEntry("IIS://localhost/W3SVC");
        int order = 1;
        foreach (DirectoryEntry webSite in iisRoot.Children)
        {
            if (webSite.SchemaClassName.ToLower() == "iiswebserver" && 
                webSite.Name.ToLower() != "administration web site")
            {
                StoreWebSiteDataInListBoxTable(webSite, order, listBoxView);
                StoreWebSiteDataInAvailableWebSitesTable(webSite, availableWSView);
                order++;
            }
        }
    }
    catch (Exception ex)
    {
        session.Log("CustomActionException: " + ex.ToString());
        return ActionResult.Failure;
    }
    return ActionResult.Success;
}

Here’s what I’ve done in the code above:

• Open two views to the msi database. One for the ListBox table and one for a custom table which I will cover later called AvailableWebSites.
• Get the root entry in IIS by using an LDAP query.
• Iterate every child of the web site to get and store the information I need.

Here’s the code for the two helper methods I use to store the IIS data to the Windows Installer database:

private static void StoreWebSiteDataInListBoxTable(DirectoryEntry webSite, int order, View listBoxView)
{
    Record newListBoxRecord = new Record(4);
    newListBoxRecord[1] = "WEBSITE";
    newListBoxRecord[2] = order;
    newListBoxRecord[3] = webSite.Name;
    newListBoxRecord[4] = webSite.Properties["ServerComment"].Value;
    listBoxView.Modify(ViewModifyMode.InsertTemporary, newListBoxRecord);
}
private static void StoreWebSiteDataInAvailableWebSitesTable(DirectoryEntry webSite, View availableWSView)
{
    //Get Ip, Port and Header from server bindings
    string[] serverBindings = ((string)webSite.Properties["ServerBindings"].Value).Split(':');
    string ip = serverBindings[0];
    string port = serverBindings[1];
    string header = serverBindings[2];
    Record newFoundWebSiteRecord = new Record(5);
    newFoundWebSiteRecord[1] = webSite.Name;
    newFoundWebSiteRecord[2] = webSite.Properties["ServerComment"].Value;
    newFoundWebSiteRecord[3] = port;
    newFoundWebSiteRecord[4] = ip;
    newFoundWebSiteRecord[5] = header;
    availableWSView.Modify(ViewModifyMode.InsertTemporary, newFoundWebSiteRecord);
}

The first method stores data in the ListBox table and the second in my custom AvailableWebSites table.

My custom table (which I’ll explain in more detail later) contains the following columns:

• WebSiteNo
• WebSiteDescription
• WebSitePort
• WebSiteIP
• WebSiteHeader

The ListBox table has these four columns:

• Property
• Order
• Value
• Text

For the ListBox table the Property is used for identifying one specific list box and will allow you to get the Value of the selected item later. The Property must be the same for every record that you want displayed in one single UI list box. Order defines in which order the item are displayed in the list. Value is what’s being returned to you when accessing the property later on. The Text field is what is shown in the UI list box that the end user sees in the MSI wizard.

In my code I set the Property for all records to WEBSITE. The Order is set to 1 the first time and then incremented by 1 every iteration. The Value is set to the web site id and theText is set to the web site name.

After the user have selected the web site we can find out which one by using the WEBSITE property, which will give us the id of the web site (the Value field).

In my custom AvailableWebSites table I store some more details about every web site. But before I can do that I need to get the server bindings from IIS which is formatted like this: ip:port:header. I split these up and add them to to the database. I do the same with WebSiteNo and WebSiteDescription.

In both cases I store the values to the record and update the database (using modify). Note that you have to use InsertTemporary because you’re not allowed to write permanent data to the MSI database during installation.

Custom action – Add selected web site info to properties
After the user have selected a web site in the list box, I call a CA where I store the details about the web site to some public properties. This will make more sense later when we stitch everything together in the WiX product file, but for now here’s the code:

[CustomAction]
public static ActionResult UpdatePropsWithSelectedWebSite(Session session)
{
    try
    {
        string selectedWebSiteId = session["WEBSITE"];
        session.Log("CA: Found web site id: " + selectedWebSiteId);
        View availableWebSitesView = session.Database.OpenView("Select * from AvailableWebSites where WebSiteNo=" + selectedWebSiteId);
        availableWebSitesView.Execute();
        Record record = availableWebSitesView.Fetch();
        if ((record[1].ToString()) == selectedWebSiteId)
        {
            session["WEBSITE_DESCRIPTION"] = (string)record[2];
            session["WEBSITE_PORT"] = (string)record[3];
            session["WEBSITE_IP"] = (string)record[4];
            session["WEBSITE_HEADER"] = (string)record[5];
        }
    }
    catch(Exception ex)
    {
        session.Log("CustomActionException: " + ex.ToString());
        return ActionResult.Failure;
    }
    return ActionResult.Success;
}

Remember the id for the web site that the user selected is stored in the WEBSITE property in the ListBox table? I can get this value by calling session[“WEBSITE”]. I then query my custom table that I populated earlier for details about this web site using Select with the id of the web site in the where clause. I then store these values to the properties: WEBSITE_DESCRIPTION, WEBSITE_PORT, WEBSITE_IP and WEBSITE_HEADER. These properties and where they came from will be explained later

Create a new dialog

To have the user see and select from available web sites, we need to create a dialog displaying a list box. Add a new wxs file to your project and name it SelectWebSiteDlg.wxs. Then replace any generated xml with this xml:

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Fragment>
    <CustomAction Id="UpdatePropsWithSelectedWebSite" BinaryKey="WebSiteCA" DllEntry="UpdatePropsWithSelectedWebSite" Execute="immediate" Return="check" />
    <Binary Id="WebSiteCA" SourceFile="$(var.SolutionDir)\IISCustomAction\bin\Debug\IISCustomAction.CA.dll" />
  </Fragment>
  <Fragment>
    <UI>
      <Dialog Id="SelectWebSiteDlg" Width="370" Height="270" Title="Select Web Site">
        <Control Id="Next" Type="PushButton" X="236" Y="243" Width="56" Height="17" Default="yes" Text="!(loc.WixUINext)" />
        <Control Id="Back" Type="PushButton" X="180" Y="243" Width="56" Height="17" Text="!(loc.WixUIBack)" />
        <Control Id="Cancel" Type="PushButton" X="304" Y="243" Width="56" Height="17" Cancel="yes" Text="!(loc.WixUICancel)">
          <Publish Event="SpawnDialog" Value="CancelDlg">1</Publish>
        </Control>
        <Control Id="Description" Type="Text" X="25" Y="23" Width="280" Height="15" Transparent="yes" NoPrefix="yes" Text="Please select which web site you want to install to." />
        <Control Id="Title" Type="Text" X="15" Y="6" Width="200" Height="15" Transparent="yes" NoPrefix="yes" Text="Select Web Site" />
        <Control Id="BannerBitmap" Type="Bitmap" X="0" Y="0" Width="370" Height="44" TabSkip="no" Text="!(loc.InstallDirDlgBannerBitmap)" />
        <Control Id="BannerLine" Type="Line" X="0" Y="44" Width="370" Height="0" />
        <Control Id="BottomLine" Type="Line" X="0" Y="234" Width="370" Height="0" />
        <Control Id="SelectWebSiteLabel" Type="Text" X="20" Y="60" Width="290" Height="14" NoPrefix="yes" Text="Select web site:" />
        <Control Id="SelectWebSiteCombo" Type="ListBox" X="20" Y="75" Width="200" Height="150" Property="WEBSITE" Sorted="yes" />
      </Dialog>
    </UI>
  </Fragment>
</Wix>

This xml file is separated into two fragments; one for the CA and one for the actual UI. The CA entry define in which assembly the CA is located and defines an id we can use later when calling the CA. This CA is the one I created previously for updating some properties with IIS data. The reason I’m defining it here is that I can, and it makes sense to group it with the dialog that are using it. Because, as you will see later, we’re going to call this CA after the user have clicked next on this dialog.

The UI section is where the layout of the actual UI components is defined. Most elements are default for any dialog, except SelectWebSiteLabel and SelectWebSiteCombo which is the two controls specific to the web site dialog.

I also need to update MyUI.wxs which controls which and in which order the dialogs are displayed in the wizard. I’ve added the SelectWebSiteDlg between InstallDirDlg and VerifyReadyDlg as shown here:

<Publish Dialog="InstallDirDlg" Control="Next" Event="SetTargetPath" Value="[WIXUI_INSTALLDIR]" Order="1">1</Publish>
<Publish Dialog="InstallDirDlg" Control="Next" Event="DoAction" Value="WixUIValidatePath" Order="2">1</Publish>
<Publish Dialog="InstallDirDlg" Control="Next" Event="SpawnDialog" Value="InvalidDirDlg" Order="3"><![CDATA[WIXUI_INSTALLDIR_VALID<>"1"]]></Publish>
<Publish Dialog="InstallDirDlg" Control="Next" Event="NewDialog" Value="SelectWebSiteDlg" Order="6"><![CDATA[WIXUI_INSTALLDIR_VALID="1"]]></Publish>
<Publish Dialog="InstallDirDlg" Control="ChangeFolder" Property="_BrowseProperty" Value="[WIXUI_INSTALLDIR]" Order="1">1</Publish>
<Publish Dialog="InstallDirDlg" Control="ChangeFolder" Event="SpawnDialog" Value="BrowseDlg" Order="2">1</Publish>
<Publish Dialog="SelectWebSiteDlg" Control="Next" Event="DoAction" Value="UpdatePropsWithSelectedWebSite" Order="1">1</Publish>
<Publish Dialog="SelectWebSiteDlg" Control="Next" Event="NewDialog" Value="VerifyReadyDlg" Order="2">1</Publish>
<Publish Dialog="SelectWebSiteDlg" Control="Back" Event="NewDialog" Value="InstallDirDlg" Order="1">1</Publish>
<Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="SelectWebSiteDlg" Order="1">NOT Installed</Publish>
<Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="MaintenanceTypeDlg" Order="2">Installed</Publish>

See that I use DoAction to call the CA I defined earlier? This is how you hook up a CA to the “click event” of a button (or any control for that matter). Not quite as easy as in Win Forms, but it’s still quite logical.

Also note that I’ve changed the Next event for InstallDirDlg and the Back event for VerifyReadyDlg to point to my new dialog. This so the wizard will navigate correctly when the user clicks the next and back buttons.

Changes to Product.wxs (the main WiX file)

Custom Table – Storing web site info
I promised to cover my custom table in more detail later, so here it is. First the code:

<CustomTable Id="AvailableWebSites" >
  <Column Id="WebSiteNo" Category="Identifier" PrimaryKey="yes" Type="int" Width="4" />
  <Column Id="WebSiteDescription" Category="Text" Type="string" PrimaryKey="no"/>
  <Column Id="WebSitePort" Category="Text" Type="string" PrimaryKey="no"/>
  <Column Id="WebSiteIP" Category="Text" Type="string" PrimaryKey="no" Nullable="yes"/>
  <Column Id="WebSiteHeader" Category="Text" Type="string" PrimaryKey="no" Nullable="yes"/>
  <Row>
    <Data Column="WebSiteNo">0</Data>
    <Data Column="WebSiteDescription">Bogus</Data>
    <Data Column="WebSitePort">0</Data>
    <Data Column="WebSiteIP"></Data>
    <Data Column="WebSiteHeader"></Data>
  </Row>
</CustomTable>

When a user have selected the web site to install to, instead of querying IIS for details about the web site (web site number, description, port etc), I can just get it from my AvailableWebSite table. Note that I’ve added some dummy data in the first row. Without this the custom table was not stored to the MSI and I did not find any other way of getting this to work.

Properties: Define, store and retrieve
Earlier I created a CA that stored info about the selected web site into some public properties. Where did these properties come from? Well, they’re defined in the Product.wxs file like this:

<Property Id="WEBSITE_DESCRIPTION">
  <RegistrySearch Id="WebSiteDescription"
          Name="WebSiteDescription"
          Root="HKLM"
          Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
          Type="raw" />
</Property>
<Property Id="WEBSITE_PORT">
  <RegistrySearch Id="WebSitePort"
          Name="WebSitePort"
          Root="HKLM"
          Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
          Type="raw" />
</Property>
<Property Id="WEBSITE_IP">
  <RegistrySearch Id="WebSiteIP"
          Name="WebSiteIP"
          Root="HKLM"
          Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
          Type="raw" />
</Property>
<Property Id="WEBSITE_HEADER">
  <RegistrySearch Id="WebSiteHeader"
          Name="WebSiteHeader"
          Root="HKLM"
          Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
          Type="raw" />
</Property>

I’ve also defined a registry search within each property. Why? In order to have access to these values during e.g. repair or uninstall we need to store them in the registry for later use. Why? Well, the Windows Installer does not maintain state (except from INSTALLDIR and maybe a few others). Meaning any values or selections a user did during installation is not kept for later use. Since we will need to know which web site the user installed the application to, so we can remove it on uninstall, we need to store the state to the registry. If the application has been installed before, the registry search above get’s these values from the registry and stores them in their respective properties.

But how did they end up in the registry to begin with? I do that by defining a new component like this:

<Component Id="PersistWebSiteValues" Guid="C3DAE2E2-FB49-48ba-ACB0-B2B5B726AE65">
  <RegistryKey Root="HKLM" Key="SOFTWARE\torresdal.net\SimpleWebApp\Install">
    <RegistryValue Name="WebSiteDescription" Type="string" Value="[WEBSITE_DESCRIPTION]"/>
    <RegistryValue Name="WebSitePort" Type="string" Value="[WEBSITE_PORT]"/>
    <RegistryValue Name="WebSiteIP" Type="string" Value="[WEBSITE_IP]"/>
    <RegistryValue Name="WebSiteHeader" Type="string" Value="[WEBSITE_HEADER]"/>
  </RegistryKey>
</Component>

And we need to reference the component under the Feature tag:

<ComponentRef Id="PersistWebSiteValues" />

Registry key’s in WiX require a component, which is good. That means that these keys/values will be added on install and removed on uninstall, saving us manual work. The registry key above is created at SOFTWARE\torresdal.net\SimpleWebApp\Install. The actual values are the properties as you see in the Value attributes. To reference a property just use [MY_PROPERTY]. This comes in handy many times when authoring MSI installations.

Reference CA’s
One of the CA’s (the UpdatePropsWithSelectedWebSite) is actually already referenced in the SelectWebSiteDlg, but we need to reference the GetWebSites CA as well:

<CustomAction Id="GetIISWebSites" BinaryKey="IISCA" DllEntry="GetWebSites" Execute="immediate"  Return="check" />
<Binary Id="IISCA" SourceFile="$(var.SolutionDir)IISCustomAction\bin\Debug\IISCustomAction.CA.dll" />

The CustomAction tag defines a logical entry that we can use later to call this CA by using the id GetIISWebSites. In addition there is a Binary node that tells where WiX can find this CA when build the project. The CustomAction node point to this by using the BynaryKey attribute.

Then we need to make sure it’s being called:

<InstallUISequence>
  <Custom Action="GetIISWebSites" After="CostFinalize" Overridable="yes">NOT Installed</Custom>
</InstallUISequence>

The above code tells the installer to run this CA in the UISequence only when the application is not already installed (defined by the NOT Installed condition).

Change the WebSite standard action
In order for the installer to pick up the properties we’ve set for the selected web site (description, port, ip etc) we need to change the code we had previously:

<iis:WebSite Id='DefaultWebSite' Description='Default Web Site'>
    <iis:WebAddress Id='AllUnassigned' Port='80' />
</iis:WebSite>

To this:

<iis:WebSite Id="SelectedWebSite" Description="[WEBSITE_DESCRIPTION]">
  <iis:WebAddress Id="AllUnassigned" Port="[WEBSITE_PORT]" IP="[WEBSITE_IP]" Header="[WEBSITE_HEADER]" />
</iis:WebSite>

Makes sense right? I’ve also changed the id to SelectedWebSite which is more accurate in this case, meaning you need to update the WebSite reference in WebVirtualDir in the IISAppplication component as well. If you fail to do this the WiX compiler will complain, so you’re in safe hands

The complete Product.wxs
There’s a lot of snippets above, so for your convenience I’ve included the complete code for Product.wxs here so you see everything together:

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi" xmlns:util="http://schemas.microsoft.com/wix/UtilExtension" xmlns:iis="http://schemas.microsoft.com/wix/IIsExtension">
  <Product Id="77da05c4-1644-4bc3-ac14-c0f721fe31fe" Name="Simple Web App" Language="1033" Version="1.0.0.0" Manufacturer="Jon Torresdal" UpgradeCode="a897ccc5-1c81-47e0-a837-65c07a72a7bc">
    <Package InstallerVersion="400" Compressed="yes" />
    <Media Id="1" Cabinet="WixProject1.cab" EmbedCab="yes" />
    <Property Id="TARGETVDIR" Value="SimpleWebApp"/>
    <Property Id="WEBSITE_DESCRIPTION">
      <RegistrySearch Id="WebSiteDescription"
              Name="WebSiteDescription"
              Root="HKLM"
              Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
              Type="raw" />
    </Property>
    <Property Id="WEBSITE_PORT">
      <RegistrySearch Id="WebSitePort"
              Name="WebSitePort"
              Root="HKLM"
              Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
              Type="raw" />
    </Property>
    <Property Id="WEBSITE_IP">
      <RegistrySearch Id="WebSiteIP"
              Name="WebSiteIP"
              Root="HKLM"
              Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
              Type="raw" />
    </Property>
    <Property Id="WEBSITE_HEADER">
      <RegistrySearch Id="WebSiteHeader"
              Name="WebSiteHeader"
              Root="HKLM"
              Key="SOFTWARE\torresdal.net\SimpleWebApp\Install"
              Type="raw" />
    </Property>
    <CustomAction Id="GetIISWebSites" BinaryKey="IISCA" DllEntry="GetWebSites" Execute="immediate"  Return="check" />
    <Binary Id="IISCA" SourceFile="$(var.SolutionDir)IISCustomAction\bin\Debug\IISCustomAction.CA.dll" />
    <InstallUISequence>
      <Custom Action="GetIISWebSites" After="CostFinalize" Overridable="yes">NOT Installed</Custom>
    </InstallUISequence>
    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLLOCATION" Name="SimpleWebApp">
          <Component Id="Default.aspx" Guid="fc46b1a2-35e9-4a17-896b-80b2daaae567">
            <File Id="Default.aspx" Name="Default.aspx" Source="$(var.SolutionDir)SimpleWebApp\Default.aspx" DiskId="1" KeyPath="yes" />
          </Component>
          <Component Id="Web.config" Guid="2ED81B77-F153-4003-9006-4770D789D4B6">
            <File Id="Web.config" Name="Web.config" Source="$(var.SolutionDir)SimpleWebApp\Web.config" DiskId="1" KeyPath="yes" />
            <util:XmlFile Id="AppSettingsAddNode" File="[INSTALLLOCATION]Web.config" Action="createElement" ElementPath="/configuration/appSettings" Name="add" Sequence="1" />
            <util:XmlFile Id="AppSettingsKeyAttribute" Action="setValue" File="[INSTALLLOCATION]Web.config" ElementPath="/configuration/appSettings/add" Name="key" Value="AddedDuringInstall" Sequence="2" />
            <util:XmlFile Id="AppSettingsValueAttribute" Action="setValue" File="[INSTALLLOCATION]Web.config" ElementPath="/configuration/appSettings/add" Name="value" Value="This text was added during installation." Sequence="3" />
          </Component>
          <Directory Id="binFolder" Name="bin">
            <Component Id="SimpleWebApp.dll" Guid="7FC6DA37-12E5-463d-8E7E-08F73E40CCF2">
              <File Id="SimpleWebApp.dll" Name="SimpleWebApp.dll" Source="$(var.SolutionDir)SimpleWebApp\Bin\SimpleWebApp.dll" DiskId="1" KeyPath="yes" />
            </Component>
          </Directory>
        </Directory>
      </Directory>
      <Directory Id="ProgramMenuFolder">
        <Directory Id="MyWebAppStartMenuFolder" Name="SimpleWebApp">
          <Component Id="StartMenuFolder" Guid="B3AEC4C4-3F8E-4865-B87A-B750533776B5" >
            <util:InternetShortcut Id="SimpleWebAppShortcut" Name="SimpleWebApp" Target="http://localhost/SimpleWebApp/Default.aspx" Directory="MyWebAppStartMenuFolder" />
            <RemoveFolder Id="RemoveStartMenuFolder1" On="uninstall"/>
            <RegistryKey Root="HKCU" Key="SOFTWARE\torresdal.net\SimpleWebApp\SimpleWebAppShortcut">
              <RegistryValue Type="string" Value="Default Value"/>
            </RegistryKey>
          </Component>
        </Directory>
      </Directory>
      <Component Id="IISApplication" Guid="FFA12D9C-5AEC-45f8-AA7D-5C4CEC7FA466">
        <iis:WebAppPool Id="SWAAppPool" Name="SWAAppPool" />
        <iis:WebVirtualDir Id="VirtualDir" Alias="[TARGETVDIR]" Directory="INSTALLLOCATION" WebSite="SelectedWebSite">
          <iis:WebApplication Id="SimpleWebAppApp" Name="[TARGETVDIR]" WebAppPool="SWAAppPool" />
          <iis:WebDirProperties Id="WebVirtualDirProperties" Execute="yes" Script="yes" Read="yes" WindowsAuthentication="no" AnonymousAccess="yes" IIsControlledPassword="yes" />
        </iis:WebVirtualDir>
      </Component>
      <Component Id="PersistWebSiteValues" Guid="C3DAE2E2-FB49-48ba-ACB0-B2B5B726AE65">
        <RegistryKey Root="HKLM" Key="SOFTWARE\torresdal.net\SimpleWebApp\Install">
          <RegistryValue Name="WebSiteDescription" Type="string" Value="[WEBSITE_DESCRIPTION]"/>
          <RegistryValue Name="WebSitePort" Type="string" Value="[WEBSITE_PORT]"/>
          <RegistryValue Name="WebSiteIP" Type="string" Value="[WEBSITE_IP]"/>
          <RegistryValue Name="WebSiteHeader" Type="string" Value="[WEBSITE_HEADER]"/>
        </RegistryKey>
      </Component>
    </Directory>
    <CustomTable Id="AvailableWebSites" >
      <Column Id="WebSiteNo" Category="Identifier" PrimaryKey="yes" Type="int" Width="4" />
      <Column Id="WebSiteDescription" Category="Text" Type="string" PrimaryKey="no"/>
      <Column Id="WebSitePort" Category="Text" Type="string" PrimaryKey="no"/>
      <Column Id="WebSiteIP" Category="Text" Type="string" PrimaryKey="no" Nullable="yes"/>
      <Column Id="WebSiteHeader" Category="Text" Type="string" PrimaryKey="no" Nullable="yes"/>
      <Row>
        <Data Column="WebSiteNo">0</Data>
        <Data Column="WebSiteDescription">Bogus</Data>
        <Data Column="WebSitePort">0</Data>
        <Data Column="WebSiteIP"></Data>
        <Data Column="WebSiteHeader"></Data>
      </Row>
    </CustomTable>
    <iis:WebSite Id="SelectedWebSite" Description="[WEBSITE_DESCRIPTION]">
      <iis:WebAddress Id="AllUnassigned" Port="[WEBSITE_PORT]" IP="[WEBSITE_IP]" Header="[WEBSITE_HEADER]" />
    </iis:WebSite>
    <Property Id="WIXUI_INSTALLDIR" Value="INSTALLLOCATION" />
    <UIRef Id="MyUI" />
    <Feature Id="ProductFeature" Title="SimpleWebApp" Level="1">
      <ComponentRef Id="Default.aspx" />
      <ComponentRef Id="Web.config" />
      <ComponentRef Id="SimpleWebApp.dll" />
      <ComponentRef Id="StartMenuFolder" />
      <ComponentRef Id="IISApplication" />
      <ComponentRef Id="PersistWebSiteValues" />
    </Feature>
  </Product>
</Wix>

The End! 
That’s that! If you’ve come this far you (hopefully) have a functional CA with goodies that allow your user to select web sites in your installer. Hope you found this post useful and let me know if you find any errors or questions, and I’ll help you out. Btw here’s the end result:

This is my third post in my WiX and DTF series for WiX 3.0. Here are some others I’ve written:

• An introduction
• Using WiX to author MSI installations
• Using a Custom Action to list available web sites on IIS

Normally bootstrappers are used for adding prerequisites to your installation; like the .Net Framework, Windows Installer etc. You can also use it for other purposes though. Basically it's an exe file with the msi (and any other installers) embedded. For the WiX series I'm currently doing we need this because:

1. Use as workaround for the WiX bug in IIS extension where the installer fails because of missing privileges on Vista SP1.
2. We want to do IIS custom actions in InstallUISequence which require elevated privileges which I will cover in a later post (hopefully very soon!).

I briefly mentioned InstallUISequence above. Windows Installer have several sequences, for details you can check them out here, but I'm just going to shortly explain two of them now. The InstallUISequence is the wizard part in the installer, InstallExecuteSequence is where things are happening and files are getting installed (when you click "Install" in the wizard).

Here's a bit of background. In Vista msi files does not run elevated (as admin) when you start them directly (double click on the msi). To do that you need to open an elevated command prompt and run the msi with msiexec /i yourInstaller.msi. That's not a good solution.

Normally there should be no need for admin privileges in UISequence (it's a reason it's not permitted per default), but there are exceptions, like the above. At least from my perspective. If you have a better way of solving this, I'm very interested.

So, with a bootstrapper or exe file you can do a bit more. For instance you can use mt.exe to add a manifest to he exe defining which privileges it requires to run. In this article I will describe how you can accomplish this using WiX and .Net.

Here's how to go about it:

1. Copy Setup.exe found in the WiX bin folder to your project location (so we don't modify the original)
2. Create a manifest file (e.g. Vista.manifest) in your favorite text editor by adding this xml:
   

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
     <assemblyIdentity version="1.0.0.0" processorArchitecture="X86" name="Setup" type="win32" />
     <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
       <security>
         <requestedPrivileges>
           <requestedExecutionLevel level="requireAdministrator" uiAccess="false" />
         </requestedPrivileges>
       </security>
     </trustInfo>
   </assembly>

3. Add the manifest to Setup.exe by using mt.exe found in the .Net SDK:

   mt.exe -manifest [pathToYourProject\]Vista.manifest -outputresource:[pathToYourProject\]Setup.exe;#1

4. Use setupbld.exe found in the WiX bin folder to embed the msi installer into a exe like this:

   setupbld.exe" -out Setup.exe -msu MyMsi.msi -setup Setup.exe

   or even better, add it as a post-build event (Right click your project -> Properties -> Build Event -> Post-build Event Command Line):

   "C:\Program Files\Windows Installer XML v3\bin\setupbld.exe" -out $(TargetDir)Setup.exe -msu "$(TargetPath)" -setup "$(ProjectDir)setup.exe"

The interesting thing to note about the manifest file is this:

<requestedExecutionLevel level="requireAdministrator" uiAccess="false" />

When setting the level to requireAdministrator Vista will show a UAC prompt when executing this file. The default level is asInvoker, which will run the exe with the current users privileges, but then the exe would have the same behavior as the msi.

Also note the assemblyIdentity node where you can set the actual version number of your installer and the name (if you use something else than Setup.exe).

This is my second post in my WiX and DTF series for WiX 3.0. Here are some others I’ve written:

• An introduction
• Using a bootstrapper to force elevated privileges in Vista
• Using a Custom Action to list available web sites on IIS

The source for this WiX demo can be downloaded here: SimpleWebApp.zip

PS! This demo is only tested on Windows Vista. If you have any issues on other versions of Windows, please let me know.

Update: There is a bug in the WiX extension for IIS on Vista SP 1 resulting in a install failure (Failed to read IIsWebSite table. (-2147024891)). Currently the only workaround is to run the msi from an elevated command prompt using msiexec /i nameOfInstaller.msi.
I'll post an update as soon as I find a better solution or the WiX team publish a bug fix.

Update2: You can work around the error mentioned above by using the approuch I've described here: Using a Bootstrapper To Force Elevated Privileges In Vista

The short time I've used WiX has been a joy. I feel so much more in control over the functionality and possibilities of Windows Installer than with any other tool. I have experience with both InstallShield and Wise, but there I found myself looking around in all corners of the UI and the MSI database to find the functionality I was looking for. However, without the knowledge from these two products the transition to WiX would not have been that easy.

In WiX everything is at your fingertips, even though it's XML It is however good if you have a bit of knowledge about Windows Installer and how it works. At first I was skeptical to WiX using XML, but with Visual Studio intellisense and a nice integration for e.g. build functionality, it's way better than any other xml authoring tool I've tried. Saying that, the documentation for WiX is a bit incomplete. This is especially true for WiX 3.0. However, there are other sources of documentation to WiX than their web site. There's quite a few blog posts out there, the WiX mailing list and a couple of Wiki's.

Download and install

Now down to the essence of WiX; authoring MSI installations. Before you start you need to download WiX and install. In my article I will assume you have Visual Studio installed, but you can certainly do the same things without Visual Studio, though with a bit of extra work.

After you have installed WiX you should have a few new templates in Visual Studio. I'm using VS 2008, where it looks like this:

Creating a new WiX project

1. File -> New -> Project
2. Select Project type WiX, Template WiX Project and click OK

That was that! Not too hard was it? So what do we have now?

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
    <Product Id="77da05c4-1644-4bc3-ac14-c0f721fe31fe" Name="WixProject1" Language="1033" Version="1.0.0.0" Manufacturer="WixProject1" UpgradeCode="a897ccc5-1c81-47e0-a837-65c07a72a7bc">
        <Package InstallerVersion="200" Compressed="yes" />

        <Media Id="1" Cabinet="WixProject1.cab" EmbedCab="yes" />

        <Directory Id="TARGETDIR" Name="SourceDir">
            <Directory Id="ProgramFilesFolder">
                <Directory Id="INSTALLLOCATION" Name="WixProject1">
                    <!-- TODO: Remove the comments around this Component element and the ComponentRef below in order to add resources to this installer. -->
                    <!-- <Component Id="ProductComponent" Guid="fc46b1a2-35e9-4a17-896b-80b2daaae567"> -->
                        <!-- TODO: Insert files, registry keys, and other resources here. -->
                    <!-- </Component> -->
                </Directory>
            </Directory>
        </Directory>

        <Feature Id="ProductFeature" Title="WixProject1" Level="1">
            <!-- TODO: Remove the comments around this ComponentRef element and the Component above in order to add resources to this installer. -->
            <!-- <ComponentRef Id="ProductComponent" /> -->
        </Feature>
    </Product>
</Wix>

We have an installation definition that can generate an msi that does nothing! Let's modify it to do something useful...

Adding installer UI

By default WiX uses the simplest installer UI possible, meaning none but the default shown by Windows Installer. This means if you want your users to interact with your installation, you need to customize it a bit. WiX comes with the following built-in dialog sets that will make this easy:

• WixUI_Mondo
• WixUI_FeatureTree
• WixUI_InstallDir
• WixUI_Minimal
• WixUI_Advanced

While creating the installer I will try to follow best practices for Windows Installer, have it work with Vista and Server 2008, and make it pass the Certified for Windows Vista test cases. That means we need to allow the user to select which folder she wants the application installed to. Which one of the above can help us out with that? You guessed it; WixUI_InstallDir.

1. Add a reference to WixUIExtension.dll (right click project -> Add referece...)
2. Add these two lines between the Directory and Feature tags in your Product.wxs file:

        <Property Id="WIXUI_INSTALLDIR" Value="INSTALLLOCATION" />
        <UIRef Id="WixUI_InstallDir" />

The property WIXUI_INSTALLDIR must be set for the UI to know which directory to use as default. Here I set it to INSTALLLOCATION which is the Id of the directory where the application is being installed. The UIRef tag allow us to reference an external package of UI's. In this case the WixUI_InstallDir in the WixUIExtension library.

Changing the installer UI

In this section we're going to remove the license agreement dialog from the UI and change the graphics displayed in the Windows Installer wizard.

WixUI_InstallDir actually includes several dialogs. Among others the license agreement dialog and the install dir dialog. For my installer I don't want the license agreement, so how do I remove it?

The easiest way is to download the WiX source and get the wxs file for WixUI InstallDir and make it your own (before you think this is too cumbersome, try it. It's actually quite fast and simple, and you learn a thing or two by looking at the source files) :

1. Right click your WiX project -> Add -> New Item...
2. Select WiX File and give it a name (e.g. MyUI.wxs)
3. In a text editor, open the file WixUI_InstallDir.wxs found (in the version I'm using) here: ...Wix-3.0.4318.0-sources\src\ext\UIExtension\wixlib
4. Copy the xml
5. Paste it into your new WiX file (MyUI.wxs)
6. Comment out the license agreement dialogs (see source below)
7. Change the navigation targets for Next and Back buttons for WelcomeDlg and InstallDirDlg to not use LicenseAgreementDlg anymore (see source below)

The next thing I want to do is change the welcome screen and the top banner of the installation with my own graphics. Here's how:

1. Add a new folder to your vs project and name it Images
2. Create two images (if you don't want to create your own, you can download mine by clicking on links for the images)
   1. msibanner.jpg (493x58)
   2. msiwelcome.jpg (493x312)
3. Copy your images to the Images folder
4. Next add the two lines below to your UI file (MyUI.wxs) just below the Fragment node to have the installation use the new images:

        <WixVariable Id="WixUIBannerBmp" Value="Images\msibanner.jpg" />
        <WixVariable Id="WixUIDialogBmp" Value="Images\msiwelcome.jpg" />

Here's the MyUI.wxs file after the changes:

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
    <Fragment>
        <WixVariable Id="WixUIBannerBmp" Value="Images\msibanner.jpg" />
        <WixVariable Id="WixUIDialogBmp" Value="Images\msiwelcome.jpg" />
        
        <UI Id="MyUI">
            <TextStyle Id="WixUI_Font_Normal" FaceName="Tahoma" Size="8" />
            <TextStyle Id="WixUI_Font_Bigger" FaceName="Tahoma" Size="12" />
            <TextStyle Id="WixUI_Font_Title" FaceName="Tahoma" Size="9" Bold="yes" />

            <Property Id="DefaultUIFont" Value="WixUI_Font_Normal" />
            <Property Id="WixUI_Mode" Value="InstallDir" />

            <DialogRef Id="BrowseDlg" />
            <DialogRef Id="DiskCostDlg" />
            <DialogRef Id="ErrorDlg" />
            <DialogRef Id="FatalError" />
            <DialogRef Id="FilesInUse" />
            <DialogRef Id="MsiRMFilesInUse" />
            <DialogRef Id="PrepareDlg" />
            <DialogRef Id="ProgressDlg" />
            <DialogRef Id="ResumeDlg" />
            <DialogRef Id="UserExit" />

            <Publish Dialog="BrowseDlg" Control="OK" Event="DoAction" Value="WixUIValidatePath" Order="3">1</Publish>
            <Publish Dialog="BrowseDlg" Control="OK" Event="SpawnDialog" Value="InvalidDirDlg" Order="4"><![CDATA[WIXUI_INSTALLDIR_VALID<>"1"]]></Publish>

            <Publish Dialog="ExitDialog" Control="Finish" Event="EndDialog" Value="Return" Order="999">1</Publish>

            <!-- Changed WelcomeDlg next button to navigate to InstallDirDlg-->
            <!--<Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>-->
            <Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="InstallDirDlg">1</Publish>

            <!-- Removed LicenseAgreementDlg -->
            <!--
            <Publish Dialog="LicenseAgreementDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>
            <Publish Dialog="LicenseAgreementDlg" Control="Next" Event="NewDialog" Value="InstallDirDlg">LicenseAccepted = "1"</Publish>
            -->

            <!-- Changed InstallDirDlg back button to navigate to WelcomeDlg -->
            <!--<Publish Dialog="InstallDirDlg" Control="Back" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>-->
            <Publish Dialog="InstallDirDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>
            
            <Publish Dialog="InstallDirDlg" Control="Next" Event="SetTargetPath" Value="[WIXUI_INSTALLDIR]" Order="1">1</Publish>
            <Publish Dialog="InstallDirDlg" Control="Next" Event="DoAction" Value="WixUIValidatePath" Order="2">1</Publish>
            <Publish Dialog="InstallDirDlg" Control="Next" Event="SpawnDialog" Value="InvalidDirDlg" Order="3"><![CDATA[WIXUI_INSTALLDIR_VALID<>"1"]]></Publish>
            <Publish Dialog="InstallDirDlg" Control="Next" Event="NewDialog" Value="VerifyReadyDlg" Order="4"><![CDATA[WIXUI_INSTALLDIR_VALID="1"]]></Publish>
            <Publish Dialog="InstallDirDlg" Control="ChangeFolder" Property="_BrowseProperty" Value="[WIXUI_INSTALLDIR]" Order="1">1</Publish>
            <Publish Dialog="InstallDirDlg" Control="ChangeFolder" Event="SpawnDialog" Value="BrowseDlg" Order="2">1</Publish>

            <Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="InstallDirDlg" Order="1">NOT Installed</Publish>
            <Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="MaintenanceTypeDlg" Order="2">Installed</Publish>

            <Publish Dialog="MaintenanceWelcomeDlg" Control="Next" Event="NewDialog" Value="MaintenanceTypeDlg">1</Publish>

            <Publish Dialog="MaintenanceTypeDlg" Control="RepairButton" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
            <Publish Dialog="MaintenanceTypeDlg" Control="RemoveButton" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
            <Publish Dialog="MaintenanceTypeDlg" Control="Back" Event="NewDialog" Value="MaintenanceWelcomeDlg">1</Publish>

            <Property Id="ARPNOMODIFY" Value="1" />
        </UI>

        <UIRef Id="WixUI_Common" />
    </Fragment>
</Wix>

If you now build your project you can see how the new installer looks like by running the MSI file which you'll find in the debug folder of your project.

Adding files, folders, shortcuts and changing Web.config

A nice UI for the installer is all good, but without installing anything useful it's not much point is it? So let's add some files.

Adding files
Since I'm later going to demo how to select which web site to install to (by using a custom action), it's natural that we're going to install a web application. I've created a very simple web app that has three files: Default.aspx, Web.config and SimpleWebApp.dll. So let's add them to the installation by changing Product.wxs:

Add directories, components, files and feature ref's as shown below:

<Directory Id="TARGETDIR" Name="SourceDir">
    <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLLOCATION" Name="SimpleWebApp">
            <Component Id="Default.aspx" Guid="fc46b1a2-35e9-4a17-896b-80b2daaae567">
                <File Id="Default.aspx" Name="Default.aspx" Source="$(var.SolutionDir)SimpleWebApp\Default.aspx" DiskId="1" KeyPath="yes" />
            </Component>
            <Component Id="Web.config" Guid="2ED81B77-F153-4003-9006-4770D789D4B6">
                <File Id="Web.config" Name="Web.config" Source="$(var.SolutionDir)SimpleWebApp\Web.config" DiskId="1" KeyPath="yes" />
            </Component>
            <Directory Id="binFolder" Name="bin">
                <Component Id="SimpleWebApp.dll" Guid="7FC6DA37-12E5-463d-8E7E-08F73E40CCF2">
                    <File Id="SimpleWebApp.dll" Name="SimpleWebApp.dll" Source="$(var.SolutionDir)SimpleWebApp\Bin\SimpleWebApp.dll" DiskId="1" KeyPath="yes" />
                </Component>
            </Directory>
        </Directory>
    </Directory>
</Directory>
...
<Feature Id="ProductFeature" Title="SimpleWebApp" Level="1">
    <ComponentRef Id="Default.aspx" />
    <ComponentRef Id="Web.config" />
    <ComponentRef Id="SimpleWebApp.dll" />
</Feature>

One thing to note in is the use of $(var.SolutionDir) in the Source attribute. This is a reference to a Visual Studio variable. In this case the path for the solution directory.

Adding a shortcut
Now let's add a shortcut to the start menu. To do this we need a reference to another WiX component: WixUtilExtension. To get intellisense in VS add the following xml namespace to the Wix node:

xmlns:util="http://schemas.microsoft.com/wix/UtilExtension"

And then add this xml:

<Directory Id="TARGETDIR" Name="SourceDir">
...
    <Directory Id="ProgramMenuFolder">
        <Directory Id="MyWebAppStartMenuFolder" Name="SimpleWebApp">
            <Component Id="StartMenuFolder" Guid="B3AEC4C4-3F8E-4865-B87A-B750533776B5" >
                <util:InternetShortcut Id="SimpleWebAppShortcut" Name="SimpleWebApp" Target="http://localhost/SimpleWebApp/Default.aspx" Directory="MyWebAppStartMenuFolder" />
                <RemoveFolder Id="RemoveStartMenuFolder1" On="uninstall"/>
                <RegistryKey Root="HKCU" Key="SOFTWARE\torresdal.net\SimpleWebApp\SimpleWebAppShortcut">
                    <RegistryValue Type="string" Value="Default Value"/>
                </RegistryKey>
            </Component>
        </Directory>
    </Directory>
</Directory>

The directory ProgramMenuFolder is a standard directory id for the program menu folder. Under that folder we add another folder for our application; the SimpleWebApp. To add the actual shortcut we need a component. In this component we define the shortcut by using util:InternetShorcut. In addition to this we must make sure to remove the SimpleWebApp folder un uninstall done by using the RemoveFolder action. And last we need to associate the component with a key. Usually components automatically links to a file for its key, but since there is no file here we must provide a registry key instead. This is done using the RegistryKey and RegistryValue actions.

And since we've created a new component we need to add that to the feature:

<ComponentRef Id="StartMenuFolder" />

Changing Web.config
Now let's do some changes to Web.config during installation. Under the component for Web.config add this xml that will add an element to appSettings in the config file:

<util:XmlFile Id="AppSettingsAddNode" File="[INSTALLLOCATION]Web.config" Action="createElement" ElementPath="/configuration/appSettings" Name="add" Sequence="1" />
<util:XmlFile Id="AppSettingsKeyAttribute" Action="setValue" File="[INSTALLLOCATION]Web.config" ElementPath="/configuration/appSettings/add" Name="key" Value="AddedDuringInstall" Sequence="2" />
<util:XmlFile Id="AppSettingsValueAttribute" Action="setValue" File="[INSTALLLOCATION]Web.config" ElementPath="/configuration/appSettings/add" Name="value" Value="This text was added during installation." Sequence="3" />

The first line will add the 'add' node below the appSettings node. The second line will add the 'key' attribute and the third line will add the 'value' attribute. WiX also provide a util called XmlConfig which is suppose to be customized for .Net config files. However, I was unable to get it to work as expected. Please let me know if you find out how to use XmlConfig instead.

Adding the web application to IIS

To work with IIS, WiX has another extension we can use; the IISExtension. Add the reference and define the xml namespace:

xmlns:iis="http://schemas.microsoft.com/wix/IIsExtension"

Then add the following xml under the root directory TARGETDIR:

<Component Id="IISApplication" Guid="FFA12D9C-5AEC-45f8-AA7D-5C4CEC7FA466">
    <iis:WebAppPool Id="SWAAppPool" Name="SWAAppPool" />
    <iis:WebVirtualDir Id="VirtualDir" Alias="[TARGETVDIR]" Directory="INSTALLLOCATION" WebSite="DefaultWebSite">
        <iis:WebApplication Id="SimpleWebAppApp" Name="[TARGETVDIR]" WebAppPool="SWAAppPool" />
        <iis:WebDirProperties Id="WebVirtualDirProperties" Execute="yes" Script="yes" Read="yes" WindowsAuthentication="no" AnonymousAccess="yes" IIsControlledPassword="yes" />
    </iis:WebVirtualDir>
</Component>

And also since this is a new component, we need to add it to the feature:

<ComponentRef Id="IISApplication" />

We also need to define the default web site which the virtual directory is pointing to:

<iis:WebSite Id='DefaultWebSite' Description='Default Web Site'>
    <iis:WebAddress Id='AllUnassigned' Port='80' />
</iis:WebSite>

The iis:WebAppPool will add a new application pool for this web application. This is strictly not necessary, but I like my web apps to run in its own app pool so I can recycle only that web app without affecting other apps. iis:WebVirtualDir adds a virtual directory to IIS under Default Web Site. In addition to this (since we have an asp.net app) we want to define a web application by using iis:WebApplication. This is set up to use the application pool defined earlier. And the last item is the properties for the virtual directory defined by iis:WebDirProperties. For further details about these items, have a look at the schema reference found in the WiX documentation.

Giving the installer a proper name

To have the installer to use Simple Web App as the product name and not WixProject1, change the Name attribute of the Product node like this:

<Product Id="77da05c4-1644-4bc3-ac14-c0f721fe31fe" Name="Simple Web App" Language="1033" Version="1.0.0.0" Manufacturer="Jon Torresdal" UpgradeCode="a897ccc5-1c81-47e0-a837-65c07a72a7bc">

And also if you want a different name of the msi you can changed that on the properties page of the WiX project. Just set the output name to something else.

The complete source

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi" xmlns:util="http://schemas.microsoft.com/wix/UtilExtension" xmlns:iis="http://schemas.microsoft.com/wix/IIsExtension">
    <Product Id="77da05c4-1644-4bc3-ac14-c0f721fe31fe" Name="Simple Web App" Language="1033" Version="1.0.0.0" Manufacturer="Jon Torresdal" UpgradeCode="a897ccc5-1c81-47e0-a837-65c07a72a7bc">
        <Package InstallerVersion="200" Compressed="yes" />

        <Media Id="1" Cabinet="WixProject1.cab" EmbedCab="yes" />
        <Property Id="TARGETVDIR" Value="SimpleWebApp"/>
        
        <Directory Id="TARGETDIR" Name="SourceDir">
            <Directory Id="ProgramFilesFolder">
                <Directory Id="INSTALLLOCATION" Name="SimpleWebApp">
                    <Component Id="Default.aspx" Guid="fc46b1a2-35e9-4a17-896b-80b2daaae567">
                        <File Id="Default.aspx" Name="Default.aspx" Source="$(var.SolutionDir)SimpleWebApp\Default.aspx" DiskId="1" KeyPath="yes" />
                    </Component>
                    <Component Id="Web.config" Guid="2ED81B77-F153-4003-9006-4770D789D4B6">
                        <File Id="Web.config" Name="Web.config" Source="$(var.SolutionDir)SimpleWebApp\Web.config" DiskId="1" KeyPath="yes" />
                        <util:XmlFile Id="AppSettingsAddNode" File="[INSTALLLOCATION]Web.config" Action="createElement" ElementPath="/configuration/appSettings" Name="add" Sequence="1" />
                        <util:XmlFile Id="AppSettingsKeyAttribute" Action="setValue" File="[INSTALLLOCATION]Web.config" ElementPath="/configuration/appSettings/add" Name="key" Value="AddedDuringInstall" Sequence="2" />
                        <util:XmlFile Id="AppSettingsValueAttribute" Action="setValue" File="[INSTALLLOCATION]Web.config" ElementPath="/configuration/appSettings/add" Name="value" Value="This text was added during installation." Sequence="3" />
                    </Component>
                    <Directory Id="binFolder" Name="bin">
                        <Component Id="SimpleWebApp.dll" Guid="7FC6DA37-12E5-463d-8E7E-08F73E40CCF2">
                            <File Id="SimpleWebApp.dll" Name="SimpleWebApp.dll" Source="$(var.SolutionDir)SimpleWebApp\Bin\SimpleWebApp.dll" DiskId="1" KeyPath="yes" />
                        </Component>
                    </Directory>
                </Directory>
            </Directory>
            <Directory Id="ProgramMenuFolder">
                <Directory Id="MyWebAppStartMenuFolder" Name="SimpleWebApp">
                    <Component Id="StartMenuFolder" Guid="B3AEC4C4-3F8E-4865-B87A-B750533776B5" >
                        <util:InternetShortcut Id="SimpleWebAppShortcut" Name="SimpleWebApp" Target="http://localhost/SimpleWebApp/Default.aspx" Directory="MyWebAppStartMenuFolder" />
                        <RemoveFolder Id="RemoveStartMenuFolder1" On="uninstall"/>
                        <RegistryKey Root="HKCU" Key="SOFTWARE\torresdal.net\SimpleWebApp\SimpleWebAppShortcut">
                            <RegistryValue Type="string" Value="Default Value"/>
                        </RegistryKey>
                    </Component>
                </Directory>
            </Directory>
            <Component Id="IISApplication" Guid="FFA12D9C-5AEC-45f8-AA7D-5C4CEC7FA466">
                <iis:WebAppPool Id="SWAAppPool" Name="SWAAppPool" />
                <iis:WebVirtualDir Id="VirtualDir" Alias="[TARGETVDIR]" Directory="INSTALLLOCATION" WebSite="DefaultWebSite">
                    <iis:WebApplication Id="SimpleWebAppApp" Name="[TARGETVDIR]" WebAppPool="SWAAppPool" />
                    <iis:WebDirProperties Id="WebVirtualDirProperties" Execute="yes" Script="yes" Read="yes" WindowsAuthentication="no" AnonymousAccess="yes" IIsControlledPassword="yes" />
                </iis:WebVirtualDir>
            </Component>
        </Directory>

        <iis:WebSite Id='DefaultWebSite' Description='Default Web Site'>
            <iis:WebAddress Id='AllUnassigned' Port='80' />
        </iis:WebSite>

        <Property Id="WIXUI_INSTALLDIR" Value="INSTALLLOCATION" />
        <UIRef Id="MyUI" />

        <Feature Id="ProductFeature" Title="SimpleWebApp" Level="1">
            <ComponentRef Id="Default.aspx" />
            <ComponentRef Id="Web.config" />
            <ComponentRef Id="SimpleWebApp.dll" />
            <ComponentRef Id="StartMenuFolder" />
            <ComponentRef Id="IISApplication" />
        </Feature>
    </Product>
</Wix>

Build and install

That's it! Now lets build the project and install the application.

This is my first post in my WiX and DTF series for WiX 3.0. Here are some others I’ve written:

• Using WiX to author MSI installations
• Using a bootstrapper to force elevated privileges in Vista
• Using a Custom Action to list available web sites on IIS

Windows Installer XML (WiX)

The version of WiX I'm going to talk about is v.3.0, currently in beta. In essence WiX is an XML format for writing MSI deployment packages. Much like using InstallShield or Wise to write your installations, you can use WiX to do the same. So why do you want to use XML to author your msi's? At first I thought: "Ohhh no! Not another XML based authoring tool!" But after doing some more digging, this is one of the scenarios were XML makes sense... kind of. Here's the benefits I see with WiX compared to traditional MSI tools:

• It's perfect for "code" generation, using Nant, TFS etc.
• WiX is very clean, so it gives you the possibility to author exactly what you need and not have all the general stuff that IS and Wise has pre added to your installation

Another thing to note is that WiX is open source and it comes from Microsoft (yea, Microsoft HAVE open source projects). Not only that, but this tool got so popular within Microsoft that most of their packages are now moving towards using WiX, and many of them, like Office, already use WiX. That says a lot!

I'll get back to using WiX to author msi installations in a later post, but now I want to focus on DTF and how to use it without WiX.

Deployment Tools Foundation (DTF)

DTF is among other things a managed (.net) wrapper on top of msi.dll (the windows installer library). DTF makes it possible to write custom actions (CA's) for MSI installations in C#, VB.net or any other .Net language. If you're not used to working with MSI installations this might not be a big deal for you, but for me this is fantastic news! Not only that, debugging has now become much easier (or should i say possible).

Before you only had three options for writing CA's: C++, VB Script and Java Script. CA's are custom code you write because there are currently no existing action supported by MS Installer that does what you're looking for.

Examples of things you can do with Windows Installer out of the box are:

• Install/delete/move files
• Create/delete/change folders
• Create/delete/change shortcuts
• Install/remove/start/stop Windows Services
• Reboots
• Install/remove ODBC drivers
• Register/un-register COM/COM+ applications
• Register/un-register fonts
• Write/change registry
• ...and so on...

Check this out for a more complete list.

However, Windows Installer can't cover all scenarios, so then you turn to CA's. Here are some examples I've used CA's for:

• List SQL Servers
• List IIS Web Sites
• Create Web Sites and Virtual Directories
• Change XML files

You should however know this; writing good CA's is difficult and there is a lot of things to take into account. For instance, what happens if your installation fails and starts rolling back? Then you need to make sure that any changes you've done to the system with your CA also needs to roll back, meaning you have to have two CA's, one for adding stuff and one for removing stuff.

Why not just stick to VB/Java script?

Using VB and Java scripts has become more and more difficult because of security restrictions, virus programs etc. Many virus programs will not allow you to use Windows Scripting Host (WSH) at all.

About 2 months ago I did some work on our existing msi packages related to a Microsoft certification program. The requirements for this certification forced me to adopt the best practices that I should have done a long time ago. To avoid the problem with scripting I had two options. Rewrite my CA's in C++, or in C# using DTF. After digging around it was an easy choice. I went for managed code.

However, this might not be the right solution for you. Managed code require the .Net framework, so if you don't know if .Net is present on the computer running your software, you might want to stick to "traditional" CA's. For me this was not a problem, since all computers (clients and servers) we install on already have .Net pre-installed.

Next

Next time I'll show you how to create a CA for listing available IIS Web Sites on IIS7. This will allow you to choose which web site to install your application under. Until then I suggest you check out WiX/DTF and start thinking if this is something for you.