Torch.exe confuses the language validation and ProductCode validation

This week I faced with another issue with torch.exe. As you might know, there’s a “type” option (-t) to apply a predefined set of validation flags to the generated transform. If you’d like to generate a language transform, you should use “-t language”. It should suppress all the errors plus validate that language in both MSI packages corresponds. But it doesn’t…

The reason is just a simple bug in the tool. When you set “-t language” in the command line, this option is mapped to the TransformFlags.LanguageTransformDefault value. It is a combination of atomic values (those you can set via –serr and -val), and it mistakenly takes “validate product code” bit instead of “validate language bit”. I’ve never noticed this unless my installation uses both instance transforms and language transforms.

The workaround is quite simple: use literally “–serr” and “–val” to achieve the same result. For instance, for language transform it should be:

       torch.exe … –serr a –serr b –serr c –serr d –serr e –serr f –val l …

[By the way, does it look too long just for me? I would prefer –serr abcdef :-)]

I’ve also filed an issue to the WiX toolset. Hope this can help somebody.

Torch.exe throws scary error message unrelated to the real problem

Today I’ve been working on the localization of my installation project, and I had to create a number of language transforms. The following simple call of torch.exe

            torch -t language setup.msi setup_ru-ru.msi -out mst\ru-ru.mst

returned the scary error message:

            error TRCH0001 : The Windows Installer service failed to start. Contact your support personnel

I’ve seen this kind of errors a couple of times, and it was a serious problem with Windows Installer engine on the target machine in all cases. Once, it indicated that Windows Installer service is completely broken, and only OS reinstall helped (fortunately, it was virtual PC)… But mighty Google gave a single, but exact hint. It is just a single line, and one can miss the point since that’s another problem which is discussed there.

So, the actual problem: if –out switch points to a folder which doesn’t exist (‘mst’ in this case), torch.exe can’t create it and returns the error. That’s okay behavior to live with, but the error message should be changed to something more appropriate: “The folder ‘mst’ can’t be found. Make sure it exists before referencing in –out switch”. I’ve also created an issue to the WiX inbox at sourceforge.net.

Hope this info is helpful until the message text is fixed.

Extended logging options in WiX custom actions

The best and maybe the only way to find out what's going wrong with the installation is investigating the MSI log file. Fortunately, the Windows Installer respects log writing very much. You can find the ways to enable logging and different logging options here.

The verbose log contains all the information MSI can generate. Though it is really useful when it comes to troubleshooting the failed installation, it is quite hard to read, especially for newbies. Again, fortunately, there's a super chapter "Using the Windows Installer log" in a super book called "The Definitive Guide to Windows Installer" by Phil Wilson, which guides you through the basics of log file reading and understanding.

I used to generate the log file with /L*v options, which means verbose. But, if you use WiX custom actions, it turns out that you can make them logging even more verbose.

If you browse the WiX source code, you can find the lines like this in its custom actions:

WcaLog(LOGMSG_STANDARD, "Error: Cannot locate User.User='%S'", wzUser);

The first argument is a logging level. It can be 

• LOGMSG_STANDARD, which is "write to log whenever informational logging is enabled", which in most cases means "always"
• LOGMSG_TRACEONLY, which is "write to log if this WiX build is a DEBUG build" (is often used internally to dump CustomActionData contents)
  
• LOGMSG_VERBOSE, which is "write to log when LOGVERBOSE"

Wait a minute, what does the last option means? I've already set the verbose logging by /L*v, but I don't see more entries there. Here is the algorithm WiX CA use to know whether to write a log entry marked as LOGMSG_VERBOSE level:

• Check if the LOGVERBOSE property is set (can be set in the command-line since it is public)
• Otherwise, check if the MsiLogging property is set (MSI 4.0+)
• Otherwise, check the logging policy in the registry

So, the following is the easiest way in my opinion to make your MSI (WiX-based) log file even more verbose:

   msiexec /i package.msi ... LOGVERBOSE=1 /L*v install.log

Hope this helps.

P.S. This is just a brief extract of what's there in the source code. As usual, code is the best documentation ;-)

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.

Multiple instance installations and patching

Well, this is the first message to my first weblog, and it should be outstanding by default. :-)

