Monthly Archives: October 2013

Create an installer for website with WIX, part 3

In part 1 we saw how we can use a MS Build script to harvest all the files that needs to be installed and to create our msi installer. In part 2 we saw how we can add our own custom UI.

With only the files installed you don’t have a website running. At least not an ASP.NET MVC website. You have to register the website in the Internet Information Services (IIS), create an app pool with the correct framework selected and activate (start) the website.

This post will handle that part of the creation of the installer where we extend the project we used in part 1 & part 2.

Add the IISConfiguration WiX file

We start by adding a new item in our setup project, choose for an installer file and name it IISConfiguration.wxs. The template will create an empty WiX page with just an empty “Fragment” element.

We’ll start with adding a component for the application pool.

We add a “DirectoryRef” element that we point to our installation folder so that this will be run when handling the installation directory in the installer.

In the “Component” element we add the “iis:WebAppPool” element. Give it an id and name, the name will be displayed in IIS. Choose the Identity that will start the application pool.

You can choose “networkService”, “localService”, “localSystem”,”applicationPoolIdentity” or “other”. With “other’” you’ll have to create a user with a username and password that you have to assign to the “iis:WebAppPool” element “users” parameter (not in this example).

NOTE: I had to install the 3.8 version of the WiX toolset to be able to assign the “applicationPoolIdentity”. In previous versions this was apparently not possible.

If you work in Visual Studio you’ll notice the editor adds an red line under the “iis:WebAppPool” element. We have to add the IISExtension namespace in the Wix declaration.

Add the install website component

Next we’ll add a second component to our file to create the website in IIS.

Here we’ll have to an unique id, a description of the website ‘(will be shown in IIS), the directory where the website is installed (our “INSTALLFOLDER”) and the auto start variables.

In the “iis:Website” element you can add one or more “iis:WebAddress” elements to assign DNS names and TCP ports to the website.

Last but not least, we’ll have to connect the correct application pool to the website by adding a “iis:WebApplication” with a unique id and name (I took the website id) and a reference to the “iis:WebAppPool” element we created before.

Create and reference component group

It’s best practice to group these two components in a component group so you only have to add one reference to iis configuration elements.

Add this “ComponentGroup” in the “Target” element.

In the product.wxs file we have to place a reference to this component group in the “Feature” tag.

Update the MS Build file

Because we created an extra file to include in the build process we must be sure that the file is added in the MS Build file.

We have to update the item groups that contain the list of files to include as shown above.

Now open up the Developer Command Prompt for Visual Studio 2012 again and change the prompt to the setup project folder and type the next statement:

msbuild /t: Build;PublishWebsite;Harvest;WIX;DeleteTmpFiles setup.build

and hit enter.

You’ll see the build process will return an error. We added a reference to the IISExtensions library in our IISConfiguration.wxs file but we didn’t told the candle.exe and light.exe tools to take that into account.

Add in both commands the –ext WixIISExtension flag and run the MS build script again. This time it shouldn’t be returning any errors.

Test the installer

Let’s run the installer and see if it really adds our website.

During the installation you’ll see a message passing by that it’s configuring IIS. Complete the installation and open up the IIS manager (run inetmgr).

image

We’ll see a new Demo Website website on the left hand side and a new application pool DemoWebsite on the right hand side running .NET 4.0 under the correct application pool identity.

image

If we open up the advanced settings of the website we’ll see the correct physical path is used and the binding is correct.

You may have noticed that our website isn’t started (the stop sign on the website icon). This isn’t a fault of the installer, it tried to start the website but because we choose port 80 in our installer IIS noticed there is another site running on that port (Default Web Site) and refuses to start our installed website.

If you change the port in the installer (or remove/stop the default webs site before installing) you’ll notice it starts upon install.

Next parts

This concludes the installation in IIS. Next part we’ll handle the creation of the database using the entered credentials and running SQL scripts from the installer.

  • Install the .NET 4.5 framework if that isn’t installed already
  • Install the MVC 4 framework if that isn’t installed already.
  • Create a folder and copy all needed files to run the application (done)
  • Create a new database on an existing SQL server and prefill the database with the correct tables and values. (the connection details and database name should be entered by the end user running the installer)
  • Create a new website in IIS 7.5 (create website and application pool running under .NET 4.5) (done)
  • Alter the config file so the correct connection settings are used (entered by the end user)

Complete source code

Can be found on Github.

Other posts in this series:

Create an installer for website with WIX, part 2

In part 1 we saw how we can use a MS Build script to harvest all the files that needs to be installed and to create our msi installer.

