IIS extension: WebAppPool

Another challenge - another piece of fun with WiX. Imagine the following requirement: the installation program must install an application pool on IIS6+ environments; the multiple installed instances should use the same application pool. In other words, the application pool must be created with the first instance installation, and must be removed with the last instance uninstallation. 

A special element for maintaining IIS AppPools in IIS extension is called WebAppPool. As usual, we'll wrap it into a separate component, so that it is created on install. Later, we'll create a special custom action to deceive the standard removing mechanism on uninstall:

      <Component DiskId="1" Id="CreateIISAppPool" Guid="{YOURGUID-6C5B-4980-AD0B-E32FA2DBC1F4}" Directory="WebsiteFolder">

         <Condition>IISMAJORVERSION <> "#5"</Condition>

         <iis:WebAppPool Id="IISSiteAppPool6" Name="[IISAPPPOOL_NAME]" MaxWorkerProcesses="1" Identity="networkService" />

         <RegistryKey Root="HKLM" Key="$(var.ParentKey)">

            <RegistryValue Name="IISAppPoolName" Type="string" Value="[IISAPPPOOL_NAME]"/>

         </RegistryKey>

      </Component>

As you can see, the component is installed once the target system has IIS 6+. It creates a WebAppPool with the name provided in IISAPPPOOL_NAME public property. It also writes this name into a registry value, which resides under the instance-specific registry key. 

With this component included into the MSI package, the app pool is created when the first instance is installed, and nothing happens for second and subsequent instances. 

Let's examine the uninstall behavior. The MSI behaves natural - when it meets the component to uninstall, it removes the WebAppPool specified in it. But the IIS extension which performs the actual deletion of app pool, needs the name to be passed in it. So, the only thing we should do is to supply this action with a fake app pool name each time, except for the last instance uninstall.

Here is the algorithm:

1. search the registry for the app pool name as usual
   
2. schedule a special action on unistall after AppSearch, which detects if this is the last instance being uninstalled, and if not, "breaks" the app pool name into something non-existent
   

The first point is quite straight-forward:

      <Property Id="IISAPPPOOL_NAME">

         <RegistrySearch Id="IISAppPoolName" Root="HKLM" Key="$(var.ParentKey)" Name="IISAppPoolName" Type="raw" />

      </Property>

The second one is not natural, like any hack:

      [CustomAction]

      public static ActionResult ChangeWebAppPoolNameToDeceiveUninstall(Session session)

      {

         int numberOfInstalled = 1;

         foreach (ProductInstallation product in ProductInstallation.GetRelatedProducts(session["UpgradeCode"]))

         {

            if ((session["ProductCode"] != product.ProductCode) && product.IsInstalled)

            {

               numberOfInstalled++;

               break;

            }

         }

         if (numberOfInstalled > 1)

         {

            session["IISAPPPOOL_NAME"] += string.Format("|{0}", DateTime.Now.ToLongTimeString());

         }

         return ActionResult.Success;

      }

It iterates the related products (those sharing the UpgradeCode), and if it finds others installed, except for itself, it changes the app pool name we retrieved from registry into something unique, for instance, appends a unique string.

Thus, the IIS custom action which is going to delete the app pool fails to find the one with the provided name, and does nothing. When, otherwise, it is the last instance being uninstalled, the retrieved app pool name remains unchanged, and the app pool is successfully removed.

Note that the mentioned action should be immediate, should occur after AppSearch on uninstall.

That's it! I would appreciate any comments as usual.

IIS extension: WebSite

Ok, it's time for another portion of the installation fun, now about the IIS web sites.

The IIS extension in WiX is probably the most tricky and unobvious. That's my personal impression, of course. But, anyway, it gives you an option to tweak any property of a website, virtual directory or web directory. 

When installing a web application on Windows XP and thus IIS 5.1, it is natural to create an "ad hoc" virtual directory during install and remove it on uninstall. That's basically quite common case, but what if the application requires to reside under the site root directly, not virtual directory? 

In this case the root of the Default Web Site should just be switched to the installation directory - nothing is created on install and nothing is removed on uninstall. Let's see how this can be done with WiX IIS extension.

