Writing Clear Code

This topic is a bit of a divergence from Custom Actions, but useful for some general coding skills. I'm going to highlight the C# language in this post, although you don't need to know C# to benefit from this discussion - I'll cover the essentials in the post. The topic is how to write clear code that makes it easier to defer the understand the intention of the code rather than the behavior of the code. The subject came up about a few months ago in a discussion with a coworker who initially didn't quite agree with me. I'll lay out the argument here as I did with him.

Take for instance the following code snippet:

string a = "hello";
string b = "hello";
System.Console.WriteLine(a == b);
System.Console.WriteLine((object)a == (object)b);

Lets explore the last two lines. The a == b equivalence operator is working on strings, and by C# rule, two strings are equivalent if they are both null, or if both values are non-null references to string instances that have identical lengths and identical characters in each character position. Translation - two nulls are identical, and any two strings that match, case sensitive, will result in a true expression. In the latter comparison, when we cast both of the strings to objects, we are not comparing the values of the strings, but the objects themselves.

What do you think it will print? The answer is True and True. Why? String literals that are identical within the same assembly refer to the same instance. Translated, 'a' and 'b' are variables that refer to the same underlying object.

Now lets replace the declaration and assignment for string b with:

string b = "he"+"llo";

Now what do you think it will print? The answer is again True and True. Why? Because the Lexical analysis (lexer) in the compiler stripped out the needless additive operator in the literal. The same would have happened if we changed the string to be "hell\u006f" - since '\u006f' is the Unicode escape sequence of the lower-case letter 'o', and this expansion takes place (most likely) prior to the lexer during the transformation phase in the compilation process.

Now lets replace the same line as above with the following two lines:

string b = "he";
b += "llo";

Now what do you think it will print? The answer is now True and False. Why? The strings are equivalent, but since the preprocessing of the source file before the compilation did not identify the strings as being the same literal, they are in different objects. In fact, because a string is immutable (once created cannot be changed), there was the construction of the string "b" during declaration and initial assignment that was later garbage collected when a new instance of "b" was created during the string concatenation.

Now that the necessary background information is understood, can you tell me the intention of the following code snippet?

string a,b;
//code here that assigns and manipulates a and b
...
if (a==b)
    compareOK();
else
    compareBad();

I'm hoping you are going to tell me that you have no clue as to the intent of the programmer. The intent could have been to compare the two strings in a case sensitive manner, ignoring cultural rules (which is what actually is happening in the above snippet). It also could have been to compare object equivalence, just that the programmer forgot to cast the strings to object first. The intention could also have been a case-insensitive comparison. Another possible intent was to compare strings using cultural rules. The intent of the programmer simply is not clear!

Rewriting the comparison line in the above snippet correctly, assuming the actual behavior of the code was the intent should look like this:

if ( String.Compare(a, b, false,
System.Globalization.CultureInfo.InvariantCulture ) == 0 )

This tells me that the intent of the programmer was to compare the two strings in a case sensitive manner, ignoring cultural rules . There is no other possible intent given the above line of code. This is not saying that the code is correct - just that the intent of the code is clear to those lucky enough to read it, and that the developer thought it through.

If I am skimming through some code and see a non-String.Compare() string comparison, I will sprinkle a //BUGBUG: comment above it. Why? The simple string comparison syntax has been a rather common cause of bugs in C# code - much like the C/C++ switch statement. When investigating an issue in a piece of code, I will first look for these BUGBUG's and the TODO's as a starting point - often with better-than-random chance results.

Custom Action Tutorial Part III – What we did in Part II

This is the third in a series of articles about building Custom Actions. If you are coming in late to the party, check out Part I and Part II first. If I tried to explain what we were doing and why in the last installment of this tutorial, you would be even more lost now than you probably are. This article is an attempt to explain exactly what it was we did in Part II and why. Let’s start by going over each project in our solution.

The HelloWorld project

We needed something to install. This happens to be it. I could have picked notepad.exe or something, but it is nicer to see how Visual Studio could grab project outputs and put them into an MSI fairly easily.

The CustomAction project

This one is really the meat of what we are trying to learn. The other projects are sort of extraneous if you are using a tool other than Visual Studio to build your MSI. Microsoft did a pretty good job of explaining why you may want to use Custom Actions in the first place, so I’m not going to rehash that.

We created a Custom Action DLL. The reason I chose a DLL is because it is the most flexible means of tightly integrating a Custom Action with the installation engine. Additionally, there is not much you cannot do in a Win32 C++ DLL. An executable Custom Action cannot interact with the MSI engine. A VBScript or JScript action does have this capability, but if you are not careful, these are not bulletproof, and usually won't allow you to do much anyway.

We added a "Module Definition File" (.def) file to the project. This .def file is read by the linker and is used (for our purposes, anyway) to prevent mangling of function names (to be technically correct, specify the calling convention to be used). Mangling is entirely normal when a DLL is created without using the extern "c" function declaration – in fact, it is called by the more pleasant name "Decorating" the function names. If you run "Dependency Walker" (depends.exe in the Bin folder of the Platform SDK), and open a DLL in it, the listing of function exports appears. Pick FrameDyD.Dll from the same Bin directory and look at it. You will notice some ? and @ symbols around the names of functions. The .def file allows us to not create these mangled exports – you can verify this by opening the custom action dll we built in our project and see this for yourself. Ultimately, this makes the process less prone to error when entering data in the custom action table of the MSI. When adding the Custom Action via Visual Studio, it will handle the mangling automatically, so for this specific project this was not strictly necessary. If you are adding this DLL using another installation designer, you will thank me for not mangling the function names. Anyway, the .def file must contain the function names of any function you wish to make callable from outside the DLL. In our case, we wanted all four of the functions we added to be callable by the MSI engine, which is why they were added to the DEF file. There are tons of other ways to accomplish this goal

The function signatures we added to the CustomAction.cpp file are based on the requirements of the DLL Custom Action type. We return an unsigned integer (UINT) and accept a single parameter that is the handle to the installation (MSIHANDLE). We must use this handle to interact with the MSI Engine. The UINT return type indicates our status to the MSI engine.

The file "msi.lib" is the link library for the MSI engine. All custom action DLL’s must link to this file in order to call any MSI functions. The instructions in Part I explained an alternate way to inform the linker what to link with. One way is not necessarily better or worse than the other. The functions defined in the header files msi.h and msiquery.h (that we included in the stdafx.h file) all require linking to this library.

We made additional solution configurations to give us a UNICODE project type. While this is not intended to be a primer on UNICODE, all NT kernel OS’s are UNICODE under the hood. Windows 95 through ME are not UNICODE, although they can support some UNICODE extensions with the Unicode Library. For dll's and executables that only will run under Windows NT, 2000, XP, or 2003, the only option you should use is UNICODE. Therefore, if you are targeting only NT based systems, build and use the UNICODE projects. If you are supporting Windows 9x based machines use the non Unicode versions. To make the Unicode transition easier, Microsoft provided the tchar.h header that we include in the stdafx.h file that deals with strings based on compiler settings (actually preprocessor macros), so you may write code that will compile and work as native UNICODE or ANSI based on compiler settings. The TEXT() macro used in the "Hello MSI!" exercise is an example of one such tchar.h macro. Future Custom Action examples presented here will use the tchar.h macros when the compatibility of the Custom Action spans both Windows 9x and NT based platforms. Actions targeting Windows NT based systems will only compile in UNICODE, and will not use the tchar.h macros.

The final thing we added to the CustomAction project was the header include for strsafe.h. This header file describes the safe string functions intended to replace the C/C++ standard library string functions as well as specific Windows string handling implementations. These functions always start with the word "String" followed by the type of count provided as a parameter to the function, either the "Cb" which is a count of bytes, or "Cch" which is a count of characters. Remember that Unicode implementations use 2 bytes per character as opposed to the ANSI 1 byte per character – so the Cb and Cch designations are important. The last important fact about this header is by default it will deprecate the unsafe string handling functions – if you use sprintf(), you will get a compiler warning.

The Setup1 Project

Hopefully we are pretty clear on the basics for the first part of this one – an EXE is generated, Visual Studio generates a basic MSI and adds entries in the Feature, Component, File, Shortcut, and other tables to install the HelloWorld exe and the shortcut for it.

