Developer Notes

Web Deploy : Customizing a deployment package

Posted 13 Feb 2011

Microsoft’s Web Deployment Tool is one of those great improvements for managing ASP.NET applications that I’ve been wanting to give try. Ever since Scott Hanselman wrote about it.

Web Deploy was created to automate common deployment tasks by packaging ASP.NET applications into a .zip with a manifest. It supports both command line deployment and an interactive mode, through the IIS management console.

This post is the result of my first attempt to roll out package based deployment using Web Deploy at a customer.

It’s been sort of a bumpy ride getting everything implemented but the tool definitely delivers what it promises; seamless deployment for your web app.

Here’s what I set out to do:

1. Build a deployment package for an existing application
2. Verify the correct pipeline mode on deployment
3. Include an empty folder (not something supported out of the box, oddly enough)
4. Give write access to specific folders
5. Prevent specific folders from being cleared on deployment
6. Customize the deployment package name to include a version and/or build number

I managed to get all of these implemented, mostly by hand-authoring an MSBuild script. One thing that disappointed me though was that interactive installation does not allow me to prevent specific folders from being cleared. That’s for command line deployment only.

In this post I’ll first give some quick pointers on how to get started with Web Deploy and building packages. After that, I’ll work down the list of requirements posted above one by one.

Note that I’m building the application using Visual Studio 2010 and MSBuild 4. The application targets IIS7, I have not tried this with IIS6.
If you’re not familiar with authoring MSBuild scripts, get the book and read it. I did so a while back and that really helped me.

Build a deployment package

Building a deployment package in Visual Studio 2010 is easy; it’s supported out of the box.

Visual Studio : Build Deployment Package

Using the Package/Publish settings allows you to configure some basic settings like the application name.

Web Deploy 101

To understand what makes Web Deploy tick, open the xml files from the generated package (.zip) in a text editor. The archive.xml file describes what to deploy en how to do it. The parameters.xml file lists all customizable parameters. These can be used to customize deployment after the package has been built.

The build also creates a command script (.cmd) you can use to deploy the application from the command line. (This file is broken however, more on that later). The command file will use the SetParameters.xml file to override default values specified in the parameters.xml file.

There is plenty of good reference documentation for command line use of the Web Deploy tool on TechNet. Check out the section on providers to get a good idea of what Web Deploy can do. For practical how-to’s IIS.NET is the place to look.

For building deployment packages the most useful resource however is the main MSBuild targets file:

 [ProgramFiles]\MSBuild\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.targets

I learned a lot from digging into this file. Thankfully, this file has a lot of hooks you can use to customize your package.

Extending Web Deployment

You can extend the package building pipeline by adding a custom msbuild project file to your application. It should be named [your project].wpp.targets and should be placed in the same folder as the web application project file [see this article]. Set the file to build type None in the properties in Visual Studio to make sure it is not included in the deployment package.

In addition to the custom targets file, you can also add a parameters.xml file. Here you can add configurable parameters to your deployment. This is mostly usefull for interactive deployment. You could for example allow users to modify settings for specific AppSettings. That would look like this:

<?xml version="1.0" encoding="utf-8" ?>
<parameters >
   <parameter name="Admin Email" description="Please provide the e-mail address to notify when errors occur." defaultValue="admin@example.com" tags="">
      <parameterEntry kind="XmlFile" scope="\\web.config$" match="/configuration/appSettings/add[@key='adminEmail']/@value" />
   </parameter>
</parameters>

In this post I’ll focus on the *.wpp.targets file since there is the least documentation on it.

Important: I’ve found that the *.wpp.targets file is not automatically reloaded by Visual Studio. While making changes to the file you’ll probably want to build the package from the command line.

Building a deployment package from the command line

There is no convenient top level target to build a deployment package. I found this method on StackOverflow which works well for me. In a VS 2010 command prompt enter the following command:

msbuild YourSolution.sln /t:rebuild /p:Configuration=Release /p:DeployOnBuild=true;DeployTarget=Package

Create deployment package on a build server

Using the command line above you can get a build server to build a deployment package. The build server should either have Visual Studio 2010 installed or you can use this recipe.

On TeamCity I managed to get the package build using the Visual Studio build runner and some additional command line parameters. The MSBuild build runner should also work.

TeamCity - setup deployment package build