The iis:WebSite element has two "modes": if it resides under Component element, it is created during install, otherwise it is there just for reference from other elements. Fortunately, it has a special attribute ConfigureIfExists. Setting it to 'yes' avoids an attempt to create a new site, configuring the existent one instead:

      <Component DiskId="1" Id="ModifyIISSite5" Guid="{YOURGUID-2023-4D19-90D2-EE9101C71E44}" Directory="WebsiteFolder" Permanent="yes">

         <Condition>IISMAJORVERSION = "#5"</Condition>

         <iis:WebSite Id="IISSite5" Description="[IISSITE_NAME]" Directory="WebsiteFolder" ConfigureIfExists="yes">

            <iis:WebAddress Id="IISSiteAddress5" Port="[IISSITE_PORT]"/>

         </iis:WebSite>

      </Component>

Note, that in this case you should make sure you specified the existent website data. The website is uniquely identified by the description, port and header. The first is an attribute of a WebSite element itself, others belong to the child mandatory element WebAddress. 

The previous snippet highlights another attribute as bold - Permanent="yes". It makes the hosting component permanent, thus preventing it from being deleted on uninstall. Internally, the Windows Installer engine just keeps an extra reference to this component forever, thus it reference count is never equal to 0.

One last thing I'd like to point your attention to is a component condition. It uses the property called IISMAJORVERSION. This property, as well as another one called IISMINORVERSION, is brought by the IIS extension. They are populated from the target system registry during the AppSearch action. Before using them in your authoring make sure you add a couple of references:

    <PropertyRef Id="IISMAJORVERSION"/>

    <PropertyRef Id="IISMINORVERSION"/>

That's it! As usual, any comments are highly appreciated.

Attach / Detach database during installation

It seems I have finally managed to implement full database support in my installation program. And it also seems that I stepped on every rake one could imagine in this area. But, the harder the battle, the sweeter the victory.

I had the following requirements: the application is distributed with the MDF/LDF files, which must be attached during installation and detached during uninstallation. Both Windows and SQL authentication must be supported.

Fortunately, the kind WiX developers implemented a wonderful SQL extension. So, let's take advantage of the sql:SqlDatabase element. The documentation says, it can be placed either under Component, or under Fragment/Module/Product. In the first case the database will always be created when the component is being installed. This doesn't suite our needs with attach, so let's stick with another option:

<fragment>

...

<sql:sqldatabase id="SqlMasterDBWinAuth" server="[SQL_SERVER]" database="master"/>

...

</fragment>

As you can see, we specify the standard Master database in this element. That's because the database must exist on the target computer by the moment Windows Installer tries to connect. This syntax will instruct the custom action to open the connection using currently logged-on Windows account.

The next step is to provide the appropriate sql:String elements for attach/detach. It is better to put these elements inside the component which installs MDF/LDF files, but this is not the rule. And if you have different conditions for installing the files and running attach, you'll have to move the scripts into a separate component.

<Component DiskId="1" Id="MSSQLCore" Guid="YOURGUID-4E94-4B28-B995-DCBFD50B9F07">

<Condition>YOUR CONDITION GOES HERE</Condition>

<File Id="MSSQLCoreFile" Name="$(var.CoreFileName)" KeyPath="yes" />

<File Id="MSSQLCoreLogFile" Name="$(var.CoreFileLogName)" />

<sql:SqlString Id="DetachCore" Sequence="1" ContinueOnError="yes" ExecuteOnUninstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="EXEC master.dbo.sp_detach_db @dbname = N'[INSTANCENAME]Core', @skipchecks=N'true'"/>

<sql:SqlString Id="AttachCore" Sequence="2" ContinueOnError="no" ExecuteOnInstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="CREATE DATABASE [\[][INSTANCENAME]Core[\]] ON ( FILENAME = N'[DB_FOLDER]$(var.CoreFileName)' ), ( FILENAME = N'[DB_FOLDER]$(var.CoreFileLogName)' ) FOR ATTACH"/>

</Component>

At this point I should mention one reef. An SqlString string element also has an attribute SQLUser. If you provide both SqlDb attribute, pointing to the "WinAuth" definition of the database, and SqlUser attribute, pointing to the "sa user", it will lead to unpredictable and very strange behavior. I would avoid this.

Ok, now we should take care about the rollback actions: during install and uninstall correspondently. It is obvious that RollbackOnInstall should detach databases, if they got installed before failure, and RollbackOnUnistall should attach the databases back, if the failure occurred during uninstall.

Thanks to the hint of Rob Mensching in one of his replies to the WiX mailinglist, I managed to overcome another trick. Right after the database is attached, there is sometimes a connection left to this database. I can see this by opening the SQL Management studio and looking at the database status (Normal). If you detach the database in this moment, it flushes the permissions on a physical file to a logon account only. I didn't dig very deep into this, it probably corresponds to the rules of permissions change during attach/detach. As a result, the windows installer can't access the file afterwards, and the uninstallation is rolled back.