When we added the Custom Actions, we did a few things that affected the compiled MSI. Use Orca (which you installed in Part I) to view the generated MSI and follow along - try to remember back to the Custom Action theory presented in Part I:

1. Added a new Component and File table entry that installs the CustomAction.dll file.
2. Added four entries to the CustomAction table, referencing the DLL that we installed with the product. Notice the Source column of the CustomAction table is a reference to the key of File table for our Custom Action DLL. The CustomAction table's Target column is the DLL entry point (remember this is nothing more magical than the function names in our .def file). The action name is just a randomly generated GUID. The type column starts its life as a Type 17 which indicates msidbCustomActionTypeDll + msidbCustomActionTypeSourceFile, and to this number is added the following:

   Action Type	Decimal Value	Description
   Uninstall	1041	= 17 + msidbCustomActionTypeInScript
   Install	1041	= 17 + msidbCustomActionTypeInScript
   Rollback	1297	= 17 + msidbCustomActionTypeInScript + msidbCustomActionTypeRollback
   Commit	1553	= 17 + msidbCustomActionTypeInScript + msidbCustomActionTypeCommit

3. Looking at the InstallExecuteSequence table, note that all but the uninstall custom action is scheduled before the RegisterUser Standard action, and the uninstall custom action is scheduled before the UnpublishComponents action. Note that these actions are conditionalized on the action state of the component, denoted by the dollar-sign - you can see this clearly in the InstallExecuteSequence table. In a nutshell, this condition will cause the custom actions to run only when the component it is tied to (the Custom Action DLL) is being added or removed from the system.

Visual Studio does not give us a bunch of options when dealing with Custom Actions, so we are pretty much stuck with what they offer – which is the ability to add an additional condition (other than the component install state), stuff what goes into the CustomActionData property fairly easy, and sequence the custom actions relative to each other. You cannot change sequencing of the custom action (like making it occur relative to another standard action other than RegisterUser or UnpublishComponents, embedding the custom action in the binary table, or add immediate custom actions. Other authoring tools offer the ability to be tons more flexible, but we are stuck with these limitations for now.

That concludes Part III of the Custom Action Tutorial. In the next part, we will learn how to debug the Custom Action.

Custom Action Tutorial Part II – Creating the Project

[Update 3/10/2009: Updated download link. Thanks for hosting, Aaron!]

In Part I we covered the dry material - what custom actions are, and how to use them. In this part of the tutorial, we will configure the development environment and create a baseline project to start from when developing future Custom Actions. Please make sure your system is configured as described in the first part before continuing.

I am providing a download link for the final project described in this part for convenience (see the end of this post for the link), but I recommend first time custom action developers follow the steps so they understand what is going on. For my more experienced readers, please bear with the simplicity here, but review the project settings before downloading or using the template in future parts.

Create a Basic Installation Project

To create our solution, open Visual Studio 2003. We are going to create two projects to start with – one a Win32 Project called "HelloWorld", and a deployment project that will create an MSI to install it. Go to the File->New->Project menu. Select the Visual C++ Projects->Win32->Win32 Project. Call the name of the project "Hello World" and place it into a directory such as C:\Projects\CATutorial. Select Finish in the Wizard dialog. When the IDE initializes, you should see the Solution Explorer window – Right-click on the Solution 'HelloWorld' line at the top of this box and select Add->New Project. Find the Setup and Deployment Projects category and select Setup Project, and select the Setup Project Wizard – you can accept the default name of Setup1. Hit next, and accept the defaults for page 2. On page 3, check the Primary Output from HelloWorld option and hit Finish. When the project opens, select the Users Programs Menu and right-click in the pane to the right. Select Create New Shortcut. Double-click Application Folder and double-click the Primary Output from HelloWorld (Active). Rename the shortcut if you wish.

Now we have both an EXE and an MSI project that installs the EXE plus a shortcut to it. At this point, we can build and test our MSI by right-clicking the Setup1 project and selecting Build. Next, right-click the project and select Install. You will be walked through the standard MSI project dialog sequence – just accept the defaults and finish the install. A shortcut is installed to Program Files in the Start Menu, which will open a window that pretty much does nothing. If you get this far, you are on the right track.

Add a DLL Project

To make a Custom Action DLL, we want to now add a new project – a Win32 Project that is a DLL. Follow the add project instructions for "HelloWorld" above, but call it "CustomAction" and in the Wizard, select the Application Settings and pick DLL for the Application Type. Press Finish. We now need to add some items to this project – please follow this closely.

1. Right-click on the CustomAction project and select Add->New Item. Find the Module-Definition File (.def) and select it. Call the file CustomAction and press Open. We'll add some content to it in a later step.
2. Right-click on the CustomAction project and select properties.
3. In the Configuration dropdown, select All Configurations
4. Expand the Linker folder, and select input. In the Additional Dependencies edit box, enter msi.lib and hit Apply. NOTE: As an alternate to this and the previous 2 steps, you can use the following directive in the stdafx.h or any other source file to tell the linker to link with msi.lib: #pragma comment(lib, "msi.lib")
5. In the upper right hand corner of the Property Pages dialog box, click Configuration Manager.
6. Under the Active Solution Configuration dropdown, select New. Enter the name Release Unicode, select Release from the Copy Settings from dropdown, and leave the checkbox checked. Press OK.
7. Repeat the previous step, calling the Configuration Debug Unicode and select Debug under the Copy Settings From dropdown. Close the Configuration Manager.
8. We are now back at the CustomAction property pages. Select Debug Unicode from the Configuration dropdown. Under the General Configuration Properties, find the Character Set setting and select Use Unicode Character Set. Press Apply.
9. Repeat the previous step for Release Unicode. Press OK to close the CustomAction property pages.
10. Repeat the previous two steps for the "HelloWorld" project by opening the property pages for the HelloWorld project.
11. In the CustomAction project, under the "Header Files" folder, double-click the file stdafx.h file to edit it. Under the // TODO: line, add the following lines:
    #include <tchar.h>
    #include <msi.h>
    #include <msiquery.h>
    #include <strsafe.h>
12. It is always a good idea to add versioning information to all the compiler outputs you build, so right-click on the CustomAction project and select Add->Resource. Pick Version from the list by double clicking on it. Edit the information here if you so desire.
13. In the CustomAction.cpp file, add four functions based on the following template named Install, Commit, Rollback, and Uninstall – function names are case sensitive.
    extern "C" UINT __stdcall Install(MSIHANDLE hInstall)
    {
    return ERROR_SUCCESS;
    }
14. Edit the CustomAction.def file and make it look like this:
    LIBRARY CustomAction
    EXPORTS
    Install
    Commit
    Rollback
    Uninstall

As a final step, we want to add the Custom Action DLL to the setup project. Right-click on Setup1 and select View->Custom Actions. Right-click on Custom Actions in the pane that opens up and select Add Custom Action. Double-click on Application Folder, and then click Add Output. Select CustomAction from the Project dropdown and accept the default Primary Output and Active Configuration settings. Click OK, then click OK on the Select Item in Project dialog. You will notice that four custom actions are added, and in viewing the properties for each of them the EntryPoint corresponds to the function names we created in the CustomAction.cpp file.

At this point, lets right-click on the Setup1 project and build it. You will notice that the file "msi.dll" is detected as a dependency for the Setup1 project – as a matter of fact, it will create a warning during compilation. Right-click on the msi.dll file under dependencies and check the Exclude option. Rebuilding the Setup1 project should now generate no warnings.

If you have not uninstalled the setup project from the earlier test, do so now, and run the Setup1 installation. You should see no difference from the previous time you ran the setup. If you get errors, you may want to download the zip file that contains the projects and steps we have performed up to here, and use WinDiff from the Bin directory of the Platform SDK to see if you can figure out the issue by comparing the directories of my project against yours.

Save your workspace and exit Visual Studio. Create a .zip file of the project directories – if you used my directory structure, you want to compress the "C:\Projects\CATutorial" directory. We will use this as a template for any future C++ custom action tutorials.

Initially, I was going to end this part here, but I thought people would be cursing me, saying that this whole exercise was pointless and no fun! After all this work, we created a Custom Action that did absolutely nothing! Let’s rectify that! Open your solution and replace the Install function in the CustomAction.cpp file with the following code (Don't worry if you don't understand it, we will cover this later):

extern "C" UINT __stdcall Install(MSIHANDLE hInstall)
{
PMSIHANDLE hRecord = MsiCreateRecord(0);
MsiRecordSetString(hRecord, 0, TEXT("Hello MSI!"));
MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER + MB_OK), hRecord);
return ERROR_SUCCESS;
}