When you run the installer we created you saw it had a very minimalistic UI, better none UI at all. In part 2 we’re going to add a user interface for the installer. We’ll make use of the build in UI elements of WiX but also add a new dialog so the end user can enter the database connection values and credentials.

The WiX library has already a lot of build in UI dialogs and flows that you can use out of the box. If you download the source code from codeplex you can take a look at the standard UI. (unzip and then go to \src\ext\UIExtension\wixlib\)

The dialogs we wanted to show our end customers where:

  • Welcome screen
  • Let the user select the install directory (default c:\inetpub\)
  • Let the user fill out database connection values (database server IP or name, database name, database user end password)
  • Confirmation to install
  • Show some progress of the installation
  • Show a install succeeded screen

The WixUI_InstallDir default UI comes closest to what we want to implement. So we start from that default UI theme.

Create our own UI

Add a new file in our setup project and name it DemoUI.wxs.and copy the default WixUI_InstallDir file content into this file.

You can see the flow the UI will follow. First a welcome screen, then a license screen, then the installation directory screen, a verify ready dialog and a maintenance dialog. Except for the license screen this is exactly what we needed.

Our first job will be to remove the license screen from our UI flow. You can delete the lines 60 and 61 but we’ll have to take care of the references to the license screen.

On line 58 you’ll see that the welcome dialog next button will send you to the license screen, alter that so it will send you to the installation directory screen.

Same for line 63 where the back button will send you to the license screen. Update the Value tag so it references the welcome dialog instead.

Reference our own UI

We still have to tell our installer that he has to use our own UI instead of the default one. In our DemoUI.wxs change the Id of the UI element (line 33) from “WixUI_InstallDir” to “MyUi”.

In our Product.wxs we’ll have to reference our own UI by adding a “UIRef” element in the “Product” element with Id “MyUI”. (line 11)

And we have to tell the UI the default folder he has to use in the Install directory dialog by adding the “WIXUI_INSTALLDIR” property that we reference to our “INETPUB” property.

Update our MS build file

Now that we have a new source file (DemoUI.wxs) we have to update our MS Build file to include our user interface.

Open up the setup.build file and update the Itemgroups containing the WiX source files and WiX compiled files.

In our WIX target we’ll have to tell the light.exe tool that we are using parts of the WixUIExtension library.

And last but not least I added a new target to clean up all previous created and build files to avoid conflicts.

Now build the installer by opening a Developer Command Prompt for Visual Studio 2012, change the directory to the setup project and enter the next command:

msbuild /t: Build;PublishWebsite;Harvest;WIX;DeleteTmpFiles setup.build

and hit enter.

In the \bin\release folder of our setup project you’ll find our freshly build DemoWebsite_Setup.msi. Double-click the installer and you’ll see the welcome screen as intended.

 image

If we click next the destination folder is prefilled with the c:\Inetpub folder but can be changed by the end user. Clicking next will show the “ready for installation” and the “installation succeeded” screens.

During installation we’ll see a progress bar showing the status of the installer. Running the installer will, just like in the last post, install the necessary files in the C:\Inetpub\DemoWebsite folder (if no other location is selected by you).

If you run the installer again you’ll get the default repair/remove interface.

Add the SQL connection screen

Now that we have a default UI for our installer we can add the dialog to let the end user enter the database connection values.

Add properties

The database connection values that will be entered by the end user will need to be reused in a later process of installation of the database. Therefor we have to store them in properties.

In our Product.wxs file we add four properties (DB_USER, DB_PASSWORD, DB_SERVER, DB_DATABASE) and give them some default values (line 7 to 10).

Add a new dialog

Now we can add the new dialog, add a new Installer file in our setup project and name it UIDialogs.wxs. I added the controls we need.

We’ll see a label and a text box for our 4 properties and a next and cancel button that we’ll link in our UI file.

Insert the dialog in the UI flow

Open up our DemoUI.wxs file again and add our new dialog between the “Install directory” and “verify ready” dialogs. Add 2 references, one for the next button and one for the back button.

The next button we reference to the “VerifyReadyDlg” and the back button to the “InstallDirDlg”.

We’ve got to alter the flow to insert our dialog by changing line 5 (reference the next button of “InstallDirDlg” to our one) and change line 12 (reference the back button of “VerifyReadyDlg” to our one).

Update our MS build file

We have to tell our script there is a new source file to handle, the dialog file. Open up the MS build script again and alter the ItemGroup settings by adding the new file.

Open your command prompt again and run the next statement:

msbuild /t: Build;PublishWebsite;Harvest;WIX;DeleteTmpFiles setup.build

and hit enter.

When our installer is build, run it and you’ll see the new dialog appear after the installation directory dialog.

image

Check the installer

