Events and Actions
This is the third part of a series on using Wix 3.7 with
Visual Studio 2012. Previously I walked through the Wix tutorial (http://wix.tramontana.co.hu/tutorial/
) from “Getting Started” through “Putting it to Use” and then through the User
Interface section from “First Steps” through “New Link in the Chain” to add
some user interface dialogs including a custom dialog to our installer. Now I
want to walk through creating a custom action to our install sequence.
Queueing Up
The Windows Installer runs through a series of actions
specified in the .msi database. The tutorial mentions using the .msi editor
Orca to investigate the sequence. Orca is a must-have tool for doing installer
development. WiX has four tags to change the sequence of the events, suppress
events and add additional events including custom ones: AdminUISequence,
AdminExecuteSequence, InstallUISequence and InstallExecuteSequence. Changing
this sequence is beyond the scope of what I want to do for now.
Extra Actions
Custom Actions need to be added as a child of the Product
element in Wix. Additionally if you want the action to run within the install
sequence you need to add it to one of the appropriate tags mentioned in
Queueing Up. The tutorial describes using custom actions to do things like
execute applications, set properties and display errors. There are also a number of additional
standard actions that can be queued up using a tag like InstallExecuteSequence.
What’s Not in the Book
I am going to have a user action that references a custom
action I write. Following the tutorial’s lead, this action is going to check
the validity of the product key entered by the user. To add the code file for this we right-click
the solution and Add > New Project.
Under Windows Installer XML select the C# Custom Action Project. We’ll
call it CheckPID.
Wix adds the code file and stubs out the custom action. It
also adds a config file with the necessary supportedRuntime tags included. I
add my code to retrieve the PIDKEY property from the installer session. Then it
writes the PIDACCEPTED value back to the session based on whether the PIDKEY
that the user inputs stats with a “1” or not: the value is 1 if it does and 0
if it does not. Then our action is always going to return ActionResult.Success.
If we returned a failure the installer would give the user an error and shut
down. We want them to be able to stay at the dialog and insert the correct key.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.Deployment.WindowsInstaller;
namespace CheckPID
{
public class CustomActions
{
[CustomAction]
public static ActionResult CheckPID(Session session)
{
string Pid = session["PIDKEY"];
session["PIDACCEPTED"] = Pid.StartsWith("1") ? "1" : "0";
return ActionResult.Success;
}
}
}
We also need to add a reference from the Wix project to our
CheckPID project. Right-click on the References item under the Wix project and
do Add Reference and then select our new project from the Projects tab.
In the Product.wxs file I added a new Fragment that contains
the CustomAction tag and the binary reference to the DLL to use. The SourceFile
attribute of the Binary element is the source file where the action is. The
CustomAction element then references the Binary element by Id. The DllEntry
attribute of the CustomAction is the method of the binary that will be called.
<Fragment>
<CustomAction Id='CheckingPID' BinaryKey='CheckPID.CA' DllEntry='CheckPID' />
<Binary Id='CheckPID.CA' SourceFile='..\CheckPID\bin\Debug\CheckPID.CA.dll' />
</Fragment>
How to Manage
Notice above that the DLL we are referencing is not the
expected CheckPID.dll. Wix uses the MakeSfxCA (for Make self-extracting custom
action) utility to put a wrapper around the assembly our C# code creates to
have a managed custom action. If you use the Wix Custom Action project as
described above Wix will handle making that call to MakeSfxCA. If you just
create a C# code library file you will need to add a post-build call to create
that wrapper (http://wix.tramontana.co.hu/tutorial/events-and-actions/how-to-manage).
Control Your Controls
In the UserRegistrationDlg I replaced the Publish events
with new ones.
<Control Id="Next" Type="PushButton" X="236" Y="243" Width="56" Height="17" Default="yes" Text="&Next">
<Publish Event="DoAction" Value="CheckingPID">1</Publish>
<Publish Event="SpawnDialog" Value="InvalidPidDlg">PIDACCEPTED = "0"</Publish>
<Publish Event="NewDialog" Value="SetupTypeDlg">PIDACCEPTED = "1"</Publish>
</Control>
The first Event DoAction has a value that refers back to the
Id of our CustomAction. Then we check the PIDACCEPTED value that we set in our
code. If the product Id is not accepted we are going to spawn a new dialog,
InvalidPidDlg. If it is accepted we’ll advance to the CustomizeDlg dialog as
before. Note that SpawnDialog creates a child dialog to the current dialog.
NewDialog navigates to a new dialog.
As before when I added the User Registration dialog I add a
new Wix .wxs file to the Wix project named InvalidPidDlg.wxs. To this file I
added a UI container with the new dialog. The dialog contains the Error text to
convey to the user, an exclamation point icon and a PushButton that will close
the dialog sending us back to the parent UserRegistrationDlg dialog for us to
re-enter the key. I also added the binary reference to the exclamation icon to
include. You can get Exclam.ico from the tutorial files download (http://wix.tramontana.co.hu/system/files/samples/SampleAskKey.zip)
or create your own.
xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Fragment>
<UI>
<Dialog Id="InvalidPidDlg" Width="260" Height="85" Title="[ProductName] Setup" NoMinimize="yes">
<Control Id="Icon" Type="Icon" X="15" Y="15" Width="24" Height="24"
ToolTip="Information icon" FixedSize="yes" IconSize="32" Text="Exclam.ico" />
<Control Id="Return" Type="PushButton" X="100" Y="62" Width="56" Height="17" Default="yes" Cancel="yes" Text="&Return">
<Publish Event="EndDialog" Value="Return">1</Publish>
</Control>
<Control Id="Text" Type="Text" X="48" Y="10" Width="194" Height="45" TabSkip="no">
<Text>
The user key you entered is
invalid.
Please, enter the key printed on
the label
of the jewel case of the
installation CD.
</Text>
</Control>
</Dialog>
</UI>
<Binary Id="Exclam.ico" SourceFile="Exclam.ico" />
</Fragment>
</Wix>
In
Conclusion
You should be able to build and run the installer now.
Submitting a product key that starts with anything other than a ‘1’ will
display the Invalid PID dialog. As I use
WiX for our real-world cases I will post anything interesting or sticking
points that come up.