When you rebuild the project and install it, you will see a "Hello MSI!" message when the Install Custom action runs.

You can download the Visual Studio 2003 Project Template here:

(Special thanks to Aaron Stebner for hosting this for me). The next installment in this series will explain what we did (and why we did it)!

Custom Action Tutorial Part I – Custom Action Types and Sequences

This is the first part of a multi-part series on Custom Actions in the MSI world. The articles are designed to be read in order, as each one will build from knowledge gained in the previous ones. To give you a short roadmap, the series will start with some dry and boring theory, and the subsequent articles will start us down a path of writing Custom Actions in unmanaged C++, C#, and script.

Custom Actions are used when the power of the Windows Installer engine's Standard Actions are not enough to accomplish a given installation task. For instance, installing or controlling a service is trivial using MSI Standard Actions, but creating a virtual directory in IIS is not. To create that virtual directory, you will need to write a custom action. Other examples of installation tasks that require Custom Actions can be found here.

Before beginning, I'd like to make sure you have the proper environment to work under. I'm going to use Microsoft's Visual Studio 2003 as the environment of choice for this series. The writing level is intended to be a walkthrough for someone who may be academically familiar with C/C++. I am going to handwave much of the Win32 enumerated types and definitions - the reader who is completely unfamiliar with these topics can find additional resources in books, the MSDN library, or around the web.

This part covers some necessary background on the different Custom Action types and Custom Action scheduling. Mostly this is dry and boring theoretical stuff, but essential to understand. Hopefully, I summarized it fairly well and won't cause anyone to drift off to sleep during their lunch hour.

Setting up your environment

For this first part, you only need the Platform SDK and a free MSI editor called Orca (distributed with the Platform SDK) installed. Future parts will require the following setup, so prepare yourself by setting this up. The development environment should be set up as follows: Install Visual Studio 2003, the current MSDN Library, and the most current Platform SDK. The Platform SDK contains new and updated header files and link libraries to support the latest OS platforms, components, and service packs. The installation of the Platform SDK installs a shortcut Microsoft Platform SDK in the Program Files menu. Open this and find the option to register the platform SDK directories with Visual Studio and run it. Finally, in the installation directory for the SDK, there is a directory "bin" and inside this you will find orca.msi. I recommend installing Orca, as my instructions are based on this. You may also substitute the MSI editor of your choice, just be aware of the differences.

Let's get started

We are going to use Orca to investigate the Orca.msi file. So, find the Orca.msi file, right-click on it, and select Edit With Orca, and play along.

The Two "categories" of Custom Actions

There are only two major categories of custom actions. The category of a custom action is indicated by a number in the type column of the CustomAction table (You should be finding this table in Orca as you read along). This number is actually a bitmask - for folks new to programming, if you looked at the number in binary form, the presence of a 1 or 0 in a particular location is how all the flags and options are interpreted by the MSI engine. I will give the hex (or Hexidecimal) representations of these flags throughout (all hex digits begin with a 0x to indicate they are hex). You can use the Windows "calc" program in the scientific view to enter the hex and convert it to binary to see which flag toggles which bit. Using hex (or even binary) is perhaps the best way to reverse engineer the decimal value from the table into the flags it represents. The two major categories of custom actions are:

• Deferred - This is a modifier of (in hex) 0x400 or 0x4000 in the Type column of the CustomAction table, which corresponds to what MSDN calls (and you do not need to understand what these are yet) msidbCustomActionTypeInScript or msidbCustomActionTypeTSAware, respectively. What is important is Deferred actions are actions that modify the state of the system in some way. There are also some notable restrictions on deferred actions - you cannot change the value of a property, you can only read the value of a single property, and you cannot interact with the MSI tables. These can only be sequenced between the InstallInitialize and InstallFinalize actions in the Sequence table, lest you encounter the dreaded 2762 error "Cannot write script record. Transaction not started." error. You will find out the reasons behind this error later in this article. Additionally, there are options to specify a special kind of deferred action of "Rollback" or "Commit." These will also be covered later in this article.
• Immediate - This is a modifier of zero in the Type column of the CustomAction table - in other words it is any entry in the Type column that does not contain the bitmasks described in the Deferred section above. Immediate actions are used for UI tasks, evaluating the state of the system, or preparing data or the system itself for later modification from a Deferred action. Immediate actions should never modify the state of the system.

The Orca.msi I am looking at has two different custom action types - 0x23 and 0x33. Neither of these numbers has the 0x400 or 0x4000 bits set, so this must mean they are Immediate Actions.

The Type column of the CustomAction table

Custom Actions have a Type - this is the base number (or bitmask) that gets entered in the Type column. This Type column tells the MSI engine both what they do and how to interpret the Source and Target columns of the CustomAction table. The major Types are:

Action	Hex Code	Description / Notes
Call a DLL function	0x01, 0x11	The DLL function that is called must be specifically written for the MSI engine.
Run an EXE	0x02, 0x12, 0x22, 0x32	Any EXE will run. By default, if the EXE returns a code other than zero, the action will fail. There is a flag available to turn off this behavior.
Abort the Installation	0x13	Aborts installation and displays a Formatted message from the target column.
Set a directory	0x23	Uses formatted text from the Target column to set a Directory.
Set a property	0x33	Uses formatted text from the Target column to set a Property.
Run some Jscript	0x05,0x15,0x25,0x35	Bear in mind the normally present WScript object is not available in these scripts.
Run some VBScript	0x06,0x16,0x26,0x36	Bear in mind the normally present WScript object is not available in these scripts.
Run a nested installation	0x07, 0x17, 0x27	Nested installations are evil. Don't do it. Use a setup launcher or AppSearch to enforce setup order.

Hopefully you see the pattern here - all the EXE actions contain 0x2, all the JScript ones contain a 0x5, etc.

The Source Column of the CustomAction Table

The second hex digit from the right in the CustomAction Type column tells us how to interpret the Source column. This is a bit more of a stretch then above, but you should see the trend:

Hex Code	Description / Notes
0x00	The Source column is a key into the Binary Table, where the the file needed to run this action is stored.
0x10	The file needed for this action is installed as part of this installation, the Source column is the key into the File table. This fact places restrictions on where this type of action can be placed in the installation sequence. In the case of the nested installation, the Source column points to the msi path inside this msi's source tree. For the abort action, the source column is ignored.
0x20	Source column is the key into the Directory table for setting the directory or indicating the EXE's working directory,Source column is the ProductCode for the nested installations,Source is null for the VBScript and Jscript actions. Note that you cannot return anything other than a success code with actions of this type. Actual script is stored in the Target column of the CustomAction table.
0x30	Source is the Property name where the value of the property will be set by the set property action, Source column contains the script code for script actions, or for the EXE action the Source column is the property that contains the path of the EXE to run.

The Target column of the CustomAction table

The Target column is dependent on the major type of the CustomAction, reading the MSDN Summary List of All Custom Action Types will explain this column in more appropriate detail. Looking back to the Orca.msi file - the actions listed translate to the following:

• 0x23 - Set the directory listed in the Source column to the Formatted Text in the Target column.
• 0x33 - Set the property listed in the Source column to the Formatted Text in the Target column.

How and When is a Custom Action run?
Now that we know a Custom Action is either Immediate or Deferred, and can be or do just about anything, we need to answer the question "How does a Custom Action get fired off?" Entering a Custom Action into the CustomAction table really only makes it available to be called - so just adding a line in the CustomAction table effectively does nothing. There are three methods of firing off a Custom Action:

• In the sequence tables. This is probably the most common way of running a custom action, and the focal point of our discussion for the remainder of this article series.
  
• In the ControlEvent tables. Essentially this is the method to launch a Custom Action in response to a UI event such as a button click. On Windows Server 2003 or better, custom actions run this way cannot send messages with MsiProcessMessage() calls, however Session.Message() calls from the automation interface work just fine (technically, prior to Windows Server 2003 neither message API officially works). Obviously, the installation must be running in full UI mode to fire these off. The Custom Action type launched by this method must be an Immediate type - remember we should never alter system state in the UI phase. I'm not going to cover how to run an Immediate Action from a dialog here using ControlEvent, perhaps in a later article.
  
