Doctor Deploys Blog

As I noted a few months ago, the Windows Installer is a declarative installation engine not a procedural installation engine. That means if you are going to extend the installation engine (which is what custom actions essentially do) then you should follow the same principles the engine follows. Namely, your custom action should read data out of a table and act based on those declarative instructions.

Let me give an example. Let’s say you want to protect some user input (maybe a password) using DPAPI.* Your first thought should be, “What are the inputs to my custom action?” Those inputs are the columns for your custom action’s table. In this case, one column would contain the value to be encrypted (Formatted so the value of a Property could be encrypted). Another column would provide the optional entropy value (that helps further randomize the protected output). A third column would specify whether the value will be protected for the current user or as the local machine account (limiting the set of users that can decrypt the data). A final column would specify the name of the Property to output the encrypted value to.

Then you would write your custom action to read each row out of the table with those for columns and call the ::CryptProtectData() API filling in the appropriate parameters. By acting on the data from the custom table, we call your custom action a “data driven custom action”.

Those of you whose first instinct was to say, “Oh, I’ll just write the code to get the value of a property called FOO and call the ::CryptProtectData() function with a bunch of parameters and write the value back out to a property called BAR.” should go back an reevaluate all of the custom actions you’ve ever written. This type of custom action is what we call a “procedural custom action” and it is inferior to the data driven method. Unfortunately, to most developers procedural custom actions are also the most intuitive way to write code (because that’s how most code is written).

Data driven custom actions are better than procedural custom actions for many reasons. as noted in the beginning, data driven custom actions follow the same declarative model that the rest of the Windows Installer follows. That means you fit into the rest of the installation system appropriately

One example is that data driven custom actions can be affected by transforms. You might think, “Oh, well I don’t support administrative customizations so I don’t care about transforms.” That might be true but the most optimal form of patching uses transforms to affect the package. If your custom actions are not data driven, your transform must patch the custom action binary directly and that creates a much larger patch.

Data driven custom actions are also reusable. Another developer can use your custom action without modifying the code because the inputs all from from a table. The custom action library that comes with the WiX toolset works just like this. We write the actions to configure things like Users, FileShares, Web Sites, Virtual Directories, SQL Databases, etc and you can reuse those actions by providing your own data. Data driven custom actions paired with the extension model in WiX provides a very powerful platform for installation.

Data driven custom actions are also more transparent than procedural custom actions. Going back to the WiX toolset Web Site example. If you look at the tables in the MSI after adding a WebSite element it is very possible to predict what the installation is going to do. Procedural custom actions hide the data and the actions in the compiled code (you don’t write script custom actions do you?). Admittedly, the data driven custom actions still have code in a black box but well written data driven custom actions can be quite transparent. Take a spin through the WiX custom action library if you don’t believe me.

Now I wanted to say that *all* custom actions should be data driven from a table but there are some rare cases where it doesn’t make sense. The custom action at the end of the install that launches your “readme.txt” through a ::ShellExecute()Â may just need a simple property passed to it (that’s how the WixShellExec custom action works today).

