Jerry Dennany's Occasional Clue

One more complaint about Windows Installer DLL Custom Actions.  If an entry point is not found, then Windows Installer generates a generic error, 1723.  This is pretty much the same error for any problem running the DLL.  As it's pretty simple for the Windows Installer team to know if the dll entry point wasn't found, why couldn't they generate a more explicit error message, or even log more detailed information in the MSI log?

It's quite obvious that Windows Installer was designed for internal product team by Microsoft, and then later released for general use.  Who actually makes their HANDLE a typedef for an unsigned long?  Windows Installer's MSIHANDLE, that's who.

Ugh.

This is more of a Windows Installer complaint, but since WiX and Windows Installer are so closely linked, I feel justified making these comments.

The mechanism that Windows Installer uses to call custom actions is convoluted, at best.  A DLL embedded into an MSI is extracted at runtime to the %TEMP% directory, and dyamically renamed to a named format, "MSI???.tmp", where the string '???' is psuedo-randomly generated (There may be a pattern, but I haven't spent the time to figure it out.)

Why do I care?  Well, I attempted to write an embedded DLL that used Managed Code.  Specifically, I used C++ for the Windows Installer entry points, and then generated a c# module.  This worked perfectly for my nUnit test suite, but my instalation kept failing when I tried this from Windows Installer.  After quite some time debugging, I finally examined the fusion assembly binding logs. I discovered that even though the module is embedded in the same PE file as the original calling assembly, the .NET framework first looks for a '.module' file external to the existing assembly.  If it fails to find that '.module', it then examines itself to find the referenced .net module.  However, a small 'feature' is that it does this by looking for it's own original assembly name. The problem I experienced is that Windows Installer has renamed my assembly to the MSI???.tmp name, so I would get assembly/module load issues.

So, that went down the drain. As I am relatively C++ averse (especially Managed C++, though C++/CLI is supposed to rescue me from the ugliness that is MC++), I really preferred to write my CAs in C#.

My solution was to write an external assembly that I install into the GAC.  Now, my c++ "interop" layer can always find the C# custom actions, as they are globally installed.  That does leave me with a chicken and egg problem, though.  How do I get my c# custom actions into the GAC before I call them?  After all, I must have them available during my UI sequence, and I can't wait until intallation time for my CA's to be present.

I followed the same solution that InstallShield uses for there "InstallSheild Engine", idriver.exe.  I wrote a mini-install to place my c# assembly into the GAC, and perform this installation at the beginning of my 'main' installer.

This is a lot of effort to get around the fact that the Windows Installer team hasn't really considered managed custom actions, although the user groups are teaming with such requests. Even though all future versions of the operating system will guarantee a managed framework, the WI team still insists on C++ as the custom code 'story' for windows installations.  (Please don't tell me that Windows Installer supports vbscript.  We all know this.  We also should know that vbscript is very, very bad in installation situations).

So, a long story short - managed CAs are possible, but not easy.  I'll post more on my Managed CA adventure soon.

Despite the lack of blog posts, I've really been immersed in WiX.  I'm learning to love and hate this project.  I really love the XML declarative style of creating MSIs.  I really hate the fact that WiX wraps the abomination known as Windows installer. 

I was very familiar with Windows Installer before this adventure. I've spent years working with both InstallShield and Wise, and have had to edit raw MSI tables many times in the past.  However, these commercial products do a much better job of hiding the complexities of Windows Installer than WiX does.  If you decide to adopt WiX, make certain that you have the time to invest in learning the ins and outs of the MSI SDK.  Even if you think that you know quite a bit in this area, be prepared to spend some time spelunking through MSI.chm.

Writing Custom Actions using WiX isn't a walk in the park, either.  I'll talk a bit about managed CAs a bit in the future.  Hopefully people will learn from my trials and tribulations in this area.

Just to make sure that this blog entry has some substance, I'm going to give my WiX UI tip of the day:

To define the default font, place the following in the <UI/> section:

<UI>
  <Property Id="DefaultUIFont">Tahoma8</Property>
  <TextStyle Id="Tahoma8" FaceName="Tahoma" Size="8" />  
  <!-- rest of UI (dialogs, etc) go here. -->