Sometimes, when creating an installation program, it is necessary to support multiple instance installations of the product to one particular computer. This requirement immediately brings the complexity of the installation to the advanced level. A couple of most tricky things to look after are component rules and patching.

In order to make your installation "multi-instance-aware", you should author a number of instance transforms in your source. The number of transforms is the number of instances you plan to support (except for the default one, of course). Fortunately, WiX provides very convenient way to do this:

   <instancetransforms property="ANY_PROPERTY">

      <instance id="InstanceId1" productcode="{42A33A91-36B0-4700-A6F5-1289D22F358C}"/>

      <instance id="InstanceId2" productcode="{68C62C01-D064-4CF0-9239-F5D2FF36BD9A}"/>

      ...

   </instancetransforms>

As always with Windows Installer, this is not the end. According to the MSI documentation about authoring multiple instances, "To keep the nonfile data of each instance isolated, the base package should collect nonfile data into sets of components for each instance". This can be done by authoring a duplicate of each component for each instance, and install conditionally. But it becomes really complex to manage when you have much more than 2 instances, let's say, 100. 

I chose another way. Assuming the fact that each instance should contain the same set of components, but with different GUIDs, we can generate a number of transforms, one per each instance, which change just the GUIDs of all the components. So, the algorithm is similar to this:

• copy the MSI package
• use API to query and update the database with new GUIDs for each component
• generate a transform between the copy and original MSI
• drop the copy MSI
• repeat the steps about the number of times as many instances you plan to support
• embed all these transforms into the original MSI

Obviously, the number of such customization transforms must be equal to the number of instance transforms and the names should be convenient to use. For instance, if you did everything correctly, you should be able to run the installation of new instance as follows:

msiexec /i YourPackage.msi MSINEWINSTANCE=1 TRANSFORMS=:InstanceId1;:ComponentGUIDTransform1.mst ...

This works like a charm in conjunction with an algorithm to detect next available instance and a bootstrapper. 

Now let's turn to the patching. When I browsed the internet for the info about multiple instance installs and patches, I found a great post of Christopher Painter. As he says there, one should populate the Targets property of the patch summary info stream with product codes of all the instances, otherwise the patch detects just the default instance. That's correct, but, yes, this is not the end of the story.

Let's take a look at the patch definition and its contents: "Patches contain at a minimum, two database transforms and can contain patch files that are stored in the cabinet file stream of the patch package". These two transforms contain the target product GUID and updated product GUID each. In the case of simple patching, it is just one GUID of the target product.

Hence, in order to be applied to each instance, the patch must contain a pair of transforms for each instance. Unfortunately, it is not supported by WiX torch+pyro approach and we should fall back to the powerful API:

   // dump transform and change its properties

   string transformFileName = GetNextValidName(transformName, nameSuffix);

   patch.ExtractTransform(transformName, transformFileName);

   SummaryInfo info = new SummaryInfo(transformFileName, true);

   info.RevisionNumber = info.RevisionNumber.Replace(originalProductCode, productCode);

   info.Persist();

   info.Close();

So, as you can see, we do the following (for each instance and for each of 2 transforms in default patch):

• extract transform from the patch package
• change the original product code to this instance product code in summary info

Afterwards, we must insert these newly created transforms into the _Storages table of the patch package:

using (View insertView = patchForWrite.OpenView("INSERT INTO `_Storages` (`Name`,`Data`) VALUES ('{0}', ?)", transformFileName))

{

   using (Record record = new Record(1))

   {

      record.SetStream(1, new FileStream(transformFileName, FileMode.Open));

      insertView.Execute(record);

      patchForWrite.Commit();

   }

}

And finally, we should append the product GUID of each instance to the Template property of Summary info (it is shown as Targets with Orca) and the name of each transform to the LastSavedBy property of the Summary info (it is not shown with Orca). Something like this:

// update patch properties

if (!patchForWrite.SummaryInfo.Template.Contains(productCode))

   {

      patchForWrite.SummaryInfo.Template += ";" + productCode;

   }

patchForWrite.SummaryInfo.LastSavedBy += ";:" + transformFileName;

patchForWrite.SummaryInfo.Persist();

That's it! Afterwards, the following magic line should work correctly and patch the installed instance of your application:

msiexec /p YourPatch.msp /n {YOURGUID-0002-0000-0000-624474736554} /qb

Good luck deploying! I would appreciate any comments on this.