MSI Tip: How to Reuse a CustomAction for Deferred and Rollback

Neil Sleightholm recently asked how to tell if your in a rollback custom action using C#/DTF. The answer is simple.

Let's suppose we want to export one custom action method and make it multipurposed. In other words, if we call into while deferred execution we should do one thing but if we call into it for rollback execution we should do another.

How would we do that? The answer is in the BOOL MsiGetMode( __in MSIHANDLE hInstall, __in MSIRUNMODE iRunMode) Windows Installer function exposed by the Session.GetMode( InstallRunMode installRunMode ) DTF method.

Consider the following WiX Code:

    <Binary Id="CustomActionModeTest"

            SourceFile="PATH_TO_DLL.CA.dll "

    </Binary>

    <CustomAction Id="RollbackCA"

                  BinaryKey="CustomActionModeTest"

                  DllEntry="CustomAction1"

                  Execute="rollback"

                  Impersonate="yes">

    </CustomAction>

    <CustomAction Id="DeferredCA"

                  BinaryKey="CustomActionModeTest"

                  DllEntry="CustomAction1"

                  Execute="deferred"

                  Impersonate="yes">

    </CustomAction>

    <InstallExecuteSequence>

      <Custom Action="RollbackCA" 

              After="InstallInitialize">

      </Custom>

      <Custom Action="DeferredCA"

              After="RollbackCA">

      </Custom>

    </InstallExecuteSequence>

You'll notice we have 2 custom actions pointing to the same exported function in the binary table. Also notice that one custom action is scheduled as deferred and the other rollback. The deferred is scheduled right after the rollback. This results in Windows Installer scheduling RollbackCA after InstallInitialize and DeferredCA after RollbackCA.

Now let's look at the code inside of that Custom Action.

using System;

using System.Windows.Forms;

using Microsoft.Deployment.WindowsInstaller;

namespace CustomActionModeTest

{

    public class CustomActions

    {

        [CustomAction]

        public static ActionResult CustomAction1(Session session)

        {

            ActionResult result = ActionResult.Success;

            if (session.GetMode(InstallRunMode.Scheduled))

            {

                MessageBox.Show("I'm not in rollback, let's cause one to occur!");

                result = ActionResult.Failure;

            }

            if (session.GetMode(InstallRunMode.Rollback))

            {

                MessageBox.Show("We are now in a rollback." );

            }

            return result;

        }

    }

}

At runtime, RollbackCA is skipped and DeferredCA is executed. The CustomAction1 method will be executed by the DeferredCA and it will detect that it's scheduled in deferred mode and display a message saying that it's not in rollback and that it'll cause one. It does so by returning a failure to Windows Installer. Now MSI starts walking the script backwards executing any rollback CA it finds. This causes it to run RollbackCA and once again we are inside of the CustomAction1 method.

This time we will evaluate that we are in rollback, display a message stating so and quit gracefully. At this point the product is not installed.

This pattern can be extended so that CustomAction1 also handles immediate execution, implicit scheduling of the deferred custom actions and CustomActionData serialization/deserialization. But I'll leave that for another blog.

MSI Tip: Authoring an ICE using C# / DTF

I once wrote an article for InstallShield entitled "MSI Tip: Authoring a Custom ICE using InstallShield 2008". The article can be found here. [Warning: PDF]
In the article, I demonstrated how to write a unit test that could find evil script custom actions. While there is value and humor in doing so, the real point of the article was to demonstrate how InstallShield's refactored InstallScript language could be used to write ICEs.

While InstallScript is certainly an improvement over C++ in terms of cutting down on the line noise and complexity, the difference between C++/InstallScript and C# is nothing short of amazing. As such, I've created a sample project demonstrating how to author ICE's using C#/DTF and Stefan Krueger of InstallSite.org is kind enough to host it for me here.

Consider the following snippet from an MSDN sample demonstrating how to write an ICE in C++:

#include <windows.h>

#include <stdio.h>

#include <tchar.h>

#include <strsafe.h>

#include <MsiQuery.h>

///////////////////////////////////////////////////////////

// ICE01 - simple ICE that does not test anything

UINT __stdcall ICE01(MSIHANDLE hInstall)