<UI>

WiX has a Visual Studio Plugin codename 'Votive'.  This project enables you to edit WiX scripts from within the Visual Studio IDE.  It's rather convenient to click "Build" from within Visual Studio.  The best part of Votive is that you don't need to author build scripts to get an .msi file from WiX.  Just build the project, and you are on your way.

That's the good part of Votive.  However, I'm finding that it's not really stable enough to use in day-to-day developement.  In the first several hours of use, I spent most of my time being the good open source citizen, reproducing bugs and filing associated bug reports with the WiX project.  I soon discovered that if I continued down this path, I'd probably spend more time doing Votive QA than I would installation development.  That same day, I dropped using the Visual Studio plugin.

I stil edit WiX scripts with Visual Studio - I even created a C# project that houses both my WiX scripts and my managed custom actions.  I can still get intellisense for the WiX schema.  I'm really only missing a 'build' button.  I think I'll sacrifice that little feature to maintain my sanity.

Please note that Votive is still considered an "Alpha" component of WiX.  It will certainly improve over time.  I'm using build 2.0.2912.0.  I would encourage you to evaluate the plugin yourself in the near future.

As promised, here is my article:

"How To extract InstallShield Dialogs from an MSI"

First, we need our installation generated from a properly licenced copy of InstallShield.

In this case, our msi is called setup.msi.

With our copy of WiX 2.0.2912.0 installed and in the PATH, we run the following command against our setup.msi:

This will generate a WiX setup file named setup.wsx.  This file will contain the reverse-generated WiX code from our setup.msi file.

If we open the setup.wsx in our favorite XML editor, we should look for the following string:

This will mark the beginning of the first dialog that we are interested in, the InstallWelcome dialog.  The

complete dialog is presented here:

The first line:
<Dialog Id="InstallWelcome" Width="374" Height="266" Title="[ProductName] - InstallShield Wizard" NoMinimize="yes">

This line is pretty self explanatory.  The Dialog Id is used to reference this dialog elswhere in the WiX setup. 

If you are like me, you'll want to remove the InstallShield string reference. 

The next several lines are Control Id's.  In this simple dialog, we only have the Next, Cancel, and Back buttons,

followed by the text controls for Copyright, and InstallShield TagLines.  We also have a Dialog Line for

appearance, along with the background bitmap.  We close with one last Text control.

Note that for most of the controls, things are pretty straightforward, with a declarative UI model.  However, the

Next button has an additional bit of XML that is of considerable importance:


<Publish Event="NewDialog" Value="LicenseAgreement"><![CDATA[1]]></Publish>

The Controls may publish several events, but for the purpose of the article we are only interested in the "SpawnDialog" event.

Let's break this down a little further:

<Publish Event="NewDialog"

This is the action to be taken if the "Next" button is pushed.

Value="LicenseAgreement"

This is the 'argument' for this action.  In the case of the NewDialog event, the argument is the name of the next screen to display.

<![CDATA[1]]>

This is the 'condition' under which this dialog should be executed.  This is blocked out into a !CDATA section, as

conditions often contain XML control characters like '<' or '>'.  A condition of '1' means 'true' or always.  A condition of '0' means never.  We may also use Windows Installer Properties instead of constants. Properties are similar to global variables, as explained in the MSDN MSI documentation.

</Publish>

Of course, we need to close the tag.

That's a quick breakdown of the dialog.  Let's embed this dialog in our first WiX script.  First, we'll view a simple script without UI:

<?xml version='1.0'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2003/01/wi'>
<!-- really, follow the advice here - this GUID is invalid - generate your own! -->
   <Product Id='INVALID_GUID-0000-0000-C000-000000000001' Name='My Product Name' Language='1033' Version='1.0.0.0'

Manufacturer='My Company'>
      <Package Id='INVALID_GUID-1234-0000-ABCD-000000000003' Description='My Setup' InstallerVersion='200'