On Hudson I was able to reuse the command line from the previous section, but I had to add the full path to the msbuild executable (i.e. c:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe ).

Verify the pipeline mode on deployment

One of those all important IIS setting is the application pool’s pipeline mode. Newer applications will usually require Integrated mode and will likely break when run in Classic mode. Here’s how to ensure the application pool is in integrated mode:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <DeployManagedPipelineMode>Integrated</DeployManagedPipelineMode>
  </PropertyGroup>
</Project>

.There are a couple of basic settings you can check / enforce through properties:

Take a look at the targets file that is used to build the package for more properties:

[ProgramFiles]\MSBuild\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.targets

Include an empty folder

By default, the web deployment build scripts will filter out empty folders. In most cases that’s a good thing, for example for folders with code like /controllers in an MVC application. This folder will be empty if the application is pre-compiled and can safely be removed before deployment.

In some cases however you may want to include a folder to hold temporary data, uploaded files, cached files or whatever. There’s two ways to go about this:

1. Include a placeholder file to make the folder non-empty
2. Create the folder in the package location

I find the second option more elegant. Here’s what the msbuild script looks like:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <AfterAddIisSettingAndFileContentsToSourceManifest>MakeEmptyFolders</AfterAddIisSettingAndFileContentsToSourceManifest>
  </PropertyGroup>
  <Target Name="MakeEmptyFolders">
    <Message Text="Adding empty folder to hold downloads" />
    <MakeDir Directories="$(_MSDeployDirPath_FullPath)\Downloads"/>
  </Target>
</Project>

The propery AfterAddIisSettingAndFileContentsToSourceManifest holds the names of targets that will be invoked after the contents for the deployment package has been prepared. This is the perfect time to add additional files or folders to the package.

Give write access to specific folders

The empty folder created above should also be writeable so that the administrative users can upload files into it. There are a couple of resources describing this, but none that capture the complete picture.

The Web Deployment tool has a provider specifically for this purpose; setAcl. This provider will conveniently apply the rights you specify for the application pool identity. However, the setAcl rule in the deployment manifest needs a scope to be able to determine the application pool identity for the target folder or file. It took some digging into Microsoft.Web.Publishing.targets and lots of trial-and-error to figure this one out. In msbuild it looks like this:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <PropertyGroup>
    <AfterAddIisSettingAndFileContentsToSourceManifest>SetCustomACLs</AfterAddIisSettingAndFileContentsToSourceManifest>
    <AfterAddDeclareParametersItemsForContentPath>SetCustomAclParameters</AfterAddDeclareParametersItemsForContentPath>
  </PropertyGroup>


  <Target Name="SetCustomACLs">
    <Message Text="Adding Custom ACls" />
    <!-- Create empty folders -->
    <MakeDir Directories="$(_MSDeployDirPath_FullPath)\Downloads"/>
    <ItemGroup>
     <!--Make sure the application pool identity has write permission to the download folder -->
     <MsDeploySourceManifest Include="setAcl"
       Condition="$(IncludeSetAclProviderOnDestination) And Exists('$(_MSDeployDirPath_FullPath)\Downloads')">
      <Path>$(_MSDeployDirPath_FullPath)\Downloads</Path>
      <setAclAccess>Write</setAclAccess>
      <setAclResourceType>Directory</setAclResourceType>
      <AdditionalProviderSettings>setAclResourceType;setAclAccess</AdditionalProviderSettings>
     </MsDeploySourceManifest>
    </ItemGroup>
  </Target>
  <Target Name="SetCustomAclParameters">
    <EscapeTextForRegularExpressions Text="$(_MSDeployDirPath_FullPath)">
      <Output TaskParameter="Result" PropertyName="_EscapeRegEx_MSDeployDirPath" />
    </EscapeTextForRegularExpressions>
    <ItemGroup>
     <MsDeployDeclareParameters Include="Add write permission to Downloads folder"
      Condition="$(IncludeSetAclProviderOnDestination) and Exists('$(_MSDeployDirPath_FullPath)\Downloads')">
      <Kind>ProviderPath</Kind>
      <Scope>setAcl</Scope>
      <Match>^$(_EscapeRegEx_MSDeployDirPath)\\Downloads$</Match>
      <Description>Add write permission to Downloads folder</Description>
      <DefaultValue>{IIS Web Application Name}/Downloads</DefaultValue>
      <Value>$(_DestinationContentPath)/Downloads</Value>
      <Tags>Hidden</Tags>
      <Priority>$(VsSetAclPriority)</Priority>
      <ExcludeFromSetParameter>True</ExcludeFromSetParameter>
     </MsDeployDeclareParameters>
    </ItemGroup>
  </Target>
