An msi is really a relational database made up of a number of tables. When an installation runs the windows installer parses the msi and then queries tables to see what actions it must perform. Msdn has a complete list of tables that the windows installer uses and it’s very worth while checking it out because it will give you a good idea of what you’re install is going to do and why.
If you use certain wix elements you may notice they create tables that are not listed in the msdn documentation. This is not because they are undocumented tables, it is because the msi format allows you to define custom tables and these custom tables will be ignored by the installer service.
So why bother putting in these tables if the installer is going to ignore them? This is because the number of things that the installer server can do is somewhat limited; there are quite a few tasks, such as installing virtual directories, file shares or users, that it is very difficult to do with out resorting custom actions. While custom actions are a necessary evil, they are also annoying because they do not fit well into the nice declarative programming model of the installer server and make it very easy to create installs that do not roll back correctly. So wix has come up with a mechanism that allows it to extend the things that installer can do by creating these new tables and providing a set of generic custom actions which queries these tables and install certain items based on the result of the query. This is a fantastic thing in my opinion, because suddenly loads of new installation task become available by a declarative mechanism. Also these mechanism will be tried and test by wix users, so are probably much safer that opening VS.NET and hacking out a few C# based custom actions.
The unfortunate thing is these custom action based tables are still largely undocumented, so it quite possible to user a wix element in an install without releasing that you need to include a custom action definition. And so it will do not do anything. And so you will bash you head against the monitor trying to find out why it does nothing.
Wix comes with two files, ‘ca\sca.wixlib’ and ‘ca\wixca.wixlib’, which will add the necessary custom action definitions for you. There is currently no documentation to tell you which elements to require you to include a custom action file in you’re build, this why I have prepared the following list of elements that need custom actions definitions. I’ve also listed the name of the method you need to call in the dll that will process the tables produced by the elements listed.
Elements that require ‘ca\sca.wixlib’ and the dlls ‘scaexec.dll’ and ‘scasched.dll’:
IIs related elements – ‘ConfigureIIs’ custom action:
Certificate
MIME
WebAddress
WebApplication
WebApplicationExtension
WebAppPool
WebDir
WebDirProperties
WebError
WebFilter
WebProperty
WebServiceExtension
WebSite
WebVirtualDir
Sql related elements – ‘ConfigureSql’ custom action:
SqlDatabase
SqlFileSpec
SqlLogFileSpec
SqlScript
SqlString
Performance counter related elements – ‘ConfigurePerfmonInstall’ and ‘ConfigurePerfmonUninstall’ custom actions:
PerfCounter
File share related elements – ‘ConfigureSmb’ custom actions:
FileShare
Permission (When child of FileShare)
User related elements – ‘ConfigureUsers’ custom action:
User
Group
GroupRef
Elements that require ‘ca\wixca.wixlib’ and the dll ‘wixca.dll’:
Service related elements – ‘CaSchedServiceConfig’ and ‘CaExecServiceConfig’ custom action:
ServiceArgument
ServiceConfig
ServiceControl
ServiceDependency
ServiceInstall
Permission (When child of ServiceInstall)
I hopefully this has given you a good idea when you need to included custom action configuration and when you don’t. I’m going to creating some more detailed examples of how to use these elements soon.
Feedback:
Feedback was imported from my only blog engine, it's no longer possible to post feedback here.
re: Wix Custom Actions - jmdavidson at gmail dot com
This is just what I've been looking for. I'll be waiting anxiously for those more detailed examples. Thank you.
re: Wix Custom Actions - Harjit S. Batra
Looking in the CA folder I also see a PubCA.wixlib. Any idea what Custom Actions one can perform with that one?
re: Wix Custom Actions - Igal Nassi
Can someone post the XML that creates an IIS Virtual folder? I am using WiX 3 and I cannot seem to find where the tags should go and what exactly needs to go under it.
re: Wix Custom Actions - Niclas
This was exactly the information I was looking for. I have been troubleshooting a linker error I get when I added a FileShare with Permissions to my project. I think the documentation at wix.sourceforge.net should be updated to contain this information. That would have saved med a lot of time.