Compressed='yes' />
      <Media Id='1' Cabinet='product.cab' EmbedCab='yes' />

      <Directory Id='TARGETDIR' Name='SourceDir'>
         <Directory Id='ProgramFilesFolder' Name='PFiles'>
            <Directory Id='MyCompany' Name='MCompany' LongName='My Company'>
               <Component Id='MyProductComponent' Guid='INVALID_GUID-374A-0000-EFAC-000000000067'>
<!-- Note: This is just an example - you wouldn't really link to a file in your system dir -->          
       <File Id='MyFile' Name='notepad.exe' KeyPath='yes' DiskId='1' src='C:\Windows\System32\notepad.exe'/>
               </Component>
            </Directory>
         </Directory>
      </Directory>

      <Feature Id='MyProductFeature' Title='My Product Feature' Level='1'>
         <ComponentRef Id='MyProductComponent' />
      </Feature>
   </Product>
</Wix>

This script would install notepad.exe into C:\Program Files\My Company\notepad.exe.  Please note that you must generate your own GUIDs for this script to compile.

For more explanation of this simple WiX script, please visit the WiX tutorial page at

http://www.tramontana.co.hu/wix/.

This script doesn't have a UI.  We'll add the Install Welcome screen we previously extracted from our InstallShield setup.

<?xml version='1.0'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2003/01/wi'>
<!-- really, follow the advice here - this GUID is invalid - generate your own! -->
   <Product Id='INVALID_GUID-0000-0000-C000-000000000001' Name='My Product Name' Language='1033' Version='1.0.0.0'

Manufacturer='My Company'>
      <Package Id='INVALID_GUID-1234-0000-ABCD-000000000003' Description='My Setup' InstallerVersion='200'

Compressed='yes' />
      <Media Id='1' Cabinet='product.cab' EmbedCab='yes' />

      <Directory Id='TARGETDIR' Name='SourceDir'>
         <Directory Id='ProgramFilesFolder' Name='PFiles'>
            <Directory Id='MyCompany' Name='MCompany' LongName='My Company'>
               <Component Id='MyProductComponent' Guid='INVALID_GUID-374A-0000-EFAC-000000000067'>
<!-- Note: This is just an example - you wouldn't really link to a file in your system dir -->          
       <File Id='MyFile' Name='notepad.exe' KeyPath='yes' DiskId='1' src='C:\Windows\System32\notepad.exe'/>
               </Component>
            </Directory>
         </Directory>
      </Directory>

      <Feature Id='MyProductFeature' Title='My Product Feature' Level='1'>
         <ComponentRef Id='MyProductComponent' />
      </Feature>
        <UI>
             
            <InstallUISequence>
   <Show Dialog="InstallWelcome" After="CostFinalize"><![CDATA[Not Installed And (Not PATCH Or

IS_MAJOR_UPGRADE)]]></Show>                
            </InstallUISequence>

<Dialog Id="InstallWelcome" Width="374" Height="266" Title="[ProductName] - InstallShield Wizard"

NoMinimize="yes">
        <Control Id="Next" Type="PushButton" X="230" Y="243" Width="66" Height="17" Default="yes" Text="&amp;Next

&gt;">
          <Publish Event="NewDialog" Value="LicenseAgreement"><![CDATA[1]]></Publish>
        </Control>
        <Control Id="Cancel" Type="PushButton" X="301" Y="243" Width="66" Height="17" Cancel="yes" Text="Cancel">
          <Publish Event="SpawnDialog" Value="CancelSetup"><![CDATA[1]]></Publish>
        </Control>
        <Control Id="Back" Type="PushButton" X="164" Y="243" Width="66" Height="17" Disabled="yes" Text="&lt;

&amp;Back">
          <Publish Event="NewDialog" Value="SplashBitmap"><![CDATA[Display_IsBitmapDlg]]></Publish>
        </Control>
        <Control Id="Copyright" Type="Text" X="135" Y="144" Width="228" Height="73" Transparent="yes"

TabSkip="no">
          <Text>WARNING: This program is protected by copyright law and international treaties.</Text>
          <Condition Action="hide"><![CDATA[SHOWCOPYRIGHT="No"]]></Condition>
          <Condition Action="show"><![CDATA[SHOWCOPYRIGHT="Yes"]]></Condition>
        </Control>
        <Control Id="TextLine2" Type="Text" X="135" Y="55" Width="228" Height="45" Transparent="yes">
          <Text>The InstallShield(R) Wizard will install [ProductName] on your computer. To continue, click