</Project>

There are two targets declared and hooked into the packaging pipeline. The first target, SetCustomACLs, is an extension of the empty folder solution discussed earlier. The empty folder is created and then the task MsDeploySourceManifest is invoked to make sure the required parameters are emitted to add the setAcl rules to the package manifest.

The second target, SetCustomAclParameters, is invoked to add the required parameters to setup the scope for the setAcl provider rules. The parameters are regular expression based so the base path ( in the _MSDeployDirPath_FullPath parameter) is escaped for use in a regular expression. Most of this is copied straight from Microsoft.Web.Publishing.targets where by default write access is assigned to the App_Data folder.

Prevent specific folders from being cleared on deployment

Assume that the downloads folder we’ve been working on up till now is in a production site. Files have been uploaded into that folder so they can be downloaded. Now you need to deploy a new version of the application. The default behavior for Web Deploy is to clear out any and all content that’s not in the deployment package. That would mean all the uploaded files are deleted. Not a good thing.

You could change the default behavior and disable clearing of the site. But that could mean stale files (like .aspx files) are left behind. Not a good thing either.

Fortunately, Web Deploy supports so called skip rules. A skip rule is used to exclude files or folders from a particular operation (Update, Delete, AddChild). In this case we want to prevent the Delete operation from being applied to the Downloads directory. That would look like this:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <OnBeforePackageUsingManifest>AddCustomSkipRules</OnBeforePackageUsingManifest>
  </PropertyGroup>
  <Target Name="AddCustomSkipRules">
    <ItemGroup>
      <MsDeploySkipRules Include="SkipDownloadsFiles">
        <SkipAction>Delete</SkipAction>
        <ObjectName>filePath</ObjectName>
        <AbsolutePath>.*\\Downloads\\.*$</AbsolutePath>
        <XPath></XPath>
      </MsDeploySkipRules>
      <MsDeploySkipRules Include="SkipDownloadsFolder">
        <SkipAction>Delete</SkipAction>
        <ObjectName>dirPath</ObjectName>
        <AbsolutePath>.*\\Downloads\\.*$</AbsolutePath>
        <XPath></XPath>
      </MsDeploySkipRules>
    </ItemGroup>
  </Target>
</Project>

The ObjectName should be dirPath for directories and filePath for files. The AbsolutePath element contains a regular expression that will be matched against the name or file or folder. Note that a directory name should end with a back-slash. In this example I’ve added a second skip rule make sure any files in subfolders are left untouched as well.

If a folder is skipped it automatically means that any file in that folder is skipped as well.

Warning : skip rules work only when deploying from the command line, using the generated command file. They are not included in the package manifest and will not be applied when deploying the package in intractive mode (ie. through IIS Manager).

Customize the deployment package name to include a version and/or build number

Finally, when building releases on a build server it’s nice to have the build artifacts named after the version or build number so that you know from the file name what version it is.

Visual Studio uses the PackageFileName property for this. We can override that in the  *.wpp.targets file:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <__ProductVersion Condition="'$(__ProductVersion)'=='' AND '$(VERSION)'!='' AND '$(REVISION)'!=''">$(VERSION).$(REVISION)</__ProductVersion>
    <__ProductVersion Condition="'$(__ProductVersion)'=='' AND '$(BUILD_NUMBER)'!=''">$(BUILD_NUMBER)</__ProductVersion>
    <__ProductVersion Condition="'$(__ProductVersion)'==''">dev</__ProductVersion>
    <PackageFileName Condition="'$(BuildingInsideVisualStudio)' != 'true'">..\..\Build\$(MSBuildProjectName)-$(__ProductVersion).zip</PackageFileName>
  </PropertyGroup>
</Project>

This MSBuild snippet uses a couple of variables to determine the product version, captured in the __ProductVersion property. Exactly how these properties are set is outside the scope of this post. They could be environment variables or they could come from the main project file for example. In this particular case the Hudson build will set the VERSION and REVISION properties. If those are not set, the BUILD_NUMBER will be used. This property is set by the TeamCity build server to increment on each build. If that is not available either the build is assumed to be from the command line on a development system, hence __ProductVersion is set to dev.

