Lessons Learned from Packaging our ASP.NET Application for the Microsoft Web Platform Installer

Disclaimer: While Jumptree Project is compatible with Microsoft Web Platform Installer, it’s not officially supported.

In 2009, Microsoft released their Web Platform Installer.

The Microsoft Web Platform Installer 2.0 (Web PI) is a free tool that makes getting the latest components of the Microsoft Web Platform, including Internet Information Services (IIS), SQL Server Express, .NET Framework and Visual Web Developer easy. The Web PI also makes it easy to install and run the most popular free web applications for blogging, content management and more with the built-in Windows Web Application Gallery.

By bundling all these components together, e.g. runtime, database, etc., it allows users to easily install and customize all the software they need to develop on a Windows machine.

Now Microsoft already has an excellent guide on how to package an application for the Windows Application Gallery.

This guide should provide you with the necessary outline to make your application compatible with the Microsoft Platform Installer.

However we did run into a few issues, and so this tutorial will document some of the lessons we learned.

Now before we get started, you’ll want to keep the Web Application Package Reference handy as it describes the details of the installer API tags.

The Basics

The first thing you’ll realize after downloading the Microsoft Web Platform Installer (MS PI) is that your application package will simply be a .zip file.

In the zip file, you need two XML files to be created at the root of your application package to make it compatible with MS PI:

1. manifest.xml
2. parameters.xml

Here’s how it looks in our Jumptree Project package:

Packaging

Now let’s take a look at the configuration files.

First, manifest.xml is basically a configuration file describing the structure of your package: SQL scripts, permission, etc.

To create a basic package, start with a simple file that has,

<MSDeploy.iisApp>
	<iisApp path="Site_Install_Folder" />
</MSDeploy.iisApp>

If your package uses a database, then to make your SQL scripts executable by MS PI, simply add,

<dbfullsql path="install.sql" />

to the mainifest.xml, where install.sql can be any SQL files you have.

For example, this is what we did for Jumptree Project,

<MSDeploy.iisApp>
	<iisApp path="Site_Install_Folder" />
	<dbfullsql path="Site_Install_Folder/App_Data/SqlScripts/Membership.sql" transacted="false" />
	<dbfullsql path="Site_Install_Folder/App_Data/SqlScripts/pmv1.2release.sql" transacted="false" />
	<dbfullsql path="Site_Install_Folder/App_Data/SqlScripts/DefaultPerspectives.sql" transacted="false" />
	<dbfullsql path="Site_Install_Folder/App_Data/SqlScripts/CustomizeFieldTyes.sql" transacted="false" />
	<dbfullsql path="Site_Install_Folder/App_Data/SqlScripts/StarterKitDefaultUser.sql" />
</MSDeploy.iisApp>

Next, parameters.xml is simply a file with a list of parameters that the Web PI will use—or prompt the users for actions.

To configure your application to be automatically installed in a virtual directory, add the following parameter with the parameterEntry code,

<parameters>
	<parameter
		name = "AppPath"
		defaultValue = "Default Web Site/Jumptree"
		tags = "iisapp"
	>
		<parameterEntry
			type  = "ProviderPath"
			scope = "iisapp"
			match = "Site_Install_Folder"
		/>
	</parameter>
...

Now one last thing…

Previously, I mentioned that if you have SQL scripts that need to be executed, then list them in manifest.xml.

Well to execute these scripts, MS PI needs to know the connection string used to connect to the database. And to do that, you’ll need to add the connection string parameter to parameters.xml,

lt;parameter
	name = "ConString1"
	defaultValue = "Server={dbServer};Database={dbName};uid={dbUsername};Pwd={dbUserPassword};"
	tags = "SQL, Hidden, SQLConnectionString, Validate"
>
	<parameterEntry
		type  = "ProviderPath"
		scope = "dbfullsql"
		match = "Membership.sql"
	/>
</parameter>

Testing

To prepare the package for testing, just zip up the folder with the manifest.xml and parameters.xml at its root.

If everything looks right and you still have problems getting MS PI to work, then something might be wrong with your zip file.

We had problems with IZArc, we posted on their forum here but 7-Zip and the Windows default zip utility worked fine.

If you’ve tested with the command line, then PLEASE retest it with the UI. Passing the command line test does NOT guarantee it’ll pass with the UI.

There were a few occasions where we tested with the command line and everything passed and installed; however, when we tried again with the UI, it failed since in parameters.xml,, there are a few parameters used by the UI (see Lesson #5).

IIS 7

ASP.NET in IIS 7 runs in 2 modes: Integrated Mode and Classic Application Mode.

If you get an error that looks like this,

[HttpException (0x80004005): Request is not available in this context]
System.Web.HttpContext.get_Request() +8792912
Jumptree.Web.JumptreeBaseHttpModule.Init(HttpApplication httpapp) +45
System.Web.HttpApplication.InitModulesCommon() +65
System.Web.HttpApplication.InitIntegratedModules() +49
System.Web.HttpApplication.InitInternal(HttpContext context, HttpApplicationState state, MethodInfo[] handlers) +729
System.Web.HttpApplicationFactory.GetNormalApplicationInstance(HttpContext context) +298
System.Web.HttpApplicationFactory.GetApplicationInstance(HttpContext context) +107
System.Web.HttpRuntime.ProcessRequestNotificationPrivate(IIS7WorkerRequest wr, HttpContext context) +363

…that means your ASP.NET application initialization has been decoupled from the request that triggered it.

Go to this article for the solution.

Edit: Please see the comment below by “Mike”. In addition, if you have httpmodules like we do in Jumptree, then please include the following structure in order to get it working on IIS 7

<system.webServer>

    <!-- disable runtime rejection of Integrated mode applications that have legacy ASP.NET settings -->
    <validation validateIntegratedModeConfiguration="false" />
    <modules>
        <add name="ProjectAccessModule" type="Jumptree.PM.Web.HttpModule.ProjectsHttpModule"/>
	....
    </modules>
 </system.webServer>

And that's about it. I hope this article serves as a reference for you while packaging for MS PI.

If you want to see an example of this package in action, then simply download our trial and use MS PI to install it.