Next.</Text>
        </Control>
        <Control Id="DlgLine" Type="Line" X="0" Y="234" Width="374" Height="0" />
        <Control Id="Image" Type="Bitmap" X="0" Y="0" Width="374" Height="234" Text="NewBinary5" />
        <Control Id="TextLine1" Type="Text" X="135" Y="8" Width="225" Height="45" Transparent="yes">
          <Text>{&amp;TahomaBold10}Welcome to the InstallShield Wizard for [ProductName]</Text>
        </Control>
      </Dialog>
        </UI>
   </Product>
</Wix>

The important thing to note is that our previous <Dialog> section is now placed within the new <UI> section of the setup XML.  We've also added an <InstallUISequence> in this same <UI> section.

The InstallUISequence tells the Windows Installer what order to run the UI elements in.  There are additional sections, such as the AdminUISequence, but we won't be covering that here.  They aren't required for a simple installation.

If we change our GUIDS to valid GUIDS, and save the file to the name Product.wxs, we may attempt to generate our MSI file by running:

candle.exe product.wxs
light.exe product.wixobj

We get an error:

C:\temp\Product.wixobj : fatal error LGHT0028: Unresolved reference: 'Dialog:CancelSetup' in section: '27A59EBD-4BCA-4C54-B625-42CE0438F9F5'

If we review our original script, we see that in the 'Next' and 'Cancel' Controls of the Dialog InstallWelcome, we

reference the 'LicenseAgreement' and 'CancelSetup' dialogs.  We haven't yet migrated these dialogs, so we will

comment these references out temporarily, so that we may compile:

<!-- Commented out to compile:
 
    <Publish Event="NewDialog" Value="LicenseAgreement"><![CDATA[1]]></Publish>

-->

And:

<!-- Commented out to compile:

    <Publish Event="SpawnDialog" Value="CancelSetup"><![CDATA[1]]></Publish>

-->

If we compile now, we get:

C:\temp\Product.wixobj : fatal error LGHT0028: Unresolved reference: 'Dialog:SplashBitmap' in section: '27A59EBD-4BCA-4C54-B625-42CE0438F9F5'

The offending line in the 'Back' Control.  If we examine this control carefully, we note that the 'Back' button is

Disabled='Yes'.  Since we can't ever go back to the SplashBitmap, we might as well remove the reference (This is a

logic bug in the original InstallShield screen logic.  As you spend time reverse engineering InstallShield setups,

you'll find may such errors).

The 'Back' control should now look like:

<Control Id="Back" Type="PushButton" X="164" Y="243" Width="66" Height="17" Disabled="yes" Text="&lt; &amp;Back"></Control>

While we are cleaning up,let's remove the extraneous conditions on the Copyright Text control.  After removing the

conditions, it should look like this:

<Control Id="Copyright" Type="Text" X="135" Y="144" Width="228" Height="73" Transparent="yes" TabSkip="no">
  <Text>WARNING: This program is protected by copyright law and international treaties.</Text>
</Control>

If we run the setup now, we see a pretty plain Welcome Screen.  We seem to be missing the InstallShield screen

background.  If we look closely at the Dialog XML, we notice that there is a reference to a bitmap control:

   <Control Id="Image" Type="Bitmap" X="0" Y="0" Width="374" Height="234" Text="NewBinary5" />

Where may we get this "NewBinary5"?

Well, NewBinary5 refers to a an entry in the Binary table of the MSI database.  If we go back to our original

generated setup.wxs, and do a search for NewBinary5, we see that one of the lines looks similar to this:

<Binary Id="NewBinary5" src="Binary\NewBinary5.ibd" />

Dark.exe will have created a file called NewBinary5.ibd in a binary subdirectory of the location where Dark was

originally run.  Copy this NewBinary5.ibd file to the same location you've placed your product.wxs.