You may see the properties now in the UI you want off course to be sure they are set properly. You can check that by letting the install process create a log file.

Browse to the /bin/release/ folder in the setup project and open a command prompt. On the prompt type the next command:

msiexec /I Demowebsite_Setup.msi /l*v demo.log

You’ll see that during the installation process a “demo.log” file will appear in the /bin/release/ folder. In that log file you will see the parameters are set to the entered values (second line in the screenshot)

image

Next parts

This concludes the custom UI we wanted to create. In the next chapters we’ll use the entered information to create a database.

Off course there is (a lot) of room to enhance the UI with custom bitmaps, text, … More information you can find in the WiX documentation page.

The items in yellow are handled, the next post will be probably on how to add a website in IIS.

  • Install the .NET 4.5 framework if that isn’t installed already
  • Install the MVC 4 framework if that isn’t installed already.
  • Create a folder and copy all needed files to run the application (done)
  • Create a new database on an existing SQL server and prefill the database with the correct tables and values. (the connection details and database name should be entered by the end user running the installer)
  • Create a new website in IIS 7.5 (create website and application pool running under .NET 4.5)
  • Alter the config file so the correct connection settings are used (entered by the end user)

Complete source code

Can be found on Github.

Other posts in this series

Create an installer for website with WIX, part 1

For a customer we created a new web application in MVC4 with an underlying SQL database. One of the requirements was to provide an installer to install this website at their customers local installations. The installer had to do a few tasks:

  • Install the .NET 4.5 framework if that isn’t installed already
  • Install the MVC 4 framework if that isn’t installed already.
  • Create a folder and copy all needed files to run the application
  • Create a new database on an existing SQL server and prefill the database with the correct tables and values. (the connection details and database name should be entered by the end user running the installer)
  • Create a new website in IIS 7.5 (create website and application pool running under .NET 4.5)
  • Alter the config file so the correct connection settings are used (entered by the end user)

From Visual Studio 2012 on there is no Windows Installer project available any more. You can use the InstallShield Express edition with limited capabilities or the Windows Installer XML (WiX) open source package created by Rob Mensching when he was working for Microsoft. (It’s actually the oldest open source project from Microsoft and now under the OuterCurve foundation)

The Installshield express version doesn’t support IIS installations and falls out of the boat. WiX does support all actions that we have to do but has a steep learning curve. I used WIX in a previous project and still had some hassle to put all of it together. This series of posts will walk us through the creation of the installer.

Start project

Start by downloading the WiX toolset from http://wixtoolset.org/releases/. For this demo I used the 3.8.826.0 version. This is not the latest stable published release but I haven’t got any problems with this version.

Next step is creating a MVC 4 web project and choose for an internet application so we have some default files (javascript, css, views, controllers, …).

Right click on the solution in the solution explorer and choose to add another project. In the ‘Add New Project’ dialog select Windows Installer XML on the left hand side. Choose for ‘Setup Project’ and click the OK button.

image

You should get a new project with only one file (Product.wxs).

WiX flow

WiX source files are written in XML and have the wxs or wxi (for variables) extensions. Those files have to be compiled to wixobj files. This can be done in Visual Studio or by command line by using the candle.exe tool in the WiX toolset. After compiling the wixobj files another tool is needed to create the msi (installer) file, the light.exe tool.

The most simple installer can be created by just using one wxs file. You will notice that it will make your project more clear to use different wxs files. One for every part of the installation.

You can use the default UI that is available in the WiX toolset but with bigger projects (and in this demo) you can create your own UI and flow. Even the UI is defined in XML and has the same wxs extension. Another reason to split up your installer code in different files to keep the overview.

Step 1: install all needed files

Open up the Product.wxs file in Visual Studio. You’ll see already a few standard values filled out.

At line 3 you get the product attributes that have to be set. Leave the asterix ( * ) at the Id tag. WiX will replace this with an unique Guid when compiling the source. Set the version, language and the name to the desired values.

IIS default location for websites is the c:\inetpub directory. We’ll alter the installer so this default location is used. In one of the next chapters we’ll be able to change this folder. Navigate to line 15 and alter the Directory tag.

You’ll see I’ve changed the default InstallFolder to Inetpub. (from c:\Program Files to c:\Inetpub). This is all we have to change for the install location.

On line 26 you’ll see the ComponentGroup where we’ll have to define all files that have to be installed in our installation folder. Let’s start with adding some files. In the example below I added 3 files in the root of out application (favicon.ico, web.config and global.asax). To add the bin folder I had to add a new ComponentGroup, a new Component, and a new Directory element before I could add the files (2 dll’s).

