Custom Installer Actions: Edit Connection Strings, IIS Directory Security Settings, etc.

When I need to deliver a web application to a client, I create a Setup/Deployment Project and then send them the .MSI file.  This makes it super easy to make sure that all the dependencies are there and that the web directory gets set up in IIS.  It eliminates 80% of the deployment hassle. 

The remaining 20% of the deployment hassle comes from having to tweek database connection strings in different files and updating other configuration settings.  In order to do this with the Deployment Project in VS2005, you need to implement a Custom Installer Action.

I finally got around to doing writing one this week.  

Here’s what it can do:

• Edit database connection strings through a dialog that pops up during the installation
  
• Types of connection strings supported: NHibernate (hibernate.cfg.xml), Stand-alone Enterprise Library (*.config) files, Web.config “connectionString” values, Web.config appSettings-based “add” connection strings
  
• Modify IIS Directory Security Settings (Allow NTLM, Allow Basic, Allow Anonymous)
  
• Update paths to configuration files referenced in Web.config (eg. custom external configuration files)

I’ve posted two zip files: the source code and the binaries.  The source code includes the code for the installer actions, the VS2005 unit tests, a sample web application, and a sample installer for the web application.  If you’re looking for an example of how to edit IIS from C#, IISActiveDirectoryUtility.cs inside of the Com.Benday.InstallerActions project is a great place to start. 

If you want to use the custom action binaries in your own installer project, you need to:

1. In Solution Explorer, click on your web application deployment project
   
2. Click the “File System Editor” button (at the top of Solution Explorer)
   
3. Go to the “bin” directory inside the “Web Application Folder”
   
4. Right-click the “bin” folder and choose Add –> File…
   
5. Choose Com.Benday.InstallerActions.dll (from wherever you put it)
   
6. Now click on the “Custom Actions Editor” button (at the top of Solution Explorer)
   
7. Right click on the “Install” folder and add one or more references to Com.Benday.InstallerActions.dll
   
8. Edit the CustomActionData value in the properties for each reference to Com.Benday.InstallerActions.dll according to the documentation later in this post

Your Custom Actions screen should now look something like this:

And after you’ve configured it, the properties for each should look something like this:

CustomActionData arguments to edit the IIS directory security settings:

• /action=VirtualDirectorySecurity
  
• /virtualDirectory=”[TARGETVDIR]”
  [TARGETVDIR] is a reserved variable that is supplied by the installer that tells you the name of the IIS directory
  
• /AllowNTLM=1 or /AllowNTLM=0
  To enable NTLM on the directory set this value to 1.  To disable NTLM, set this value to 0 or omit /AllowNTLM
  
• /AllowBasic
  To enable basic authentication on the directory set this value to 1.  To disable, set this value to 0 or omit.
  
• /AllowAnonymous
  To enable anonymous access on the directory set this value to 1.  To disable, set this value to 0 or omit.

CustomActionData arguments for editing NHibernate database connection strings:

• /action=ConfigurationFiles
  
• /targetDirectory=”[TARGETDIR]”
  [TARGETDIR] is a reserved variable that is supplied by the installer that points to the filesystem path for the directory. HINT: make sure that you put this in quotes and that you have a “” after [TARGETDIR].  If you see weird FileNotFound errors, this is probably the culprit. 
  
• /hibernateConfigFile=hibernate.cfg.xml
  This is the name of the NHibernate configuration file.  This value will always be “hibernate.cfg.xml”.

CustomActionData arguments for editing connection strings stored in Web.config’s “connectionStrings” element:

• /action=ConfigurationFiles
  
• /targetDirectory=”[TARGETDIR]”
  [TARGETDIR] is a reserved variable that is supplied by the installer that points to the filesystem path for the directory. HINT: make sure that you put this in quotes and that you have a “” after [TARGETDIR].  If you see weird FileNotFound errors, this is probably the culprit. 
  
• /webConfigConnectionString=WebConfigConnectionString
  This is the “name” of the connection string that you want to edit

CustomActionData arguments for editing connection strings stored in Web.config’s “appSettings” element:

• /action=ConfigurationFiles
  
• /targetDirectory=”[TARGETDIR]”
  [TARGETDIR] is a reserved variable that is supplied by the installer that points to the filesystem path for the directory. HINT: make sure that you put this in quotes and that you have a “” after [TARGETDIR].  If you see weird FileNotFound errors, this is probably the culprit. 
  
• /webConfigDatabaseKeys=DB_CONNECTION;ANOTHER_DB_CONNECTION
  The value is the name of the “add” element that has the connection string in it.  If you have multiple “add” elements with database connection strings in them, separate the values by semi-colon.

CustomActionData arguments for editing connection strings stored in a separate Enterprise Library Database Configuration file:

• /action=ConfigurationFiles
  
• /targetDirectory=”[TARGETDIR]”
  [TARGETDIR] is a reserved variable that is supplied by the installer that points to the filesystem path for the directory. HINT: make sure that you put this in quotes and that you have a “” after [TARGETDIR].  If you see weird FileNotFound errors, this is probably the culprit. 
  
• /enterpriseLibraryDbConfigFile=dataConfiguration.config
  This is the name of the file that has the enterprise library configuration data

CustomActionData arguments for editing paths to files referenced in Web.config’s appSettings:

• /action=ConfigurationFiles
  
• /targetDirectory=”[TARGETDIR]”
  [TARGETDIR] is a reserved variable that is supplied by the installer that points to the filesystem path for the directory. HINT: make sure that you put this in quotes and that you have a “” after [TARGETDIR].  If you see weird FileNotFound errors, this is probably the culprit. 
  
• /webConfigUpdatePathToFilenamesKey=PATH_TO_A_FILE;SomeImportantFile.txt
  This is a semi-colon delimited value.  The first part of the value is the name of the “add” key in “appSettings”.  The second part is the name of the file that needs to have it’s full filesystem path updated.  If you need to update more than one file reference, you can add more semi-colon delimited pairs. 

More Hints:

If you have several database config values that that all need to point to the same database — for example, some codee connects via Enterprise Library and some code uses hibernate.cfg.xml — put all of these into the same /action=ConfigurationFiles reference.  A CustomActionData that looks like this “/action=ConfigurationFiles /targetDirectory=”[TARGETDIR]” /enterpriseLibraryDbConfigFile=dataConfiguration.config /hibernateConfigFile=hibernate.cfg.xml” would allow you to set the enterprise library db config file and the nhibernate config file to the same database connection at the same time. 

Definitely take a look at the custom action configuration in the sample installer that’s included in the source code zip.  After that, feel free to post your questions.

-Ben