However, any custom action that modifies system state (see #3 in my list of custom action classes) should definitely be a data driven custom action to participate in the installation transaction well. After I do an example of a data driven internal-only custom action (#1 from the list), I’ll dive into system modification custom actions and further demonstrate why they should be data driven.

Anyway, that’s a long blog entry that basically says, “If you have already failed and determined that you need a custom action, make sure you make it data driven.”

Â

* Yes, I am going to walk step by step through this example at some time in the future.

Â

Original post by Rob Mensching

The title of this blog entry is a concept that I kept trying to sneak into one of my earlier posts on this “Zen and the Art of Custom Actions” thread.  I finally gave up trying to make it a bullet point and now here we are.  What convinced me that there was a full topic to be covered was when I realized I meant two things when I said “Custom actions are (generally/typically) an admission of failure.”

First, as a setup developer you really shouldn’t have to write any custom actions*.  I know a lot of people think writing custom actions is more fun than simply declaring everything that needs to be installed.  However, custom actions are invariably more error prone than the native engine functionality.

There are three common reasons custom actions are introduced.

a.  The setup developer wrote a custom action that was already supported by the underlying engine.  This is essentially reinventing the wheel with a less stable solution.  Invariably this comes down to lack of documentation or lack of effort on the developer’s part.  Either way a failure to use the most optimal solution.

b.  The setup developer wrote a custom action to address some complexity in his or her application.  As I have noted a great many times before, setup is “where the rubber meets the road” for the first time for most applications.  When issues arise often there is pressure to just solve the problems in setup rather than go back and fix/simplify the application.  Often deciding to complicate setup will lead to more fragile solutions than if the application had just been updated.  Either way the failure is often rooted in a poor design.

c.  The setup developer wrote a custom action to configure some platform because the platform technology didn’t provide installation primitives for itself.  This one is just sad and, unfortunately, happens more often than not.  My favorite platform to pick on is the Internet Information Services or IIS.  The ever popular platform for ASP.NET that hosts a great many web sites around the globe provides basically no mechanisms to enable install, uninstall, rollback, upgrade and patching of web sites, virtual directories, app pools, etc.  The platform failed the setup developer.

There is a variation on c. where the setup developer wrote a custom action because his or her authoring environment doesn’t support all the functionality of the installation engine.  In this case, I would encourage the setup developer to find a better authoring environment.

The second reason I say, “Custom action are an admission of failure” is that if you have a custom action then you are far more likely to have installation failures.  Having written a great number of custom actions for the WiX toolset (to try and help address c. above) I can assure you that getting the code right in all cases (especially patching) is extremely difficult.  If you look at the last bugs in WiX v2, you’ll find they have all been custom action issues.  An installation package with no custom actions is far less likely to fail than a package with custom actions.

So, ultimately, I would encourage all setup developers to be very skeptical about custom actions and continually work to reduce the amount of custom code in your installation package.  There are few setup experiences more stable than an application that simply needs a bunch of files installed.  Get in the habit of questioning the value of every setup requirement beyond copying files and you may be surprised how stable things can be.  You’ll also be quite a few steps down the path of Zen and the Art of Custom Actions.

 

* Note: when I talk about custom actions in this blog entry (and most blog entries) I do not mean the simple Type 51 property assignment operations that are technically defined as a custom action in the Windows Installer.  Type 51 custom action are rarely the cause of an installation failure (although you can certainly cause failures by assigning the wrong thing to the wrong place at the wrong time).

 

Original post by Rob Mensching

Continuing the Zen and the Art of Custom Actions thread, I thought I’d post a mostly formed thought.  When I’m presented with the need to write a custom action I often mentally classify the work into one of three or so different buckets.  Now, I’m not sure the ideas presented here in capture exactly everything the way I want but it seems like a decent place to start discussion.  So, on with the classifications.

1.  Internal-only custom actions.  This class of custom actions operates purely on data available inside the MSI database.  Assigning a Property the value of another Property is a simple internal-only custom action.  A custom action that reads some table in the MSI and populates some other table with temporary rows is also an internal-only custom action.  Internal-only custom actions are usually easier to design and implement because their data is contained completely within the MSI itself.  Since internal-only custom actions do not interact with the “outside world” (i.e. anything on the machine) they usually have very few dependencies.

2.  Read-only custom actions.  This class of custom actions reaches out on to the machine to gather data for some other process of the install.  Usually, read-only custom actions access some data store (registry, SQL database, file system) and populate a Property or some table inside the MSI for later processes to act on.  These custom actions are usually a bit more complex than the internal-only custom actions because you have to think about what user context you are accessing the machine with (Local System or the installing user that is elevated or not).  Read-only custom actions also have to be robust to handle whatever circumstances they might find on a user’s machine.  Basically, there are a lot more unknowns when you start to reach outside of the MSI database and the code often has more dependencies that can fail.

3. System modification custom actions.  This class of custom actions is by far the most complex custom action to write.  These are the custom actions that go out and change some state on the machine.  They do all kinds of things from creating registry keys (bad, use the Registry table) to writing ACLs (yeah, I know the LockPermissions table sucks) to updating the IIS metabase (that’s what the standard WiX IIS CustomActions do) to talking to SQL Server (WiX SQL CustomActions can do much of that) to changing any other number of bits on the user’s machine.  System modification custom actions are difficult because they not only have to consider the context they are operating in, they usually have to be deferred (which is a fascinating set of future topics).  On top of that, system modification custom actions need to think about what they do to the machine when installing, uninstalling, repairing, patching and rolling back all of those operations.  Needless to say, designing, developing and testing system modification custom actions is a very onerous process.  I dread having to write a custom action that modifies the system state.

Anyway, that’s the three major classifications of custom actions that I typically consider.  There are probably different ways to split the classifications.  For example, launching a program at the end of the install is something that I would consider a read-only custom action or a system modification custom action depending on whether the launched application modifies system state.  In any case, these buckets tend to capture most of the concerns I immediately think about when the need for a custom action arises.

We’ll talk about custom actions more later.  Eventually, I’ll even get around to writing code or dissecting existing custom action code.

 

Original post by Rob Mensching

I have been asked a great many times to talk about how to create Windows Installer custom actions.  Each time I’ve dismissed the request noting that it would take tons of time to organize my thoughts on the topic and actually write them all down.  I just don’t have that kind of time.  Besides, I gave up trying to create comprehensive blog entries a long time ago.

So, I’ve decided to compromise and at the same time test Technorati’s search-ability of tags here.  What I’m going to do is write random topics about creating custom action and use the tag zataoca.  There will be no series here.  One blog won’t necessarily follow logically from another.  Each topic will stand alone and hopefully the search engine will be able to tie the body of knowledge back together again.  It seems everyone searches for everything now anyway, so let’s see how far we can push it.

If you didn’t guess, zataoca stands for “Zen and the Art of Custom Actions” a title borrowed heavily from the incredible book Zen and the Art of Motorcycle Maintenance.  If you have never read that book, do so.

Speaking of things to I highly suggest reading, the following are a few links to custom action topics to get you in the mood.

1.  MSI SDK Topic about Custom Actions

2.  My blog entry why Script Custom Actions suck

3.  Heath Stewart describes another reason why Script Custom Actions suck

Until next time, keep coding… you know I am.

 

Original post by Rob Mensching