As you can see this is a tedious job to add every file you want to be installed. Luckily there is a faster way to create this.

Use the heat component from the WiX toolset

The WiX toolset has another tool heat.exe that can help us to harvest all files that we need to install. Although heat was incorporated in Votive (the Visual Studio environment for WiX) in earlier versions, in the 3.7 – 3.8 version this is not available in Visual Studio.

MSBuild to the rescue

If we want to make use of the heat component we’ll have to script it. We can create a bat file we can run every time before we build the installer or we can create an MS build script that we can run. The MS build script has the advantage that we can reuse this script for out build server (continuous integration).

Create a new text file in the Setup project and rename it to setup.build. First we’ll add some properties in a ‘PropertyGroup’: the source of our website and the name of the WiX file we want to build. We also include the path where we should publish all files. In the ‘itemgroups’ we define the temporary files witch is the content of the web site and the list of WiX input files.

Add build target

We first have to build our website so we are sure we have the latest build we are deploying. Therefor we add a target in the MS build file

Add Publish website target

We’ll use the build in publish feature of MS build to deploy the website to a new folder so we have only the files we need. (and not the .cs files etc)

Harvest the files in WiX

Now that we have all the files we need under a temporary folder we can use the heat.exe tool in the WiX tool belt to harvest the files and create a wxs file.

The parameters used in this command:

  • dir $(Publish) tells to harvest a directory (our published website)
  • -dr:  The directory where the files have to be installed to
  • -ke:  Keep the Empty directories
  • -srd:  Suppress harvesting the root directory as an element.
  • -cg: The ComponentGroup name that have to be used
  • -var var.publishDir: Will substitute the source directory with a wix variable so we can use $(var.publishDir)\myfile.txt in the wxs files
  • -out $(WebsiteContentCode)  the file we want to be created (see PropertyGroup settings)

Test the script

With the heat command inserted we can test our script. Open up a Developer Command Prompt for VS2012. Change the prompt to the DemoWebsite.Setup project folder and type the following command:

msbuild /t: Build;PublishWebsite;Harvest setup.build

and hit enter. If everything goes well you’ll see a lot of command coming by. The script will create a folder Setup\publish under the root and publish the website. At last a WebsiteContent.wxs file will be created in the setup project folder.

If you open up the WebsiteContent.wxs file you’ll see all files and folders are added with their own Id under a ComponentGroup MyWebComponents.

If you looked closely you’ll have seen a few WiX commands passing by when executing the build file. Because we are going to handle the WiX build process in our build file we can exclude the setup project from the build configuration. Right click on the solution in the Solution Explorer in Visual Studio and choose for Configuration manager.

image

Change the active solution configuration to ‘Release’ and uncheck the build flag next to the setup project.

image

Update the Product.wxs file

Now we have all our files we have to install we have to reference to the created MyWebComponents CompenentGroup and delete the entries we made before to add the files.

Build the installer

Now that we have all the components for the first fase (installing the files) we can use the candle.exe and light.exe tools from the WiX tool belt to built our installer.

Add properties in the build file

First we need some more properties in our build file. Add the WebSiteContentObject parameter that will hold the compiled WiX code (WebSiteContent.wixobj). And also add the MsiOut parameter that will hold the path and name of the installer (.msi) file.

Add candle.exe in the build file

Add a new target tag in the build file and add the candle.exe tool with the parameters where to find the publish directory and witch files he has to compile.

Add light.exe in the build file

In the same target (WIX) add the light.exe command with parameters where to put the generated msi and witch source files to include.

Final run

Open up your Developer Command Prompt and type the next command where we added the WIX target:

msbuild /t: Build;PublishWebsite;Harvest;WIX setup.build

Hit enter and keep your fingers crossed. If you had no error messages you should find a msi file in the bin/release folder of the setup project. Run that installer and you’ll see that under the C:\inetpub folder a DemoWebsite folder is added with all the published files from our webapplication.

If you had any errors you can find the complete files here:

Next parts

Enough for one blog post I would say. the next posts in this series will handle the next actions:

  • Install the .NET 4.5 framework if that isn’t installed already
  • Install the MVC 4 framework if that isn’t installed already.
  • Create a folder and copy all needed files to run the application (done)
  • Create a new database on an existing SQL server and prefill the database with the correct tables and values. (the connection details and database name should be entered by the end user running the installer)
  • Create a new website in IIS 7.5 (create website and application pool running under .NET 4.5)
  • Alter the config file so the correct connection settings are used (entered by the end user)

Complete source code

You can find the complete source code for this project on GitHub. Keep in mind that this project will be altered when the next parts are implemented. I will try to keep the commits together with the series.

Other posts in this series