Custom action project templates

New in this week's WiX build 3.0.4123 are Visual Studio 2005 & 2008 templates for C++, C#, and VB custom action projects:

WiX Project Templates for Visual Studio

The C++ project sets you up with the WiX unmanaged CA utility library (wcautil), while the C# and VB projects use the DTF library for managed-code MSI custom actions. I assume you're here because you want to read more about the latter.

When DTF first released with WiX last week, it included some sparse documentation about how to create a post-build step to package up your managed CA assembly in a form callable by MSI. I apologize to anyone who jumped on it right away and had trouble hooking things up (which was only made more difficult by a missing binary that had to be built from source). I should have had these templates ready then.

When you create a C# custom action project from the new template, the project has the necessary post-build step hooked up already. For the curious, those build rules are in %ProgramFiles%\MSBuild\Microsoft\WiX\v3.0\wix.ca.targets. Building the custom action project will produce an additional DLL in the target directory with the name $(TargetName).CA.dll. That is the DLL to be streamed into your MSI Binary table. Since that DLL exports ordinary entrypoints callable directly by the MSI engine, you can use it with any MSI authoring tool as if it was an unmanaged CA DLL.

The custom action build process will automatically package up any non-GAC'd assemblies that your CA depends on. (Make sure the Copy Local property is set to 'true' on the reference node if you want it included.) Those dependencies will include at a minimum the Microsoft.Deployment.WindowsInstaller.dll assembly from DTF. Additionally, any items in the project with a Build Action of 'Content' will be included in the CA package. CustomAction.config is the sole Content file in the template; your CA may require additional resources or data files at runtime.

In Votive, a convenient way to consume the custom action DLL in your setup is via a project reference:

  1. Create a solution with a WiX MSI or WiX Library project and a C# or VB custom action project.
  2. Add a reference from the WiX project to the custom action project.
  3. Author the custom action in your setup with WiX code similar to the fragment below. Note you may need to change some attributes in the XML, depending on your CA and how it executes.

<Fragment>

<Binary Id="MyCustomAction.dll"

SourceFile="$(var.CAProjectName.TargetDir)$(var.CAProjectName.TargetName).CA.dll" />

<CustomAction Id="MyCustomAction" BinaryKey="MyCustomAction.dll"

DllEntry="CAMethodName" Execute="immediate" />

</Fragment>

I hope this helps interested developers get started with managed custom actions. Future posts here will hopefully get into some actual coding.