• By a call to Session.DoAction() or MsiDoAction(). This is a way of calling one Custom Action from another. Although this won't make sense until it is explained later on, you can not call a Deferred Custom Action in this manner unless it is called while the "installation script" is being written - but it should be OK to call it from a custom action scheduled between InstallInitialize and InstallFinalize. More on the "installation script" concept later.

The Sequence tables

Before we can discuss the primary way Custom Actions are launched, you need a better understanding on how MSI sequences work. We will get into this in more detail later in this article so I am handwaving some important details here for the sake of getting a basic understanding. The typical installation is kicked off by double-clicking the MSI. This causes the installation engine to begin processing the InstallUISequence table (The processing of this table is skipped entirely if the UI mode is set to "basic" or "no UI" - both Full and Reduced UI modes actually do process this table). There are other sequences such as the AdminUISequence and AdvtUISequence that all follow the same logic for administrative and advertised installations. Hopefully you still have Orca open, so look at the tables as I describe them and follow along - sort the table by ascending sequence number.

The InstallUISequence table is processed in the order identified by the Sequence column (starting at sequence number 1), executing each action listed(Standard, Custom, and Dialog), as long as the Condition column for that action evaluates to true or is null (empty). The negative values in this table are "jumped" to on termination of the setup based on the result code of the installation. Once the "ExecuteAction" action is encountered, the InstallExecuteSequence is run. When the InstallExecuteSequence is complete, control will return to process the remaining UISequence table or it will jump to the corresponding negatively numbered sequence based on the result code of the installation process. Every action in the *UISequence tables are run in the currently logged on user's process for security reasons, and this is known throughout MSDN's documentation as the "client" portion of the installation.

The InstallExecuteSequence is where things get interesting, and differs based on platform.

• On Windows NT based systems, this table is evaluated and run in a separate process from that of the User Interface. See my earlier article on Properties for information as to what is passed from the "client" (UI portion) to the "server" or "service" portion of the installation. To recap, the admin user has two processes owned by him/her, one is the UI sequence processing, and the second is the Execute sequence processing. The non admin user installing with elevated privlidges can have three processes - the same two as above, plus a third process, owned by the System, which executes the deferred
  msidbCustomActionTypeNoImpersonate actions.
• On Windows 9x based systems, both the *UISequence and *ExecuteSequence and all actions contained therein are run in the same process.

Actions in the *ExecuteSequence should only use UI interactions that use the Session.Message() or MsiProcessMessage() API's and not reference the Dialog table or contain UI's (such as MessageBoxes, status bars, shell progress indicators, dialogs from 3rd party libraries, etc.) in order to respect the UILevel wishes of the user.

Now or Later

Let's continue the discussion by distinguishing the Immediate vs. Deferred custom action categories a bit more. An immediate action is one that is "run" or "executed" immediately when the action is encountered in the sequence. A Deferred action is one that, when encountered in one of the Sequence Tables, is written to a sequential "installation script" with some metadata - you can think of this as a "To-Do list". Wherever you see the words "script" or "written to the script" in MSDN documentation, this is what I am referring to. More on deferred actions and scripts later - let's get the Immediate Custom Actions out of the way first.