{

// setup the record to describe owner and date created

PMSIHANDLE hRecCreated = ::MsiCreateRecord(1);

::MsiRecordSetString(hRecCreated, 0, TEXT("ICE01\t3\tCreated 04/29/1998 by <insert author's name here>"));

// post the owner message

::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecCreated); 

// setup the record to describe the last time the ICE was modified

::MsiRecordSetString(hRecCreated, 0, TEXT("ICE01\t3\tLast modified 05/06/1998 by <insert author's name here>"));

// post the last modification message

::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecCreated);

// setup the record to describe what the ICE evaluates

::MsiRecordSetString(hRecCreated, 0, TEXT("ICE01\t3\tSimple ICE illustrating the ICE concept"));

// post the description of evaluation message

::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecCreated);

// time value to be sent on

TCHAR szValue[200];

DWORD cchValue = sizeof(szValue)/sizeof(TCHAR);

// try to get the time of this call

if (MsiGetProperty(hInstall, TEXT("Time"), szValue, &cchValue) != ERROR_SUCCESS)

StringCchCopy(szValue,  sizeof("(none)")/sizeof(TCHAR)+1, TEXT("none"));// no time available

// setup the record to be sent as a message

PMSIHANDLE hRecTime = ::MsiCreateRecord(2);

::MsiRecordSetString(hRecTime, 0, TEXT("ICE01\t3\tCalled at [1]."));

::MsiRecordSetString(hRecTime, 1, szValue);

// send the time

::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecTime);

return ERROR_SUCCESS; // allows other ICEs will continue

}

With DTF and a little OOP ( Object Oriented Programming ) this can be reduced to the following snippet in C# / DTF:

using DE.TestFramework;

using Microsoft.Deployment.WindowsInstaller;

namespace DE.Tests

{

    partial class ICE01 : TestBase

    {

        [ICETest]

        public void TestExample()

        {

            Publish( ICELevel.Information, "Created 04/29/1998 by <insert author's name here>");

            Publish( ICELevel.Information, "Last modified 05/06/1998 by <insert author's name here>");

            Publish( ICELevel.Information, "Simple ICE illustrating the ICE concept");

            Publish( ICELevel.Information, "Called at " + Session["Time"] );

        }

    }

}

That may not seem like a big deal but consider the flexibity a few overloads can provide:

public void Publish(ICELevel iceLevel, string Description)

public void Publish(ICELevel iceLevel, string Description, string HelpLocation )

public void Publish(ICELevel iceLevel, string Description, string HelpLocation, string Table, string Column, string PrimaryKey)

public void Publish(ICELevel iceLevel, string Description, string HelpLocation, string Table, string Column, string[] PrimaryKeys)

Of course the real power comes from DTF's awesome interop classes. Going back to example the of detecting script custom actions in InstallScript, here is what it would look like in C# / DTF:

using DE.TestFramework;

using Microsoft.Deployment.WindowsInstaller;

using System;

namespace DE.Tests

{

    partial class ICE_DE_10

    {

        [ICETest]

        public void TestForScriptCustomActionsAreEvil()

        {

            Publish(ICELevel.Information, "Searching for Evil Script Custom Actions...");

            using (View view = Session.Database.OpenView("SELECT `CustomAction`.`Action`, `CustomAction`.`Type` FROM `CustomAction`"))

            {

                view.Execute();

                foreach (var record in view)

                {

                    string customActionName = record.GetString("Action");

                    int type = record.GetInteger("Type") & 0x00000007;

                    CustomActionTypes customActionType = (CustomActionTypes)type;

                    if (customActionType.Equals(CustomActionTypes.VBScript) || customActionType.Equals(CustomActionTypes.JScript))

                    {

                        Publish(ICELevel.Error, 

                            "Found Evil " + customActionType.ToString() + " Custom Action " + customActionName,

                            "http://blogs.msdn.com/robmen/archive/2004/05/20/136530.aspx",

                            "CustomAction",

                            "Action",

                            customActionName ); 

                    }

                    else

                    {

                        Publish(ICELevel.Information, "Found Nice Custom Action: " + customActionName + " Type: " + customActionType.ToString());

                    }

                }

            }

        }

    }

}