To fix this, perform "SET OFFLINE" query before detaching the database and you'll never face with this behavior again.

Thus, the final version will look similar to this:

<Component DiskId="1" Id="MSSQLCore" Guid="YOURGUID-4E94-4B28-B995-DCBFD50B9F07">

<Condition>YOUR CONDITION GOES HERE</Condition>

<File Id="MSSQLCoreFile" Name="$(var.CoreFileName)" KeyPath="yes" />

<File Id="MSSQLCoreLogFile" Name="$(var.CoreFileLogName)" />

<sql:SqlString Id="RollbackDetachCore" Sequence="1" ContinueOnError="yes" RollbackOnUninstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="CREATE DATABASE [\[][INSTANCENAME]Core[\]] ON ( FILENAME = N'[DB_FOLDER]$(var.CoreFileName)' ), ( FILENAME = N'[DB_FOLDER]$(var.CoreFileLogName)' ) FOR ATTACH"/>

<sql:SqlString Id="OfflineCoreDatabase" Sequence="2" ContinueOnError="yes" ExecuteOnUninstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="ALTER DATABASE [\[][INSTANCENAME]Core[\]] SET OFFLINE WITH ROLLBACK IMMEDIATE" />

<sql:SqlString Id="DetachCore" Sequence="3" ContinueOnError="yes" ExecuteOnUninstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="EXEC master.dbo.sp_detach_db @dbname = N'[INSTANCENAME]Core', @skipchecks=N'true'"/>

<sql:SqlString Id="RollbackAttachCore" Sequence="4" ContinueOnError="yes" RollbackOnInstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="EXEC master.dbo.sp_detach_db @dbname = N'[INSTANCENAME]Core', @skipchecks=N'true'"/>

<sql:SqlString Id="AttachCore" Sequence="5" ContinueOnError="no" ExecuteOnInstall="yes" SqlDb="SqlMasterDBWinAuth" SQL="CREATE DATABASE [\[][INSTANCENAME]Core[\]] ON ( FILENAME = N'[DB_FOLDER]$(var.CoreFileName)' ), ( FILENAME = N'[DB_FOLDER]$(var.CoreFileLogName)' ) FOR ATTACH"/>

</Component>

Ok, but what about Sql Authentication? Well, this requires some kind of duplicating the code. The SqlDb attribute of the SqlString element can't accept MSI properties, thus can't be dinamically changed during runtime. We must author another element SqlDatabase for referencing it from another set of scripts.

<util:User Id="SQLUser" Name="[SC_SQL_SERVER_USER]" Password="[SC_SQL_SERVER_PASSWORD]"/>

<sql:SqlDatabase Id="SqlMasterDBWinAuth" Server="[SC_SQL_SERVER]" Database="master" />

<sql:SqlDatabase Id="SqlMasterDBSqlAuth" Server="[SC_SQL_SERVER]" Database="master" User="SQLUser" />

The first element defines a user to connect to the database. In this example, the username and password are read from the public properties. The user is not created, it is just referenced. The second element should be familiar - it was described above. And the last one differs only in one attribute - SQLUser.

This does the trick: if you want Windows Authentication way to use, reference SqlMasterDBWinAuth in your scripts, otherwise - use SqlMasterDBWinAuth. Obviously, you need another set of the similar SqlString elements in a different component.

Tired? The last thing.

If you implemented something similar to what I've described, you should have mentioned that in case of Sql Auth the database is attached as read-only. This happens because the SQL service account (NETWORK SERVICE in my case) doesn't have enough permissions to the [DB_FOLDER] and files by the moment attach starts.

No problem, let's assign the necessary rights. Put the following snippet into your component which contains the SqlAuth scripts:

<CreateFolder>

<util:PermissionEx GenericAll="yes" User="NetworkService" />

</CreateFolder>

Note: Don't forget to reference WIX_ACCOUNT_NETWORKSERVICE property.

But, wait, the ShedSecureObjects is scheduled after the InstallSqlData, this doesn't help!

Right, the sequence should also be changed like this:

<InstallExecureSequence>

...

<Custom Action="InstallSqlData" After="SchedSecureObjects">NOT SKIPINSTALLSQLDATA AND VersionNT > 400</Custom>

...

</InstallExecuteSequence>

That's it! I know, this can't seem easy at first glance, but, as for me, it is much more controlled and customizable, than with InstallShield. I might be wrong, though.

Good luck! I would appreciate any comments and notes to this.