Immediate actions have a method of assuring they will only be executed a set number of times - this is perhaps the most confusing page of documentation in the MSDN library. The Custom Action Type msidbCustomActionTypeFirstSequence will cause the action to not run in the Execute sequence if it already ran in the User Interface sequence. The msidbCustomActionTypeOncePerProcess flag is similar to the msidbCustomActionTypeFirstSequence flag, with the exception that it will run an action again in the Execute sequence if the Execute Sequence is being run in a different process than the User Interface process (In English - it will run in both sequences on NT machines, and only once on 9x based machines). The msidbCustomActionTypeClientRepeat flag means if you run the MSI in silent mode (and therefore don't have the UI sequence table processed) , the Custom Action wouldn't execute, but if you ran it in full UI mode it would execute. The lack of any of these flags causes the action to be run always. Remember that Immediate Actions should not modify the state of the system in any way. Deferred actions cannot have the properties described in this paragraph. Deferred Actions are "recorded" in what is called the "installation script" before anything is actually run/executed. The script is created in the *ExecuteSequence when the InstallInitialize action is encountered, therefore deferred actions can only be sequenced after this action. The only time an item is written to the script is if the Condition is true at the time it is to be written to the script (as indicated in the Condition column of the Sequence table). In reality, there are two scripts being generated, the "installation script" and the "rollback script". I'm going to treat it as if there is only one script for simplified understanding.

Deferred Actions and the script

Think of this example: The MSI Engine is going through each of the actions in the InstallExecuteSequence in order of the sequence numbers, when - blammo - it hits the InstallInitialize action. At this point, it creates a data structure known as the "script" and starts recording all actions that meet the condition specified in the Condition column and are marked as msidbCustomActionTypeInScript along with some magical metadata (In other words it only records deferred actions in the script). If an immediate action with a proper condition (that also is compliant with the multiple execution flag setting) is encountered, it runs immediately. Otherwise, it keeps adding stuff to the script until it hits an InstallExecute, InstallExecuteAgain, or InstallFinalize action is encountered. Ignoring InstallExecute and InstallExecuteAgain for now, when InstallFinalize is encountered, it completes writing to the script and seals it from further additions. Then it begins processing the script by executing the actions, top down. The details of how the list is processed and the effect of InstallExecute and InstallExecuteAgain is covered in a bit.

So, what exactly is this magical metadata mentioned above? We already know that the condition column was evaluated before the decision was made to write the action to the "script" - if the condition was false, the task was not written. As near as I can figure, this metadata holds three major things:

• The value of a property that having the same name as the CustomAction - the so-called CustomActionData property you have undoubtably heard so much about. Additionally, the ProductCode and UserSID properties are available in a Deferred action.
• How to Run it flags (derived from the Type column of the CustomAction table)
• The type of action (DLL, EXE, Script, etc.) and the path to the CustomAction code.
  
• Impersonation type - The flag msidbCustomActionTypeNoImpersonate will cause the action to run in the system context vs. the otherwise usual currently logged-on user context. The exception to this rule is a server with Terminal Services which normally runs actions in the system context unless the msidbCustomActionTypeTSAware flag is set (flag valid on Windows 2003 Terminal Server only).
  
• msidbCustomActionTypeAsync indicates that once the action is kicked off there is no need for the MSI engine to wait for it to complete before executing the next action. However, the MSI engine does want to know the return code, and as such will wait around at the end of the sequence until it finally returns if the action takes that long. All actions are synchronous unless this flag is set. Only EXE type custom actions can also combine the msidbCustomActionTypeContinue flag so that the installation can exit even while the Custom Action EXE is still running asynchronously.
  
• msidbCustomActionTypeContinue indicates that the exit code of the custom action is ignored - therefore the sequence will progress even if the return code indicates failure.


• When to run it flags indicates three possible things (again derived from the Type column of the CustomAction table). As briefly mentioned earlier there are actually two different scripts written - Commit and Rollback actions are both written to a separate "Rollback Script", but ignore this for now.
• "Normal Deferred" assuming nothing has failed and the list is being processed top to bottom - msidbCustomActionTypeTSAware or msidbCustomActionTypeInScript
  options without msidbCustomActionTypeRollback or msidbCustomActionTypeCommit flags
• "Commit" - Run after the entire (sealed) script is processed once successfully (After InstallFinalize is encountered and the complete script has been processed once successfully). Actions in this category have themsidbCustomActionTypeTSAware or msidbCustomActionTypeInScript combined with msidbCustomActionTypeCommit flags in the Type column. This is only written if Rollback is not disabled - more on this later..
  
• "Rollback" - if another deferred action failed, this will be run. This is only written for the msidbCustomActionTypeTSAware or msidbCustomActionTypeInScript
  when combined with msidbCustomActionTypeRollback actions, and only if Rollback is not disabled - more on this later..

How the Script is Processed

To recap, we have a "script" containing deferred actions along with some metadata that we started collecting when InstallInitialize was encountered in the sequence. We can potentially start processing the list before it is completely written (assuming a InstallExecute or InstallExecuteAgain was encountered prior to InstallFinalize in the sequence tables).

Processing always begins top-down, and there are up to three "phases" in the script processing based on the "when to run it" metadata described above.

First, only "normal deferred" actions are processed. Each deferred action is executed only once - if an InstallExecute or InstallExecuteAgain action was encountered in the sequence tables causing a portion of the script to be executed prior to the script being completely written, "normal deferred" actions already executed are skipped.

If an error is thrown during the execution of a "normal deferred" action, the processing of the list reverses and starts moving backwards from where it currently is processing, executing the "On Rollback" actions in the list. Rollback can be "turned off" at a system level, if this is the case, Rollback actions will not be written to the script, and will not be executed.

Assuming all "normal deferred" actions are successful, processing of the script begins executing at the top again, this time executing the "On Commit" actions. Retuening a failure from a Commit Custom Action will cause any previously written Rollback actions to be executed. Because this causes some interesting and practically impossible to test scenarios, it is important to write solid Commit actions that do not fail or also specify the msidbCustomActionTypeContinue flag in the CustomAction table. Rollback can be "turned off" at a system level, if this is the case, Commit actions will also not be written to the script, and will not be executed.

Dealing with Rollback and Commit

If you are familiar with database concepts, Windows Installer is transactional. In other words, a failure to install a MSI package should leave the system in the exact state it was prior to beginning the installation. As such, Rollback and Commit actions are a part of the lexicon of Windows Installer, and understanding this when writing a Custom Action is essential. Also essential is understanding that Rollback can be disabled on a system level, thus, Rollback and Commit actions are not executed.

To adhere to the Windows Installer "Best Practices," all changes that are made to a system are in a "deferred" action - as an example, the "InstallFiles" standard action is actually a deferred action under the hood. Although not apparent in this manner (nor is apparrant by looking at the Sequence tables), the InstallFiles "normal deferred" action creates a backup of all the files it replaces if Rollback is enabled. This way, if an error occurs, all the replaced files can be restored to their previous state if an error occurs in a later deferred action through the Rollback process. The Commit actions are only run after all the "normal deferred" actions are run successfully - and the MSI engine uses the Commit action to delete the Rollback files.

Because of their nature, Rollback and Commit actions cannot be asynchronous.

A "normal deferred" Custom Action should only save rollback information if the RollbackDisabled property is not set. If it is set, Rollback and Commit actions will not be run, and this will cause your saved rollback data to remain after the installation is completed. You will need to pass this data into your "normal deferred" CustomActionData property in order to check if you should save rollback information.

Other Considerations

Inside a CustomAction, you may need to evaluate if a patch or repair is occurring. Since deferred CustomActions do not have the ability to check properties (other than the few properties mentioned earlier), you need to use an Immediate action to check (and pass on to the deferred action via CustomActionData) the value(s) of REINSTALL, PATCH, and/or MsiPatchRemovalList properties. For more details, see the Windows Installer Team Blog's comments on the subject or Heath Stewart's post.

To determine if you should save Rollback information in your deferred action, you will need to do the same technique as above to pass the value of the RollbackDisabled property. Other properties of interest for deferred CustomActions (depending on what they do) is ALLUSERS, and possibly UILevel.

To handle user requests to cancel the installation in any custom action, make sure that you check the return value from MsiProcessMessage() (or Session.Message()) calls to handle the IDCANCEL return value. I will be showing examples of handling progress messages in future posts on this topic. In the meantime check out the Windows Installer Team blog entry on the subject.

Another tricky concept is scheduling a reboot, if required, from a deferred Custom Action. Normally, you can't! To work around this oversight you have several options. The one I use is creating a file on the filesystem that the user running the installation can have delete access to. This is where the ProductCode and UserSID properties available to a CustomAction come in handy. Find the temp directory of the user using their SID and write a file with the name "ProductCode_rebootme" there. In an immediate action scheduled after InstallFinalize, check for the existance of this file and if present, delete it and call MsiSetMode() to indicate a reboot is required.

MSDN provides a few pointers on security here and here. In my opinion, it is extremely difficult to author a "data secure" MSI. If you need to pass internally sensitive data to a deferred custom action, use encryption on the CustomActionData in addition to adding sensitive properities (and the name of the deferred custom action) to the MsiHiddenProperties and using the msidbCustomActionTypeHideTarget CustomAction type flag. It is possible to digitally sign an installer package and its cabinet files. It is trivial to circumvent these measures if someone wanted to - and in a typical administrative installation, the msi signing is removed anyway. Think about data security in an MSI as glass in a jewelry store - it only keeps the honest people honest.

If a Custom Action needs to use disk space (to install a database, for example), you need to author (or modify at run time) the ReserveCost table. This is keyed on the installation state of a component.

The use of COM in a CustomAction is fine - when a dll-based Custom Action runs, it is created on its own thread. There is some conflicting documentation on this, however. MSDN claims CoInitialize is called in a per-machine installation and is not called in a per-user installation. A post here (scroll through to the comments) indicates that CoInitialize and/or its brethren CoInitializeEx is not called on this thread. I like MSDN's advice to not quit if it is determined the thread is already COM initialized.

Terminal Server is special. Throughout this article I have mentioned the *TSAware flags. In a per-machine installation on a Terminal Server, actions not marked with this flag are run as LocalSystem, where on a non-terminal server system they will normally impersonate the calling user.

The way patching and upgrading is handled, and its effect on Custom Actions, is the subject of a future article in this series.

The Ten Cent Summary

Custom Actions can be very powerful, and can be run in a variety of different ways and at a variety of times. The important things to remember when deciding on how to design them are:

• Immediate actions are normally used to "set up" deferred actions (by stuffing CustomActionData) or to simply evaluate the state of a machine. Immediate actions are NEVER to be used to alter the state of a machine.
• Deferred actions come in three different flavors, and where you have one, you should have all of them - the "normal deferred", rollback, and commit. The "normal deferred" should save undo information on the system somewhere if rollback is enabled. The rollback action will use this undo information to restore the initial state of the machine. The commit actions will clean up the rollback's undo information. Deferred actions can only be included in the execute sequences between InstallInitialize and InstallFinalize.
• Rollback only occurs if an error is encountered while processing deferred actions (including Commit actions) between InstallInitialize and InstallFinalize in the *Execute sequences.
• Because the conditions of deferred actions (including commit and rollback actions) are evaluated at the time the script is written, the same condition should be used for the sister actions.
• Actions should be written to run correctly regardless of the UI mode and respect the wishes of the user when it comes to UI levels.
• Never use a nested installation custom action type.
• Understand the flags and options for scheduling and running actions as presented above.

Part II of this series will cover writing our first Custom Action in C++!

InstallScript and Enumerators

I was helping a coworker out today trying to figure out why a simple VB Script using WMI could not be "ported" to InstallShield's InstallScript. The reason turned out to be that InstallScript does not support handling enumerators - In VBScript, you can enumerate a collection using the "For Each" construct. In JScript, you have the Enumerator object. In InstallScript - sadly - you have nothing.

I started thinking that I may be able to create a DLL to handle this. I then thought that someone else likely has done the same. My Google-foo came in handy and I found a post by __EDITED___ that covers the topic quite well. I was able to easily compile his C++ code into a DLL and use it immediately.

UPDATE: Turns out that the link previously referenced above was pretty much a blatent copy of code previously submitted to Installsite.org. Thank you to the commenter for pointing this out.

In the deleted link above, the poster was complaining about certain InstallShield limitations. I agree with most of the comments in his post - InstallShield's help system is at least second-rate. The InstallShield books by Baker are nice to have around, but not everyone has this luxury.

I disagree with his comments that MSI is "limited." It certainly is not the "holy grail" of installation technology - and I doubt that this can even exist. MSI technology is extremely extensible, but this comes at a cost of understanding the design patterns inherent in it - which are vastly different than the "other" installation technologies. I know I mentioned this before, but using MSI technology could practically eliminate vendor dependence and ease the switch between authoring tools.

Unfortunately, the documentation for MSI technology is equally as poor as InstallShield's. Rumor has it (plus the Amazon ratings) that Phil Wilson's book on the subject is pretty good - if Brian will ever let me borrow his copy I can give it an official review. I will attempt to help out with this by (finally) publishing my series on Custom Actions over the next several weeks.

Avoiding Disaster

This post is a bit off the usual technical topic - I will be talking about the duo of hurricanes, impact on the victims, emergency response, pre/post emergency evacuation of large populated areas, your individual family emergency plan, and how to help. Although I am not currently active, I was a volunteer paramedic and firefighter, serving poor and middle-class neighborhoods for several years, so I do have some background in this area - but far from an expert on the subject. To my loyal readers, I have some technical content in the queue for later...

Impact on People

It looks like Hurricane Rita was not as devastating as was feared. Katrina, however, was a nightmare. Ignoring the evacuation problems, lets look at the issues someone who evacuated early will encounter:

1. Money. If you used a local bank, forget about getting cash from an ATM machine. As the banks were knocked offline, so was the ability of their patrons to access their money. Perhaps some distributed systems can be used in the future to alleviate this issue. In the meantime, I'd start depositing a good portion of my money in a nationwide bank or split assets between two banks housed on opposite coasts. Fortunately, lenders are claiming they are not going to report victims to the credit breuraus. Also fortunately, any cash you had in a banking institution should eventually be available.
2. Housing. I'd venture to say this is perhaps the worst - you come back to a slab where your house once stood. Jewelry, important documents, photos of your great-grandparents, etc. are now all gone. Even worse is the potential backups of this information stored at the bank or a family member's house are gone, too. Is insurance going to cover any part of the replaceable damaged items?
3. Job. Unless you work in construction, it could be a while before you can get your old job back. Hopefully, the owners of the damaged or destroyed companies will be able to rebuild at all. Without money, housing, or a job - I can't imagine surviving too well in today's society outside a log cabin house in the forest.
4. Attitude. While there are several personality types out there, the two I am looking at are the "society owes me" and "I'd never take a handout" type of people. Both of these extreme personality types will require a make-over. If the "society owes me" folks continue with this attitude (or possibly get it more ingrained), they will never recover - assistance programs will decrease as time goes on. The "never take a handout" folks will not be able to recover until they do get some external assistance. Unless you are in that log cabin house in the woods, you live in a society, and participation is a two way street. This reminds me about a old and now not-so-funny anecdote about a man stuck on his roof during a flood. Three rescue boats floated past and the man refused the assistance saying "God will save me." Eventually he drowns, goes to heaven, and asks God why he wasn't saved. God's response - "I sent three boats..."
5. Fixed income. These folks are the ones who tear at my heart-strings the most. In the previous paragraph I stated that "assistance programs will decrease as time goes on." These people are retired, and can't possibly rebuild their home, get a well-paying job (either because of age/health related issues or the fact that no company will hire them), or rely on long-term financial assistance. It would be nice to see a specific charity set up to help these people long-term who will soon be forgotten. Please leave a comment if you know of one.
6. Social Structure. Coming back from complete devastation, it is likely a significant portion of what used to be society is no longer there. Neighbors, friends, church members, etc. could have either died or given up on their old lives. The remaining social structure will be slow to recover and ineffective. Small communal groups will likely form inside the shattered society, and their establishment should be encouraged. I see faith-based church groups as the foundation of these mini-communes, as many of these organizations typically group together people of different skills to repair an elderly member's house in "normal times". These groups of people can utilize each member to their best potential to serve the needs of the group. This was the old "American Western Frontier" mentality, which is exactly what is needed in these areas today.

The other subset of people, who did not evacuate prior to the devastation have all the above issues, plus some others:

1. Mental scaring. I couldn't imagine being stuck in an attic with a gallon of water and a stale loaf of bread for a week - not knowing if I would eventually get rescued or not. Witnessing looting, fighting, and gunfire would put a damper on my ability to trust society when I do rebuild. Seeing bodies stacked on the sidewalk - unthinkable.
2. Mental boost. The word "news" was formed from the first letters of "North East West South". I have been thinking that the "N" now stands for "Negative". I have heard many stories about positive things occurring in the aftermath, but stories without images have a way of being forgotten - images of people shooting at rescue choppers don't. I'm sure that many (but hopefully most) people in the midst of this disaster had positive interactions with others of their own species.

There is also an impact on the part of society that was not affected at all by the hurricanes.

1. "How can I help" - I'm sure at least everyone in America has tossed at least a quarter in a fireman's boot for the relief effort. Unfortunately, this is not a very personal way of dealing with it. If this is as far as you have gone in the relief effort, shame on you. The money is needed later. Early on, the need was/is for water, housing, clothing, food, toiletries, sanitization supplies, ice, etc. The most effective assistance was immediate and non-financial. A local radio show got corporate and individual sponsors to get trucks full of various goods (from a specific list, donated by listeners) and convoy it to the affected areas. This was immediate assistance of exactly what was needed. Listening to the stories of the volunteers drivers in this effort brought me to tears - literally.
2. "I'm not helping those looters" - I can't believe I actually heard this one (while dropping off a donation of goods for the convoy...). Repeat after me - "Not everyone in this world is evil". Taking it one step further, that attitude is not going to help society become less evil.

Emergency Response

Without getting overly technical, the response to any emergency is the same. It requires knowledge (as early as possible in the emergency) such as:

• Where is the emergency? In cases of mass casualty incidents, where is the worst emergency so we can attack that first.
• What is the emergency? Each response team has a different one (the engineers' emergency was to plug up the levees, as an example), but all efforts are focused on saving lives first.
• What are my resources? This is people (rescue workers), equipment (trucks, boats, choppers), and supplies (water, medications, etc) - just to name a few.
• Access. How close can I get to the scene? Can I get other, possibly more critical, resources in later? Can I get victims out?
• Mitigation. If there is a chemical spill, do I have to worry about keeping it out of the creek? For a fire, we would want to protect the building housing the explosive materials more than other surrounding buildings. How do we stop an already bad situation from getting worse?

This is where the concept of disaster planning comes in. Every area has one. In Pennsylvania, we have a bunch of coal mines, so dealing with fires, subsidence, and rescue is in our plans, and it may not be in your community's plan. To create the plan, you take a risk analysis of different disaster types, and attempt to answer all the questions posed above for the highest risks in advance.

For example, if there is a poly-methyl-bad-stuff chemical manufacturing plant, we would know, in advance, of where to go, what to do, and who to call. This is easy. Keeping it up to date is hard. When a parking lot next to the plant gets converted to an office building, you have additional concerns of more victims and less access. Was the plan reviewed and updated with this new development? Usually, the answer is no.

Planning for disaster response on a large scale - like an entire city - is impossible. You just can't answer questions like the above in advance. For things like this, we rely on a list of resources. In my community's plan, we have several phone numbers for school bus and public transportation companies, heavy equipment companies, etc. If we need a drilling rig on Christmas Eve, we should be able to get one. Are these numbers and resources kept up to date? Likely - no. In a mass disaster situation, you do not have the resources to hunt down the current foreman of "Bob the Builder, Inc" to get a bulldozer to prevent one tragedy when there are 100 other tragedies going on at the same time.

This is where you, as an individual or business owner, can help. Contact your local fire department, and let them know what resources you have available, where they are located, and how to contact you or others that also have access to them. Notify them when this changes. There were cases where I wish I had an ATV or a snowmobile I can get quickly where it was rather difficult to get access or equipment to it. Ask what you can do in the event of an emergency to help out. Volunteer as a fund raiser or associate member of the fire and/or rescue squads to make sure these items are kept up to date and you and your community are protected. You don't have to go into a burning building to help save a life. Remember, after an incident starts, it is too late for planning.

Mass Evacuation

The infrastructure of all cities makes a mass evacuation impossible. Roads are designed (and in Pittsburgh, especially poorly) to manage the traffic of under 10% of the population using a major roadway on a daily basis. There is no way to manage this or mitigate it. Mass evacuations of cities will never go well. If you do have to evacuate, understand why you are evacuating - for a flood, if you can't get out, seek the highest natural ground or a flotation device. Have emergency packs where you keep items like water, non-email-based Spam, first aid products, sanitizers, blankets, maps, camping gear, and medical information/contact information tags for your family that they can wear, put in their pocket, or tape to their arms. You can grab this kit and go. Don't try to move that plasma TV to the attic and barricade the house from looters. Most people will try to get this stuff together before they leave. The earlier you leave the better.

Head for any area that is safe where you think other people won't think of to go. Going to the next major city where friends and relatives are is the first thing people think of. You can get to the friends and relatives later - for now get out of the danger zone and go where the route will be less crowded.

For businesses with large vehicles (trucks, buses, etc.) - make sure you know what to do before you get out in a mass evacuation. Where do you fit in the evacuation plan? Ask this ahead of time - you can be given a specific location to go to to pick up people and route to take when an evacuation is called. You are more likely to get assistance if you run out of gas if you are hauling maximum vehicle capacity of random people, than a car with one or two people full of useless stuff.

Your Family Emergency Plan

As a small kid in an amusement park, there was nothing more thrilling than being old enough where your parents let you go off on your own. Typically, you met at different times throughout the day at the same location so they knew everything was OK. But before you were old enough, I am sure your parents gave instructions as to what to do if you were separated - meet at the Merry-Go-Round, find an employee or security guard, etc. How many people have a plan if their house catches on fire? For something like Katrina? An earthquake?

There are plenty of sites that will help you create one. I'll leave it up to your Google-foo to find them. Here are some ideas to start you off:

1. Sinking Titanic, Flooding, injured by a large explosion, etc. - Lets say the worst has happened. You are with your family now - but you may get separated. If not by the incident itself, rescue workers will need to separate people based on the criticality of the injury. Make sure everyone has ID - this could be as simple as putting a drivers license or credit card in everyone's pocket, diaper, whatever. Better yet is a Sharpie marker or something indelible where you can write directly on the skin - name, DOB, SSN, important medical information, and a few phone numbers of people you know. Trust me - in this situation scrawling "Diabetic" on someone's forehead is a REALLY good idea. Remember - you may get separated from your ID, clothing, medical bracelet, etc - and in the worst case, you may not be able to communicate. Make sure everything a rescuer could need is available, not only to medically assist, but to reunite you.
2. Grabbing on to others. Same goes for tying a bunch of people together. In a water emergency, you may lessen the chances of both for survival. There are several techniques you can use, if you are in flood prone areas or like to boat, this is something you should research. I like the "The Worst-Case Scenario" series of books - they are humorous to an extent, but contain real and practical information. They are great coffee table type books to have around and page through, as an added bonus.
3. Have a series of phone numbers handy, and on your kids at all times - not just in an emergency. Have not only the numbers of the local relatives, but the long-distance ones too. Explain that you are to call as many of these people as you can with your location to make reuniting easier. Cell phone numbers, although nice, are useless in a mass emergency.

Helping Out

Before donating, see if your company, like mine does, matches donations - then pick the best one from the list. Organizations that rate charities such as Charity Navigator are helpful. Remember that there is always overhead with these organizations, so try to get the most bang for the buck with your donation. Even better is to call a few local church groups and see if they are tied into a group in the affected areas with specific needs. Go out and buy these needs, and ship them down there. This way, 100% of your donation is being utilized.

My heart goes out to all the victims of this disaster, and to the families who lost loved ones. God bless them, and protect them.

Trouble ahead for time computations?

I was just reading an article about the new U.S. Energy Bill that intends to extend Daylight Savings Time an additional month (starting in 2007). I wonder what the impact of this is on the Computer Science front. There has not been any chatter on my normally read blogs, but perhaps there will be soon. I have no facts to back up my theory here, but lets play along with my conspiracy theory and possibly learn something about static and dynamic linking of DLLs.

Think about this from the Microsoft C/C++ developer perspective: the date functions are implemented in the C standard library, MSVCRT.DLL (or its post VC6 brethren MSVC*.dll). Lets assume (although I am guessing) that the "rules" for the current daylight savings time are implemented in this same DLL (NOTE: Please see comments). One of these functions is called mktime(). Let me quote from MSDN:

When specifying a tm structure time, set the tm_isdst field to 0 to indicate that standard time is in effect, or to a value greater than 0 to indicate that daylight savings time is in effect, or to a value less than zero to have the C run-time library code compute whether standard time or daylight savings time is in effect. (The C run-time library assumes the United States's rules for implementing the calculation of Daylight Saving Time).

So if we developers assumed that the runtime would take care of conversions for us, and we statically linked to the library, we may have to recompile against a newer link library (with the revised code) for our applications to continue working if this change actually happens. On the other hand, had the developer dynamically linked to this DLL and not copied the pre-dst-updated MSVCRT.DLL to the application folder or application current directory (Remember that in Windows Server 2003 and possibly Windows XP the rules have changed), the DLL can be updated once in the system32 directory (perhaps through Windows Update) and our preexisting applications will be none the wiser and work just fine with the change.

This is more food for thought on the debate of static vs. dynamic linking that could help sway some developers into a different line of thought - I prefer dynamic linking, but in some cases for some applications I do not practice what I preach. For the installation folks, please read the previous link (and the comments - good stuff there on merge modules) - this is why you need to be sure that you are following proper version replacement and marking shared DLL's as shared - otherwise you can cause grief for other applications or your own.

[UPDATE: 10/4/2005 - fix formatting and errant character]

All About Properties

Late last week an anonymous poster commented it has been a while since my last blog post. I'm going to attempt to make up for it with this rather long post as the first in a short series on MSI Properties. Newbies to MSI technology have a difficult time understanding them, and even experienced setup developers get burned by forgetting something. Let's start by looking at some of the basic properties of, well, Properties.

Properties are sort of like variables. Properties cannot have spaces in their name and must begin with a letter or underscore. All properties can be defined in the Property table or set by other mechanisms – via AppSearch, Custom Actions, dialog control elements, etc. They have scope: Public, Private, and Restricted. Cosmetically, Private properties have lower case letters, Public properties are all uppercase. Under the hood, there are plenty of differences. I am going to ignore the Win9x and Terminal Server aware differences and concentrate on the NT based MSI engine.

We first need to cover something I should have covered in an earlier blog post – the MSI engine's UI phase and execution phase. The UI phase (sometimes also referred to as the 'acquisition phase') is carried out in the current logged on user's context. The execution phase (sometimes also referred to as the 'server process' or 'server side', or simply 'service' – lets hear it for MSDN documentation consistency!) is carried out in a completely different process (or processes). This is pretty easy to see for yourself – write a custom action that pops up a message box with the current process ID and run it in three different contexts – UI (Immediate), Execute (Immediate), and Execute (msidbCustomActionTypeNoImpersonate + msidbCustomActionTypeInScript). If you are an administrator, you will notice that the UI action runs in one process and the execute actions run in a different process – all owned by the interactive user. If you are a non-admin user, you will note that each of the three actions run in their own separate process, with the difference being the "NoImpersonate" action, which runs in the SYSTEM context.

Back to the property discussion – Private properties have lower case letters as stated earlier. They cannot be passed into an installation via the command line method or modified by transforms. Predefined Private properties may be set by the MSI engine – see "Property Reference" in the MSI docs for a list of properties set by the MSI engine automatically. Private properties can be changed by Custom Actions, although you likely do not want to change one of the predefined private properties. One last important distinction is that changes to private properties are NEVER passed from the UI phase to the Execution phase. Although there may be a reason to use a Private Property for something, I have never created a private property for use in an installation.

Public Properties are a bit more useful. There is a slight difference between Public and Restricted which I will cover next. For the purposes of this paragraph, treat them as synonymous. Public Properties must contain all uppercase letters. They can be set via the command line and modified by transforms. Public properties CAN be passed into the execution phase, and the key word here is CAN (more on this later). Also, values of properties are NEVER passed from the execution phase back to the UI phase when the execution phase is done processing – so if the value of a property is changed in the execution phase, it is not reflected in the UI phase afterwards.

Restricted, or Restricted Public Properties, are Public properties with the distinction being purely based on system or user state. Looking at an out-of-the-box Windows installation and a generic template MSI installation the following statements apply: If you are an administrator running an installation, properties WILL be passed to the execution phase (Restricted public property behavior). If you are not an admin user, most public properties WILL NOT be passed to the execution phase (normal public property behavior). If you want ALL properties set in the UI phase to pass to the execute phase (i.e. you want all public properties to be restricted), enter a property into the property table "EnableUserControl" and set it to "1". This setting can also be set as a system group policy by a network administrator. Alternatively, each property that you want to allow to be passed into the execution phase (made Restricted) can be specified in another entry in the property table called "SecureCustomProperties" which is a semicolon delimited list of public properties. By default, some properties are set to be restricted, see the "Restricted Public Properties" list in MSDN. This concept is a bit confusing, as the "Restricted" properties are the ones allowed to transition from UI to execute phases, even though you may think the opposite when first hearing the term.

The concept of "Restricted Public Properties" is rather important for your installation to work if installed by a non-admin user via group policy style deployments. It is highly advisable to test your installation for this deployment type by creating a local admin user and setting both HKLM and HKCU Software\Policies\Microsoft\Windows\Installer "AlwaysInstallElevated" (DWORD) to 1. Then take the user out of the admin group. This will have the effect described above. Test your installation in this configuration to make sure it functions correctly.

There are more fun tidbits about properties…

First, all entries in the directory table are accessible as properties. Therefore, be sure not to run into naming clashes when determining your property names. Be sure not to rely on the directory properties until after CostFinalize has been run.

Some properties, if authored into the Property table, result in an ICE validation warning. The documentation for ICE 87 explains some of them. Other properties in this table are validated with ICE 05, ICE 16, ICE 24, ICE 74, ICE 80, ICE 86, ICE 90, and ICE 99. I found it useful to review all the ICE's when learning MSI, since it locks in the "don't do this" mentality before you try something and it later fails...

You can set the "MsiHiddenProperties" Property to a list of semicolon delimited properties that should not be placed into the install log. This only works on MSI 2.0 or greater schemas, and is really not a good means to secure vital information, such as passwords or product codes.

Many Properties (and several Windows Installer API's) are not available to a custom action running deferred. To pass a property to a deferred custom action, use a type 51 custom action to set a property with the name of the deferred custom action you want to pass data into, sequenced prior to the deferred action in the execute sequence. In the deferred custom action, you can access this property by getting a property called "CustomActionData". Since you typically need to pass more than one property to a custom action, the technique of stuffing a bunch of properties together and later separating them is commonly used.

Any property value that is changed during the installation process is not preserved or persisted – thus, properties that were set during installation are not present when uninstallation occurs. IMHO, not providing a built-in persistence mechanism is a serious oversight made by the MSI team.

Speaking of persistence, the "AdminProperties" property is one way to persist a property – albeit only during an administrative installation. To allow this behavior, add the property you wish to set into a property called "AdminProperties" in the usual semicolon delimited list manner. When a user runs an installation after it was deployed to an administrative installation point, these properties are loaded with their saved values – a good easy way to provide default values specific to an enterprise without developing a transform.

The last important thing to realize about properties is their "Order of Precedence". Essentially, this describes when a property is set. I'm going to list these in the reverse order as MSDN does, as it makes more sense to do so. A property can potentially start its life as an entry in the Property table. If a transform was applied to the MSI, this will change what was described in the Property table. Next, the saved properties from an administrative installation that were listed in the "AdminProperties" property are restored. If anything was specified on the command line, those properties are used. Finally, operating system properties are set. To illustrate by example, if you declare property FOO to be "prop table" in the property table, then run the installation from the command line by "msiexec /I test.msi FOO=cmdline" FOO will be set to "cmdline" since the property is set by the command line AFTER it was set by reading the property table.

My next blog entry will discuss some techniques to persist properties and their data across installation sessions.

Installing an Internet Explorer ActiveX Control Part II

In part I of this article, I expressed concern over the various methods of installing an ActiveX control normally distributed and/or updated in a CAB file via Internet Explorer. This follow-up post addresses some concerns of a commenter to that last post, and describes what my solution was.

The comment made by Troy was from the perspective of a repackaging solution. Troy is quite correct - using pre and post installation snapshots will grab the changes to the ModuleUsage subkey. However, this solution fails to achieve the other goals for this particular installation. We still have the issue of a later update coupled with the MSI repair (or self-repair) operation. A point I failed to mention but Troy unintentionally reminded me of is compatibility across versions of IE. With the type of software this is, it may have a shelf life that would include IE7. Are the changes made to the system under IE6 applicable to all versions of IE under all OS's? I don't know. Using the API to install the control alleviates most (but not all) of the potential future incompatibility concerns.

I especially like how he disliked option #3 - changing the IE security settings to assure a successful installation, calling the API, and resetting them. I laughed as I wrote this option, as I could not imagine anyone doing this. In the middle of last week, I came across the "Get In the Zone" section of an issue of "Web Team Talking." They actually suggest and provide code for doing just that - although in a different context for a slightly different reason. I happen to agree with the KISS directive - "Keep it Simple, Stupid" - but sometimes to assure a successful operation you need to handle the corner cases.

The last part of his comment - "[this is] why many enterprise customers choose to repackage installations from ISVs" is a completely different blog post. I cannot tell you how true this statement is - and it is usually caused by setup developers, either intentionally or unintentionally. I'll add this one to the list of future topics for sure.

For the sake of discussion we were using the Crystal Reports Web Viewer which can generically be replaced with any properly signed cab file that works in the normal deployment mechanism of IE using the OBJECT tag. I have not tried this with unsigned controls, but I tested the approach using Macromedia's Flash player. You can play along by visiting the Macromedia's Flash download page and getting the CLSID from the OBJECT tag in the page's source. I then downloaded the swflash.cab file from the codebase attribute of the object tag and stored it on my local disk. The example below is going to use this flash cab file and the flash Class ID. Additionally, I am going to assume the reader is familiar with COM, C++, and MFC. The code is a bit lengthy to post here, but using the steps below a reasonable Windows developer should be able to complete this exercise in an hour or two.

I chose MFC since we need to implement IBindStatusCallback. This is easily accomplished by deriving a class from CCmdTarget. Make sure the implementations of QueryInterface(), AddRef(), and Release() call the External...() base class implementations. GetPriority() and OnLowResource() can simply return E_NOTIMPL. All the other methods can return S_OK. Since this is an async callback we need to have an event handle member variable, initialized in the Constructor, and have the event set in the OnObjectAvailable() method. That's the essential plumbing for the callback class. The callbacks for download progress can be implemented for the progress bars in the MSI.

Before we continue, let's make sure we have all the data we need to install the control.

• The class id of the control is {D27CDB6E-AE6D-11cf-96B8-444553540000}. It needs to be in this format as a string (with the braces) so we can call CLSIDFromString to convert it to a CLSID type.
• We are going to use major and minor versions of 0xFFFFFFFF to assure it is always installed.
• Finally, we need a codebase - or place to "download" the cab file from. Since we are installing the cab file locally, the CA needs to be appropriately place in the sequence and we need to get the local path to the file. The path needs to be in appropriate format - for a local disk where the file is at C:\swflash.cab, we need to make it file://c:\\swflash.cab

The entry point code needs to hook up the plumbing - instantiate the IBindStatusCallback implementation class, call ExternalQueryInterface() on it to get the interface pointer. Then we need to create and register the binding context by calling CreateBindCtx() and RegisterBindStatusCallback().

The meat of what we are doing is a call to CoGetClassObjectFromURL() with the parameters described above. The two common returns from this call will be
MK_S_ASYNCHRONOUS, S_OK, or an error. If S_OK is returned, the object is already installed. If the async value is returned, we need to loop until the event in the callback class is set or some predefined timeout elapses. After the event is set, check to see that the object was created based on what was set in the OnObjectAvailable() method.

Based on testing, this method appears to work all of the time, regardless of the various IE security zone settings. This is likely due to using the file:// protocol. Remember that we are dealing with a signed control - with unsigned controls, your mileage may vary. This method was not tested in IE with Server 2003 in Enhanced Security Configuration, so all bets are off there as well.

If you wish to have the installation always grab the "latest" version of the code from a URL, you will need to implement the code to change and restore the IE security settings from the article linked to above and also implement the download callbacks to move the MSI progress bar. Be sure to alert the user that you will be temporarily altering the IE security settings, and make sure when handling a cancel button press from the MSI that you restore the settings. This particular corollary to the problem can be useful if you want to refresh the clients using a simple repair/maintainence/reinstall option after the server-side control was updated without having Bob the network admin do much extra work (or having to release client side patches).