Add the following line to your <UI> section, so that WiX will embed this file into your MSI:

<Binary Id="NewBinary5" src="NewBinary5.ibd" />
    
After this, we finally have a reproduction of the original InstallShield Welcome Dialog.  We may continue to add dialogs as needed, by either hand crafting them, our extracting them from our existing installations.

Here's the final script:

<?xml version='1.0'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2003/01/wi'>
<!-- really, follow the advice here - this GUID is invalid - generate your own! -->
   <Product Id='27A59EBD4BCA4c54B62542CE0438F9F5' Name='My Product Name' Language='1033' Version='1.0.0.0'

Manufacturer='My Company'>
      <Package Id='90E7DDF747F445098914E98F99AC2841' Description='My Setup' InstallerVersion='200'

Compressed='yes' />
      <Media Id='1' Cabinet='product.cab' EmbedCab='yes' />

      <Directory Id='TARGETDIR' Name='SourceDir'>
         <Directory Id='ProgramFilesFolder' Name='PFiles'>
            <Directory Id='MyCompany' Name='MCompany' LongName='My Company'>
               <Component Id='MyProductComponent' Guid='7F7A882791C544dbAEC7CF134F819EF3'>
<!-- Note: This is just an example - you wouldn't really link to a file in your system dir -->          
       <File Id='MyFile' Name='notepad.exe' KeyPath='yes' DiskId='1' src='C:\Windows\System32\notepad.exe'/>
               </Component>
            </Directory>
         </Directory>
      </Directory>

      <Feature Id='MyProductFeature' Title='My Product Feature' Level='1'>
         <ComponentRef Id='MyProductComponent' />
      </Feature>
        <UI>

 <Binary Id="NewBinary5" src="NewBinary5.ibd" />
                  
            <InstallUISequence>
   <Show Dialog="InstallWelcome" After="CostFinalize"><![CDATA[Not Installed And (Not PATCH Or

IS_MAJOR_UPGRADE)]]></Show>                
            </InstallUISequence>

<Dialog Id="InstallWelcome" Width="374" Height="266" Title="[ProductName] - InstallShield Wizard"

NoMinimize="yes">
        <Control Id="Next" Type="PushButton" X="230" Y="243" Width="66" Height="17" Default="yes" Text="&amp;Next

&gt;">

<!--
          <Publish Event="NewDialog" Value="LicenseAgreement"><![CDATA[1]]></Publish>
-->

        </Control>
        <Control Id="Cancel" Type="PushButton" X="301" Y="243" Width="66" Height="17" Cancel="yes" Text="Cancel">

<!--
          <Publish Event="SpawnDialog" Value="CancelSetup"><![CDATA[1]]></Publish>

-->

        </Control>
        <Control Id="Back" Type="PushButton" X="164" Y="243" Width="66" Height="17" Disabled="yes" Text="&lt;

&amp;Back">
        </Control>
        <Control Id="Copyright" Type="Text" X="135" Y="144" Width="228" Height="73" Transparent="yes"

TabSkip="no">
          <Text>WARNING: This program is protected by copyright law and international treaties.</Text>
        </Control>
        <Control Id="TextLine2" Type="Text" X="135" Y="55" Width="228" Height="45" Transparent="yes">
          <Text>The InstallShield(R) Wizard will install [ProductName] on your computer. To continue, click

Next.</Text>
        </Control>
        <Control Id="DlgLine" Type="Line" X="0" Y="234" Width="374" Height="0" />
        <Control Id="Image" Type="Bitmap" X="0" Y="0" Width="374" Height="234" Text="NewBinary5" />
        <Control Id="TextLine1" Type="Text" X="135" Y="8" Width="225" Height="45" Transparent="yes">
          <Text>{&amp;TahomaBold10}Welcome to the InstallShield Wizard for [ProductName]</Text>
        </Control>
      </Dialog>
        </UI>
   </Product>
</Wix>

I had planned a post on how to extract Installshield Dialogs from an existing setup, for use with WiX, but I'll have to postpone that entry.  I had an unscheduled event take up most of my day.

Instead, I'll answer a few WiX questions that have been asked recently:

1. What is WiX?
A: WiX is "Windows Installer XML", a tool for creating Windows Installer setups through declarative XML markup.

2. WiX is pretty new.  Is it robust enough for my installation?
A: WiX has been used internally in Microsoft for quite some time.  Many teams in Microsoft have dumped Installshield in favor of WiX, including SQL Server, Microsoft Office, and MSN.  I sincerely doubt that your installation is more complicated than setup for Microsoft Office.

3. What about support?  I can buy commercial support from InstallShield, but not for WiX?
A: I've been monitoring the WiX-Users mailing list for several months now, and even sent my first question yesterday.  Questions are anwered promptly, and often by the author of that feature. (Try getting a software engineer on the phone from InstallShield!)  My question was answered within a couple of hours.
If you really insist on purchasing support for every product you work with, then there are several companies available that will sell support for Open Source Software.

4. Where do I get information about WiX?
A: Well, after downloading the software, I'd suggest that you head directly to Gabor DEAK JAHN's tutorial.  This document is considered the defacto starting point for working with WiX.  After reading the tutorial, you may find that the WiX.chm help file makes a decent reference. (I don't think so, personally.  The WiX documentation could use some improvement.  Specifically, the Schema section has no associated usage examples.  This is one area where WiX could learn something from nAnt.)
Also, subscribe to the WiX-Users mailing list several weeks before starting a WiX project.  There are some pretty interesting discussions on "Best Practices" with WiX.  This stuff isn't in the docs, in in a bunch of people's heads.  In fact, it might pay off to go spend a half day reading the mailing list archives after spending time with the tutorial.

5. I still want more WiX info!
Sure - a non-inclusive list:
http://blogs.msdn.com/robmen
http://strangelights.com/blog/category/7.aspx
http://www.ondotnet.com/pub/a/dotnet/2004/04/19/wix.html
http://blogs.wdevs.com/neilco/archive/2005/01/04/1744.aspx
http://gauss.dynalias.net/blog/ExtendingWiX.aspx

(Part of a multi-part story on WiX)

Well, it has certainly been a long day.  Today, I've been working on reverse engineering my current install, written with InstallShield 9, using Windows Installer.  WiX has a tool called 'dark.exe' that allows you to convert an MSI database into a valid WiX xml format.

So, after "Darking" my existing MSI, I find roughly 6,000 lines of rather dense XML.  As I'm intimately familiar with the previous installation, reviewing this WiX-generated code gives me a good 'feel' for how WiX works.  I'm afraid that I won't be able to use most of the generated code, however.  We used InstallScript to write our custom actions, and since we are dumping Installshield, we have to dump many custom actions, too.  Fortunately, WiX will perform the bulk of the work with it's built in Custom Action library.  I'm particularly looking forward to using the database and IIS portions of the CA library.

There's one outstanding WiX bug where the Database gets 'dropped' during a rollback operation.  I'll have to make certain to test heavily to make certain that rollback doesn't do this to my install - that's a pretty severe issue.  The cool thing about this being an open source project is that if no-one else fixes it, I can always do so myself.  (Not like InstallShield, where I'm still experiencing some of the same bugs left over from IS 7.0)
So, since I'm going to have to actually maintain this stuff in the future, I won't be using Dark.exe to 'copy' the previous installation.

The WiX community seems to be Anti-managed code for custom actions.  That's unfortunate, as my C# skills are stronger than my C++ ones.  I've looked at the current WiX CAs implemented in C++, and they certainly don't look fun to modify (or author, for that point).  I'd much rather do managed CAs, and I'll probably use C++ custom actions as a wrapper around C# managed methods.

I think my next post will be a walk-through on how to take an existing Dialog from InstallShield and convert it into a WiX dialog.

I'm about to begin what I'll call the "Journey of WiX".  My intent is to chronicle my story during the next month. I will be converting a rather complicated InstallShield setup to a WiX based setup.  I'll share my trials and tribulations, along with my successes, for the next month of this project.

My goal is to write something on regular basis for the next thirty days, with each blog entry related to this project.

By the end of the month, we'll know if I succeeded, or not.

Let’s hope for success!