Finally, the PackageFileName property is set. This is the property used by the web packaging build to determine the package file name and path. In this sample, the package will be created in the Build folder and will be named after the main project, suffixed with the product version. Also note that the BuildingInsideVisualStudio property will be set to true if we’re building in Visual Studio. In that case we’ll use whatever was defined in the Publish & Package settings for the project.

If we’re modifying the package file name to change with every build we also need to add some additional logic to clean up older versions. Here’s how to do that:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <CleanDependsOn>
      $(CleanDependsOn);
      CleanAllPackagesFromBuildFolder;
    </CleanDependsOn>
    <Target Name="CleanAllPackagesFromBuildFolder">
    <ItemGroup>
      <__BuildFolderCleanup Include="..\..\Build\$(MSBuildProjectName)*"/>
    </ItemGroup>
    <Delete Files="@(__BuildFolderCleanup)"
          Condition="Exists('..\..\Build')"
          TreatErrorsAsWarnings="True"  />
  </Target>
</Project>

First the Clean target is extended to run our custom cleanup target by modifying the CleanDepensOn property. The CleanAllPackagesFromBuildFolder target then proceeds to delete all files from the Build folder. That’s the folder we indicated our package should be created.

Fixing the MSDeploy version

The steps above customize the generated package and the build process so that all the requirements I listed at the beginning of this post are met. Unfortunately, the Microsoft.Web.Publishing.targets file that shipped with Visual Studio 2010 is not quite up to date. Web Deployment Tool v2 has shipped recently but targets file is hard coded to generate a command file for version 1.

The command script uses a registry key to determine where msdeploy.exe is installed:

HKLM\SOFTWARE\Microsoft\IIS Extensions\MSDeploy\1

Unfortunately, if you install only the latest release this key does not exist and the script will fail. The fix is simple; replace the 1 at the end with a 2. Here’s how that looks in msbuild:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <OnAfterPackageUsingManifest>
		$(OnAfterPackageUsingManifest);
		FixMsDeployVersion;
    </OnAfterPackageUsingManifest>
  </PropertyGroup>
  <Target Name="FixMsDeployVersion" DependsOnTargets="GenerateSampleDeployScript">
	<PropertyGroup>
		<__DeployScriptLocation>$(GenerateSampleDeployScriptLocation)</__DeployScriptLocation>
		<__DeployScriptContents>$([System.IO.File]::ReadAllText('$(__DeployScriptLocation)'))</__DeployScriptContents>
	</PropertyGroup>	
	<WriteLinesToFile File="$(GenerateSampleDeployScriptLocation)"
               Overwrite="True"
               Encoding="us-ascii"
               Lines="$(__DeployScriptContents.Replace('HKLM\SOFTWARE\Microsoft\IIS Extensions\MSDeploy\1', 'HKLM\SOFTWARE\Microsoft\IIS Extensions\MSDeploy\2'))"/>
  </Target>
</Project>

PackageUsingManifest is the main target performing the package generation. When it’s done we want to do our final fix of the command script. We hook in our target by modifying the OnAfterPackageUsingManifest property. To make sure our target is executed after the deploymeny command script is generated a dependency on the GenerateSampleDeployScript is added to our target.

The FixMsDeployVersion target itself pulls in the entire command script from disk and does a String.Replace on it to fix the registry key before writing the whole file back to disk.

Conclusion

The Web Deploy tool offers a lot to ease the deployment of ASP.NET applications. Tailoring the build to match every day deployment requirements is possible but by no means easy. I’ve had to do a lot of digging into the bowels of the build targets file to find the right extension points. As far as I know, there is no documentation on the MSBuild tasks used by the packaging pipeline.

The fact that interactive deployment does not support skip rules is really a huge mistake. That and the fix needed for the command script are things that would prevent me from rolling out the web deployment tool at a customer.

However, once the deployment package is customized it’s just so easy to deploy a new version. No more diffing directories when deploying an update. No more last minute phone calls when deploying to production because somebody forgot to create a folder or set the appropriate access rights.
This is a huge win for developers and QA people needing to deploy new versions often for testing as well as for IT people that need to deploy to production.

[Update 2012-11-29] The code sample for preventing folders and their contents from being deleted was not quite perfect. Turns out it’s needed to exclude both the folder (and sub folders) and the files.