I received a customer email asking how they can take their web application/site offline for the entire duration that a publish is happening from Visual Studio. An easy way to take your site offline is to drop an app_offline.htm file in the sites root directory. For more info on that you can read ScottGu’s post, link in below in resources section. Unfortunately Web Deploy itself doesn’t support this . If you want Web Deploy (aka MSDeploy) to natively support this feature please vote on it at http://aspnet.uservoice.com/forums/41199-general/suggestions/2499911-take-my-site-app-offline-during-publishing.

Since Web Deploy doesn’t support this it’s going to be a bit more difficult and it requires us to perform the following steps:

1. Publish app_offline.htm
2. Publish the app, and ensure that app_offline.htm is contained inside the payload being published
3. Delete app_offline.htm

#1 will take the app offline before the publish process  begins.
#2 will ensure that when we publish that app_offline.htm is not deleted (and therefore keep the app offline)
#3 will delete the app_offline.htm and bring the site back online

Now that we know what needs to be done let’s look at the implementation. First for the easy part. Create a file in your Web Application Project (WAP) named app_offline-template.htm. This will be the file which will end up being the app_offline.htm file on your target server. If you leave it blank your users will get a generic message stating that the app is offline, but it would be better for you to place static HTML (no ASP.NET markup) inside of that file letting users know that the site will come back up and whatever other info you think is relevant to your users. When you add this file you should change the Build Action to None in the Properties grid. This will make sure that this file itself is not published/packaged. Since the file ends in .htm it will by default be published. See the image below.

Now for the hard part. For Web Application Projects we have a hook into the publish/package process which we refer to as “wpp.targets”. If you want to extend your publish/package process you can create a file named {ProjectName}.wpp.targets in the same folder as the project file itself. Here is the file which I created you can copy and paste the content into your wpp.targets file. I will explain the significant parts but wanted to post the entire file for your convince. Note: you can grab my latest version of this file from my github repo, the link is in the resource section below.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="InitalizeAppOffline">
    <!-- 
    This property needs to be declared inside of target because this is imported before
    the MSDeployPath property is defined as well as others -->
    <PropertyGroup>
      <MSDeployExe Condition=" '$(MSDeployExe)'=='' ">$(MSDeployPath)msdeploy.exe</MSDeployExe>
    </PropertyGroup>    
  </Target>

  <PropertyGroup>
    <PublishAppOfflineToDest>
      InitalizeAppOffline;
    </PublishAppOfflineToDest>
  </PropertyGroup>

  <!--
    %msdeploy% 
      -verb:sync 
      -source:contentPath="C:\path\to\app_offline-template.htm" 
      -dest:contentPath="Default Web Site/AppOfflineDemo/app_offline.htm"
  -->

  <!--***********************************************************************
  Make sure app_offline-template.htm gets published as app_offline.htm
  ***************************************************************************-->
  <Target Name="PublishAppOfflineToDest" 
          BeforeTargets="MSDeployPublish" 
          DependsOnTargets="$(PublishAppOfflineToDest)">
    <ItemGroup>
      <_AoPubAppOfflineSourceProviderSetting Include="contentPath">
        <Path>$(MSBuildProjectDirectory)\app_offline-template.htm</Path>
        <EncryptPassword>$(DeployEncryptKey)</EncryptPassword>
        <WebServerAppHostConfigDirectory>$(_MSDeploySourceWebServerAppHostConfigDirectory)</WebServerAppHostConfigDirectory>
        <WebServerManifest>$(_MSDeploySourceWebServerManifest)</WebServerManifest>
        <WebServerDirectory>$(_MSDeploySourceWebServerDirectory)</WebServerDirectory>
      </_AoPubAppOfflineSourceProviderSetting>

      <_AoPubAppOfflineDestProviderSetting Include="contentPath">
        <Path>"$(DeployIisAppPath)/app_offline.htm"</Path>
        <ComputerName>$(_PublishMsDeployServiceUrl)</ComputerName>
        <UserName>$(UserName)</UserName>
        <Password>$(Password)</Password>
        <EncryptPassword>$(DeployEncryptKey)</EncryptPassword>
        <IncludeAcls>False</IncludeAcls>
        <AuthType>$(AuthType)</AuthType>
        <WebServerAppHostConfigDirectory>$(_MSDeployDestinationWebServerAppHostConfigDirectory)</WebServerAppHostConfigDirectory>
        <WebServerManifest>$(_MSDeployDestinationWebServerManifest)</WebServerManifest>
        <WebServerDirectory>$(_MSDeployDestinationWebServerDirectory)</WebServerDirectory>
      </_AoPubAppOfflineDestProviderSetting>
    </ItemGroup>

    <MSdeploy
          MSDeployVersionsToTry="$(_MSDeployVersionsToTry)"
          Verb="sync"
          Source="@(_AoPubAppOfflineSourceProviderSetting)"
          Destination="@(_AoPubAppOfflineDestProviderSetting)"
          EnableRule="DoNotDeleteRule"
          AllowUntrusted="$(AllowUntrustedCertificate)"
          RetryAttempts="$(RetryAttemptsForDeployment)"
          SimpleSetParameterItems="@(_AoArchivePublishSetParam)"
          ExePath="$(MSDeployPath)" />
  </Target>

  <!--***********************************************************************
  Make sure app_offline-template.htm gets published as app_offline.htm
  ***************************************************************************-->
  <!-- We need to create a replace rule for app_offline-template.htm->app_offline.htm for when the app get's published -->
  <ItemGroup>
    <!-- Make sure not to include this file if a package is being created, so condition this on publishing -->
    <FilesForPackagingFromProject Include="app_offline-template.htm" Condition=" '$(DeployTarget)'=='MSDeployPublish' ">
      <DestinationRelativePath>app_offline.htm</DestinationRelativePath>
    </FilesForPackagingFromProject>

    <!-- This will prevent app_offline-template.htm from being published -->
    <MsDeploySkipRules Include="SkipAppOfflineTemplate">
      <ObjectName>filePath</ObjectName>
      <AbsolutePath>app_offline-template.htm</AbsolutePath>
    </MsDeploySkipRules>
  </ItemGroup>

  <!--***********************************************************************
  When publish is completed we need to delete the app_offline.htm
  ***************************************************************************-->
  <Target Name="DeleteAppOffline" AfterTargets="MSDeployPublish">
    <!--
    %msdeploy% 
      -verb:delete 
      -dest:contentPath="{IIS-Path}/app_offline.htm",computerName="...",username="...",password="..."
    -->
    <Message Text="************************************************************************" />
    <Message Text="Calling MSDeploy to delete the app_offline.htm file" Importance="high" />
    <Message Text="************************************************************************" />

    <ItemGroup>
      <_AoDeleteAppOfflineDestProviderSetting Include="contentPath">
        <Path>$(DeployIisAppPath)/app_offline.htm</Path>
        <ComputerName>$(_PublishMsDeployServiceUrl)</ComputerName>
        <UserName>$(UserName)</UserName>
        <Password>$(Password)</Password>
        <EncryptPassword>$(DeployEncryptKey)</EncryptPassword>
        <AuthType>$(AuthType)</AuthType>
        <WebServerAppHostConfigDirectory>$(_MSDeployDestinationWebServerAppHostConfigDirectory)</WebServerAppHostConfigDirectory>
        <WebServerManifest>$(_MSDeployDestinationWebServerManifest)</WebServerManifest>
        <WebServerDirectory>$(_MSDeployDestinationWebServerDirectory)</WebServerDirectory>
      </_AoDeleteAppOfflineDestProviderSetting>
    </ItemGroup>
    
    <!-- 
    We cannot use the MSDeploy/VSMSDeploy tasks for delete so we have to call msdeploy.exe directly.
    When they support delete we can just pass in @(_AoDeleteAppOfflineDestProviderSetting) as the dest
    -->
    <PropertyGroup>
      <_Cmd>"$(MSDeployExe)" -verb:delete -dest:contentPath="%(_AoDeleteAppOfflineDestProviderSetting.Path)"</_Cmd>
      <_Cmd Condition=" '%(_AoDeleteAppOfflineDestProviderSetting.ComputerName)' != '' ">$(_Cmd),computerName="%(_AoDeleteAppOfflineDestProviderSetting.ComputerName)"</_Cmd>
      <_Cmd Condition=" '%(_AoDeleteAppOfflineDestProviderSetting.UserName)' != '' ">$(_Cmd),username="%(_AoDeleteAppOfflineDestProviderSetting.UserName)"</_Cmd>
      <_Cmd Condition=" '%(_AoDeleteAppOfflineDestProviderSetting.Password)' != ''">$(_Cmd),password=$(Password)</_Cmd>
      <_Cmd Condition=" '%(_AoDeleteAppOfflineDestProviderSetting.AuthType)' != ''">$(_Cmd),authType="%(_AoDeleteAppOfflineDestProviderSetting.AuthType)"</_Cmd>
    </PropertyGroup>

    <Exec Command="$(_Cmd)"/>
  </Target>  
</Project>

#1 Publish app_offline.htm

The implementation for #1 is contained inside the target PublishAppOfflineToDest. The msdeploy.exe command that we need to get executed is.

msdeploy.exe
    -source:contentPath='C:\Data\Personal\My Repo\sayed-samples\AppOfflineDemo01\AppOfflineDemo01\app_offline-template.htm'
    -dest:contentPath='"Default Web Site/AppOfflineDemo/app_offline.htm"',UserName='sayedha',Password='password-here',ComputerName='computername-here',IncludeAcls='False',AuthType='NTLM' -verb:sync -enableRule:DoNotDeleteRule

In order to do this I will leverage the MSDeploy task. Inside of the PublishAppOfflineToDest target you can see how this is accomplished by creating an item for both the source and destination.

#2 Publish the app, and ensure that app_offline.htm is contained inside the payload being published

This part is accomplished by the fragment

  <!--***********************************************************************
  Make sure app_offline-template.htm gets published as app_offline.htm
  ***************************************************************************-->
  <!-- We need to create a replace rule for app_offline-template.htm->app_offline.htm for when the app get's published -->
  <ItemGroup>
    <!-- Make sure not to include this file if a package is being created, so condition this on publishing -->
    <FilesForPackagingFromProject Include="app_offline-template.htm" Condition=" '$(DeployTarget)'=='MSDeployPublish' ">
      <DestinationRelativePath>app_offline.htm</DestinationRelativePath>
    </FilesForPackagingFromProject>

    <!-- This will prevent app_offline-template.htm from being published -->
    <MsDeploySkipRules Include="SkipAppOfflineTemplate">
      <ObjectName>filePath</ObjectName>
      <AbsolutePath>app_offline-template.htm</AbsolutePath>
    </MsDeploySkipRules>
  </ItemGroup>

The item value for FilesForPackagingFromProject here will convert your app_offline-template.htm to app_offline.htm in the folder from where the publish will be processed. Also there is a condition on it so that it only happens during publish and not packaging. We do not want app_offline-template.htm to be in the package (but it’s not the end of the world if it does either).

The element for MsDeploySkiprules will make sure that app_offline-template.htm itself doesn’t get published. This may not be required but it shouldn’t hurt.

#3 Delete app_offline.htm

Now that our app is published we need to delete the app_offline.htm file from the dest web app. The msdeploy.exe command would be:

%msdeploy%
      -verb:delete
      -dest:contentPath="{IIS-Path}/app_offline.htm",computerName="...",username="...",password="..."

This is implemented inside of the DeleteAppOffline target. This target will automatically get executed after the publish because I have included the attribute AfterTargets=”MSDeployPublish”. In that target you can see that I am building up the msdeploy.exe command directly, it looks like the MSDeploy task doesn’t support the delete verb.

If you do try this out please let me know if you run into any issues. I am thinking to create a Nuget package from this so that you can just install that package. That would take a bit of work so please let me know if you are interested in that.

Resources

1. The latest version of my AppOffline wpp.targets file.
2. ScottGu’s blog on app_offline.htm

 

Sayed Ibrahim Hashimi @SayedIHashimi

Note: I’d like to thank Tom Dykstra for helping me put this together

Overview

In this tutorial you'll see how to use a web deployment package package to deploy an application. A deployment package is a .zip file that includes all of the content and metadata that's required to deploy an application.

Deployment packages are often used in enterprise environments. This is because a developer or a continuous integration server can create the package without needing to know things like passwords that are stored in Web.config files. Only the server administrator who actually installs the package needs to know those passwords, and that person can enter the details at installation time.

In a smaller organization that doesn't have separate people for these roles, there's less need for deployment packages. But you can also use deployment packages as a way to back up and restore the state of an application. After you use a deployment package to deploy, you can save the package,. Then if a subsequent deployment has a problem, you can quickly and easily restore the application state to the earlier state by reinstalling the earlier package. (This scenario is more complicated if database changes are involved, however.)

This tutorial shows how to use Visual Studio to create a package and IIS Manager to install it. For information about how to create and install packages using the command line, see ASP.NET Deployment Content Map on the MSDN web site.

To keep things relatively simple, this example assumes you have already deployed the application and its databases, and you only need to deploy a code update. You have made the code update, and you are ready to deploy it first to your test environment (IIS on your local computer) and then to your hosting provider. You have a Test build configuration that you use for the test environment and you use the Release build configuration for the production environment. In the example, the name of the Visual Studio project is ContosoUniversity, and instructions for its initial deployment can be found in a series of tutorials that will be published in December on the ASP.NET web site.

The hosting provider shown, Cytanium.com, is one of many that are available, and its use here does not constitute an endorsement or recommendation.

Note The following example uses separate packages for the test and production environments, but you can also create a single deployment package that can be used for both environments. This would require that you use Web Deploy parameters instead of Web.config transformations for Web.config file changes that depend on deployment destination. For information about how to use Web Deploy parameters, see How to: Use Parameters to Configure Deployment Settings When a Package is Installed.

Configuring the Deployment Package

In this section, you'll configure settings for the deployment package. Some of these settings are the same ones that you set also for one-click publish, others are only for deployment packages.

Open the Package/Publish Web tab of the Project Properties window and select the Test build configuration.

For this deployment you aren't making any database changes, so clear Include all databases configured in Package/Publish SQL tab. Make sure Exclude files from the App_Data folder is selected.

Review the settings in the section labeled Web Deployment Package Settings:

• By default, deployment packages are created as .zip files. You don't need to change this setting.
• By default, deployment packages are created in the project's obj\Test\Package folder. You don't need to change this setting.
• The default IIS web application name is the name of the project with "_deploy" appended to it. Remove that suffix. You want the application to be named just ContosoUniversity in IIS on your computer.
• For this tutorial you're not deploying IIS settings, so you don't need to enter a password for that.

The Package/Publish Web tab now looks like this:

You also need to configure settings for deploying to the production environment. Select the Release build configuration to do that.

Change IIS Web site/application name to use on the destination server to a string that will serve as a reminder of what you need to do later when this value is displayed in the IIS Manager UI: "[clear this field]". The text box on this page won't stay cleared even if you clear it, so entering this note to yourself will remind you to clear this value later when you deploy. When you deploy to your hosting provider, you will connect to a site, not to a server, and in this case you want to deploy to the root of the site.

Creating a Deployment Package for the Test Environment

To create a deployment package, first make sure you've selected the right build configuration. In the Solution Configurations drop-down box, select Test.

In Solution Explorer, right-click the project that you want to build the package for and then select Build Deployment Package.

The Output window reports successful a build and publish (package creation) and tells you where the package was created.

Installing the Deployment Package in the Test Environment

The next step is to install the deployment package in IIS on your development computer.

Run IIS Manager. In the Connections pane of the IIS Manager window, expand the local server node, expand the Sites node, and select Default Web Site. Then in the Actions pane, click Import Application. (If you don't see an Import Application link, the most likely reason is that you have not installed Web Deploy. You can use the Web Platform Installer to install both IIS and Web Deploy.)

In the Select the Package wizard step, navigate to the location of the package you just created. By default, that's the obj\Test\Package folder in your ContosoUniversity project folder. (A package created with the Release build configuration would be in obj\Release\Package.)

Click Next. The Select the Contents of the Package step is displayed.

Click Next.

The step that allows you to enter parameter values is displayed. The Application Path value defaults to "ContosoUniversity", because that's what you entered on the Package/Publish Web tab of the Project Properties window.

Click Next.

The wizard asks if you want to delete files at the destination that aren't in the source.

In this case you haven't deleted any files that you want to delete at the destination, so the default (no deletions) is okay. Click Next.

IIS Manager installs the package and reports its status.

Click Finish.

Open a browser and run the application in test by going to the URL http://localhost/ContosoUniversity.

Installing IIS Manager for Remote Administration

The process for deploying to production is similar except that you create the package using the Release build configuration, and you install it in IIS Manager using a remote connection to the hosting provider. But first you have to install the IIS Manager feature that facilitates remote connections.

Click the following link to use the Web Platform Installer for this task:

• IIS Manager for Remote Administration v1.1

Connecting to Your Site at the Hosting Provider

After you install the IIS Manager for Remote Administration, run IIS Manager. You see a new Start Page in IIS Manager that has several Connect to ... links in a Connection tasks box. (These options are also available from the File menu.)

In IIS Manager, click Connect to a site. In the Specify Site Connection Details step, enter the Server name and Site name values that are assigned to you by your provider, and then click Next. For a hosting account at Cytanium.com, you get the server name from Service URL in the Visual Studio 2010 section of the welcome email. The site name is indicated by "Site/application" in the same section of the email.

In the Provide Credentials step, enter the user name and password assigned by the provider, and then click Next:

You might see a Server Certificate Alert dialog box. If you're sure that you've entered the correct server and site name, click Connect.

In the Specify a Connection Name step, click Finish.

After IIS Manager connects to the provider's server, a New Feature Available dialog box might appear that lists administration features available for download. Click Cancel — you've already installed everything you need for this deployment.

After the New Feature Available box closes, the IIS Manager window appears. There's now a node in the Connections pane for the site at the hosting provider.

Creating a Package for the Production Site

The next step is to create a deployment package for the production environment. In the Visual Studio Solution Configurations drop-down box, select the Release build configuration.

In Solution Explorer, right-click the ContosoUniversity project and then select Build Deployment Package.

The Output window reports a successful build and publish (package creation), and it tells you that the package is created in the obj\Release\Package folder in your project folder.

Installing the Package in the Production Environment

Now you can install the package in the production environment. In the IIS Manager Connections pane, select the new connection you added earlier. Then click Import Application, which will walk you through the same process you followed earlier when you deployed to the test environment.

In the Select the Package step, select the package that you just created:

In the Select the Contents of the Package step, leave all the check boxes selected and click Next:

In the Enter Application Package Information step, clear the Application Path and click Next:

The wizard asks if you want to delete files at the destination that aren't in the source.

You don't need to have anything deleted, so just click Next.

When you get the warning about installing to the root folder, click OK:

Package installation begins. When it's done, the Installation Progress and Summary dialog box is shown:

Click Finish. Your application has been deployed to the hosting provider's server, and you can test by browsing to your public site's URL.

You've now seen how to deploy an application update by manually creating and installing a deployment package. For information about how to create and install packages from the command line in order to be able to integrate them into a continuous integration process, see the ASP.NET Deployment Content Map on the MSDN web site.

Sayed Ibrahim Hashimi – @SayedIHashimi

ddd

Back in November I participated in Virtual Tech Days which is an online conference presented by Microsoft. In the session I discussed the enhancements to web deployment using Visual Studio 2010 and MSDeploy. Some of the topics which I covered includ:

• web.conig (XDT) transforms
• How to publish to local file system using Visual Studio
• How to publish to a 3rd party host using Visual Studio via MSDeploy
• How to publish to local IIS server using the .cmd file generated by Visual Studio
• How to use msdeploy.exe to delete IIS applications
• How to use the IIS Manager to import web packages
• How to use msdeploy.exe to deploy a web package to the local IIS server
• How to use msdeploy.exe to deploy a web package to a remove IIS server
• How to use msdeploy.exe to deploy a web package & set parameters using SetParameters.xml to a remote IIS server

You can download the video & all of my sample files at http://virtualtechdays.com/pastevents_2010november.aspx. In the samples you will find all of the scripts that I used and a bunch of others which I didn’t have time to cover. Enjoy!

Sayed Ibrahim Hashimi @sayedihashimi

I just saw a post on twitter asking the question

Is there any easy way to see the underlying MSBuild command when building in VS2010? Want to see the MSDeploy params. @wdeploy?

This is actually pretty easy, but wouldn’t fit into 140 characters, so I decided to blog it.

One thing to know is that when you publish from Visual Studio, by default we use the MSDeploy (AKA Web Deployment Tool) Object Model in order to perform the deployment. We do this for performance and other reasons. Because of this there is no real msdeploy.exe command that is being issued. You can however change that behavior. This is controlled by an MSBuild property UseMSDeployExe which is false by default. In this case since Troy wants to see the command we will need to set that property to false. There are 2 ways in which you can do this. You can set it in the project file itself, or you can define it in a .wpp.targets file. I would recommend the second approach. What you need to do is to create a file with the name {ProjectName}.wpp.targets in the same directory as the project where {ProjectName} is the name of the Web Application Project (WAP). When you do this, during a build or publish the file is automatically imported into the build process. In my example I have a WAP named WebApplication1.csproj, so I created the file WebApplication1.wpp.targets and its contents are shown below.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Build" 
         xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <UseMsdeployExe>true</UseMsdeployExe>
  </PropertyGroup>
</Project>

In the snippet above you can see that I defined the property to true. Now there is one more thing to do, publish the project. Once you publish the project, in the output window you will see the MSDeploy command which is being used. In my case I published the project to localhost to the Default Web Site/Test01 application path. You may have to copy the text from the output window into Notepad and search for msdeploy.exe. The command that was issued in my case is shown below (with formatting changes for readability).

"C:\Program Files (x86)\IIS\Microsoft Web Deploy\msdeploy.exe" 
-source:manifest='C:\temp\_NET\ThrowAway\WebApplication3\WebApplication1\obj\Debug\Package\WebApplication1.SourceManifest.xml' 
-dest:auto,IncludeAcls='False',AuthType='NTLM' 
-verb:sync 
-enableRule:DoNotDeleteRule 
-disableLink:AppPoolExtension 
-disableLink:ContentExtension 
-disableLink:CertificateExtension 
-setParam:kind='ProviderPath',
    scope='IisApp',match='^C:\\temp\\_NET\\ThrowAway\\WebApplication3\\WebApplication1\\obj\\Debug\\Package\\PackageTmp$',
    value='Default Web Site/Test01' 
-setParam:kind='ProviderPath',
    scope='setAcl',
    match='^C:\\temp\\_NET\\ThrowAway\\WebApplication3\\WebApplication1\\obj\\Debug\\Package\\PackageTmp$',
    value='Default Web Site/Test01' 
-retryAttempts=2 

So that’s it, pretty simple.

FYI, if you want more detail you can increase the MSBuild Output Window verbosity by going to Tools->Options->Projects and Solutions->Build and Run then specifying a different value for MSBuild project build output verbosity.

Sayed Ibrahim Hashimi - @sayedihashimi

A while back I posted an entry on How to build a package including extra files or exclude files a reader posted a question to StackOverflow.com asking how to exclude files from the created package based on the configuration for the project. He asked me to take a look at it so I figured it would be a good blog post.

From the previous post we can see that the way to exclude files from packaging is by declaring an item as follows.

<ItemGroup>
  <ExcludeFromPackageFiles Include="Sample.Debug.xml">
    <FromTarget>Project</FromTarget>
  </ExcludeFromPackageFiles>
</ItemGroup>

So we need to extend this to only exclude files if the config is a certain value. Since MSBuild supports conditions on almost every element this is going to be a breeze. As an example I have created a sample web project with a scripts directory that has the following files.

In that folder there I there are two files which have ‘debug’ in the name of the file. We only want those to be included if the configuration is set to Debug, or another way of putting it is we want to exclude those files if the configuration is not Debug. So we need to create to add files to the ExcludeFromPackageFiles and guard it with the condition that the configuration is not debug. Here is that.

<Target Name="CustomExlucdeFiles" BeforeTargets="ExcludeFilesFromPackage">
  <ItemGroup Condition=" '$(Configuration)'!='Debug' ">
    <ExcludeFromPackageFiles Include="scripts\**\*debug*" />
  </ItemGroup>
  
  <Message Text="Configuration: $(Configuration)" />
  <Message Text="ExcludeFromPackageFiles: @(ExcludeFromPackageFiles)" Importance="high" />
</Target>

You can see the item group defined above which does what we want. Please note that I put this inside of a target, CustomExcludeFiles, I will discuss why in a bit but let’s stay on topic now. So this is pretty straight forward when the item group is evaluated all files under scripts which have debug in the file name will be excluded if the configuration is not set to Debug. Let’s see if it works, I will build the deployment package once in both debug & release then examine the contents of the Package folder.

So we can see that the files were excluded from the Release package. Now back to why I declared the item group in a target instead of directly in the project file itself. I noticed that if I declare that item in the project file there are some visual issues with the representation in the Solution Explorer. To be specific the files show up as dups, see image below.

I have reported this to the right people, but for now this is a harmless issue with an easy workaround.

Sayed Ibrahim Hashimi

If you are using Visual Studio 2010 then you may already be aware that Web Deployment Tool (aka MSDeploy) is integrated into Visual Studio. I’ve posted a few blog entries already about this tool. Two of the common questions that I get discussing this with people are

1. How do I exclude files from being placed in the package?
2. How do I add other files to the created package?

I will address these two questions here, first we look at the easier one, how to exclude files but we will go over a bit of background first.

Web Publishing Pipeline

With Visual Studio 2010 a new concept has been created which is known as the Web Publishing Pipeline. In a nutshell this is a process which will take your web application, build it and eventually create a package that you can use to deploy your application. This process is fully captured in MSBuild. With VS 2010 many targets and many tasks are shipped to support this process. Since its captured in MSBuild format, you can customize and extend to your hearts desire. So what we need to do is hook into this process to perform the customizations that we need. This process is captured in the following files.

%program files%\MSBuild\Microsoft\VisualStudio\v10.0\WebApplications\Microsoft.WebApplication.targets
%program files%\MSBuild\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.targets

The Microsoft.WebApplication.targets file is imported by the web applications projects file, then that file imports the Microsoft.Web.Publishing.targets file.

Excluding files from being packaged

If you open the project file of a web application created with VS 2010 towards the bottom of it you will find a line with.

<Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v10.0\WebApplications\Microsoft.WebApplication.targets" />

BTW you can open the project file inside of VS. Right click on the project pick Unload Project. Then right click on the unloaded project and select Edit Project.

This statement will include all the targets and tasks that we need. Most of our customizations should be after that import, if you are not sure put if after! So if you have files to exclude there is an item name, ExcludeFromPackageFiles, that can be used to do so. For example let’s say that you have file named Sample.Debug.js which included in your web application but you want that file to be excluded from the created packages. You can place the snippet below after that import statement.

<ItemGroup>
  <ExcludeFromPackageFiles Include="Sample.Debug.xml">
    <FromTarget>Project</FromTarget>
  </ExcludeFromPackageFiles>
</ItemGroup>

By declaring populating this item the files will automatically be excluded. Note the usage of the FromTarget metadata here. I will not get into that here, but you should know to always specify that.

Including extra files into the package

Including extra files into the package is a bit harder but still no bigee if you are comfortable with MSBuild, and if you are not then read this.  In order to do this we need to hook into the part of the process that collects the files for packaging. The target we need to extend is called CopyAllFilesToSingleFolder. This target has a dependency property, PipelinePreDeployCopyAllFilesToOneFolderDependsOn, that we can tap into and inject our own target. So we will create a target named CustomCollectFiles and inject that into the process. We achieve this with the following (remember after the import statement).

<PropertyGroup>
  <CopyAllFilesToSingleFolderForPackageDependsOn>
    CustomCollectFiles;
    $(CopyAllFilesToSingleFolderForPackageDependsOn);
  </CopyAllFilesToSingleFolderForPackageDependsOn>
</PropertyGroup>

This will add our target to the process, now we need to define the target itself. Let’s assume that you have a folder named Extra Files that sits 1 level above your web project. You want to include all of those files. Here is the CustomCollectFiles target and we discuss after that.

<Target Name="CustomCollectFiles">
  <ItemGroup>
    <_CustomFiles Include="..\Extra Files\**\*" />

    <FilesForPackagingFromProject  Include="%(_CustomFiles.Identity)">
      <DestinationRelativePath>Extra Files\%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
    </FilesForPackagingFromProject>
  </ItemGroup>
</Target>

Here what I did was create the item _CustomFiles and in the Include attribute told it to pick up all the files in that folder and any folder underneath it. Then I use this item to populate the FilesForPackagingFromProject item. This is the item that MSDeploy actually uses to add extra files. Also notice that I declared the metadata DestinationRelativePath value. This will determine the relative path that it will be placed in the package. I used the statement Extra Files%(RecursiveDir)%(Filename)%(Extension) here. What that is saying is to place it in the same relative location in the package as it is under the Extra Files folder.

Admittedly this could be easier, but its not too bad, and its pretty flexible.

Sayed Ibrahim Hashimi

Disclaimer: Take what you read here with a grain of salt, I’m not an expert at providers … yet :)

I’ve known for quite a while that the Web Deployment Tool supports custom providers but I’ve never really looked at what it took to get actually write one. Tonight I wanted to write a simple provider to just sync a file from one place to another, just to see what is involved in creating that provider. In this post I describe how I created the provider. First you have to have the Web Deployment Tool installed, I’ve got the RTM version installed, but recently they delivered version 1.1 either should work. First things first, you need to create a class library project in Visual Studio. For this example I used Visual Studio 2010 RC for the reason that it’s the only version of Visual Studio that I have installed on this machine. If you are using Visual Studio 2010 make sure that you specify to build for .NET 3.5 because MSDeploy won’t pickup any providers written in .NET 4.0. To specify that your project should build for .NET 3.5 go to Project->Properties then on the Application tab pick the Target Framework to be .NET 3.5. See the image below for clarification.

You will need to reference the two assemblies Microsoft.Web.Deployment.dll and Microsoft.Web.Delegation.dll. You can find both in the %Program Files%\IIS\Microsoft Web Deploy folder.

After this you need to create the class which is the provider. I called my CustomFileProvider because it will only sync a single file. The class should extend the DeploymentObjectProvider class. There are a couple abstract items that you must implement those are.

CreateKeyAttributeData

From what I can see this method is used to indicate how the “key attribute” is used. For instance when you use a contentPath provider you would use a statement like msdeploy –verb:sync –source:contentPath=C:\one\pathToSync –dest:… So we can see that the value C:\one\pathToSync is passed to the provider without a name. This is the key attribute value. This method for my provider looks like the following.

public override DeploymentObjectAttributeData CreateKeyAttributeData()
{
    DeploymentObjectAttributeData attributeData = new DeploymentObjectAttributeData(
        CustomFileProvider.KeyAttributeName,
        this.FilePath,
        DeploymentObjectAttributeKind.CaseInsensitiveCompare);

    return attributeData;
}

In this case CustomFileProvider.KeyAttributeName is a const whose value is path and its value is provided from the FilePath property. The other item that you have to override is the Name property.

Name

This property returns the name of the provider. In all the samples that I have seen (which is not very much) this name always agrees with the name of the custom provider factory, more on that in a bit. So in their example I had mine return the value customFile which my factory also returns.

Outside of these two items there are some other methods that you need to know about those are covered below.

GetAttributes

The GetAttributes method is kinda interesting. This method will be called on both the source and destination and you need to understand which context its being called in and act accordingly. You can determine if you are executing on the source or dest by using the BaseContext.IsDestinationObject property. So for this provider if you are in the source you want to ensure that the file specified exists, if not then raise a DeploymentFatalExcepton, this will stop the sync. If you are on the destination you could perform some checks to see if the file is up-to-date or not. For a simple provider you can force a sync to occur. You would do this by raising a DeploymentException. When you raise this exception at this time it causes the Add method to be called, which is exactly what we want. Here is my version of the GetAttributes method.

public override void GetAttributes(DeploymentAddAttributeContext addContext)
{
    if (this.BaseContext.IsDestinationObject)
    {
        // if we are on the destination and the file doesn't exist then we need to throw an exception
        // to ensure that the file gets synced. This happens because the Add command will be called for us.

        // Since I'm throwing an exception here Add will always be called, we could check to see if this file
        // was up-to-date and if so then skip this exception.
        throw new DeploymentException();
    }
    else
    {
        // We are acting on the source object here, make sure that the file exists on disk
        if (!File.Exists(this.FilePath))
        {
            string message = string.Format("File <{0}> does not exist",this.FilePath);
            throw new DeploymentFatalException(message);
        }
    }

    base.GetAttributes(addContext);
}

For the most part the only thing left for this simple provider to implement is to override the Add method. First I will show the method then discuss its content. Here is the method.

public override void Add(DeploymentObject source, bool whatIf)
{
    // This is called on the Destination so this.FilePath is the dest path not source path
    if (!whatIf && File.Exists(source.ProviderContext.Path))
    {
        // We can let MSDeploy do the actual sync for us using existig provider
        DeploymentProviderOptions sourceProviderOptions = new DeploymentProviderOptions(DeploymentWellKnownProvider.FilePath);
        sourceProviderOptions.Path = source.ProviderContext.Path;

        using (DeploymentObject sourceObject = DeploymentManager.CreateObject(sourceProviderOptions, new DeploymentBaseOptions()))
        {
            DeploymentProviderOptions destProviderOptions = new DeploymentProviderOptions(DeploymentWellKnownProvider.FilePath);
            destProviderOptions.Path = this.FilePath;

            // Make the call to perform an actual sync
            sourceObject.SyncTo(destProviderOptions, new DeploymentBaseOptions(), new DeploymentSyncOptions());
        }
    }
}

First I check to make sure that we are not doing a whatif run (i.e. a run where we don’t want to physically perform the action) and that the source file exists. Take note of the fact that I’m explicitly using source.ProviderContext.Path to get the source path. This provider has a property, FilePath, which contains the path but it could be either source path or dest path depending on which end you are executing in. the source.ProviderContent.Path will always point to the source value. After that you can see that I’m actually leveraging an existing provider the FilePath provider to do the actual sync for me. So all the dirty work is his job! If you are writing a provider make sure to re-use any existing providers that you can, because the code for this part looks like it can get nasty. I’ll leave that for another post.

After I prepare the source options I create an instance of the DeploymentObject class, prepare the FilePath provider and call SyncTo on the object., this is where the physical sync occurs. That is basically it for the provider itself now we need to create a provider factory class which is the guy who knows how to create our providers for us.

Fortunately creating custom provider factories is even easier then creating custom providers themselves. I called mine CustomFileProviderFactory and the entire class is shown below.

[DeploymentProviderFactory]
public class CustomFileProviderFactory : DeploymentProviderFactory
{
    protected override DeploymentObjectProvider Create(DeploymentProviderContext providerContext, DeploymentBaseContext baseContext)
    {
        return new CustomFileProvider(providerContext, baseContext);
    }

    public override string Description
    {
        get { return @"Custom provider to copy a file"; }
    }

    public override string ExamplePath
    {
        get { return @"c:\somefile.txt"; }
    }

    public override string FriendlyName
    {
        get { return "customFile"; }
    }
    public override string Name
    {
        get { return "customFile"; }
    }
}

A few things to make note of; your class should extend the DeploymentProviderFactory class and it should have the DeploymentProviderFactory attribute attached to it. Besides that there are two properties FriendlyName and Name, once again in all the samples I have seen they are always the same and always equal to the Name property on the provider itself. I followed suit and copied them. I’m still trying to figure out more about what each of these actually do, but for now I’m OK with leaving them to be the same. So that is basically it.

In order to have MSDeploy use the provider you have to create a folder named Extensibility under the %Program Files%\IIS\Microsoft Web Deploy folder if it doesn’t exist, and then copy the assembly into that folder. And then you are good to go. Here is the snippet showing my custom provider in action!

C:\temp\MSDeploy>msdeploy -verb:sync -source:customFile=C:\temp\MSDeploy\Source\source.txt -dest:customFile=C:\temp
\MSDeploy\Dest\one.txt -verbose
Verbose: Performing synchronization pass #1.
Info: Adding MSDeploy.customFile (MSDeploy.customFile).
Info: Adding customFile (C:\temp\MSDeploy\Dest\one.txt).
Verbose: The dependency check 'DependencyCheckInUse' found no issues.
Verbose: The synchronization completed in 1 pass(es).
Total changes: 2 (2 added, 0 deleted, 0 updated, 0 parameters changed, 0 bytes copied)

This was a pretty basic provider, but you have to start somewhere. I will post more about custom providers as I find out more.

You can download the entire source at http://sedotech.com/Resources#CustomProviders under the Custom Providers heading of the MSDeploy section.

Sayed Ibrahim Hashimi

I just received a message from a reader asking about how he can extend the package process in Visual Studio 2010 RC to include files that his web project doesn't contain or reference. If you are not familiar with this Visual Studio 2010 has support for creating Web Packages now. These packages can be used with the Web Deployment Tool to simply deployments. The Web Deployment Tool is also known as MSDeploy.

He was actually asking about including external dependencies, but in this post I will show how to include some text files which are already written to disk. To extend this to use those dependencies should be pretty easy. Here is what I did:

1. Created a new ASP.NET MVC 2 Project (because he stated this is what he has)
2. Added a folder named Extra Files one folder above where the .csproj file is located and put a few files there
3. In Visual Studio right clicked on the project selected “Unload Project”
4. In Visual Studio right clicked on the project selected “Edit project”

Then at the bottom of the project file (right above the </Project> statement). I inserted the following XML fragments.

<PropertyGroup>
  <CopyAllFilesToSingleFolderForPackageDependsOn>
    CustomCollectFiles;
    $(CopyAllFilesToSingleFolderForPackageDependsOn);
  </CopyAllFilesToSingleFolderForPackageDependsOn>
</PropertyGroup>
<Target Name="CustomCollectFiles">
  <ItemGroup>
    <_CustomFiles Include="..\Extra Files\**\*">
      <DestinationRelativePath>%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
    </_CustomFiles>

    <FilesForPackagingFromProject  Include="%(_CustomFiles.Identity)">
      <DestinationRelativePath>Extra Files\%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
    </FilesForPackagingFromProject>
  </ItemGroup>
</Target>

Here I do a few things. First I extend the CopyAllFilesToSingleFolderForPackage target by extending its DependsOn property to include my target CustomCollectFiles. This will inject my target at the right time into the Web Publishing Pipeline. Inside that target I need to add my files into the FilesForPackagingFromProject item group, but I must do so in a particular manner. Specifically I have to define the relative path to where it should be written. This captured inside the DestinationRelativePath metadata item. This is required because sometimes you may have a file which is named, or in a different folder, than it was originally. After you do that you will see that the web package that is created when you create a web package from Visual Studio (or from the command line using msbuild.exe for that matter) contains your custom files.

I just posted a blog about my upcoming talk discussing Web Deployments and ASP.NET MVC, once again check it out :)

Sayed Ibrahim Hashimi

I will be speaking at the Orlando Code Camp on Saturday March 27. I will be giving two session; one on Simplifying deployments with MSDeploy and Visual Studio 2010 and the other on ASP.NET MVC View Helpers. By the way, the other name for MSDeploy is the Web Deployment Tool.

If you have ever had issues with deploying web applications (which includes everyone who has ever deployed a web app :) ) then you need to attend my session. I will discuss the three major scenarios of deploying web applications:

• Deploying to a local IIS server
• Deploying to an IIS server on the intranet
• Deploying to a 3rd party host

I will be demonstrating how to perform 2 of the 3; deploying to local IIS server and to a 3rd party host. Since I won’t have any other machines besides my notebook I will not be demoing how to deploy to an IIS server on the intranet, but it is very similar to the other 2 scenarios. There has been a lot of work in the area of web deployment (deployment in general actually) recently which could really help spare you of a lot of headache. I presented this at the South Florida Code Camp a couple weeks ago and a person actually stated in the session “There are a lot of people who wish they were in here right now”! If you are in the area then you should attend my session, you won’t regret it.

Here is the abstract:

Visual Studio 2010 will be shipped including integration with Microsoft’s Web Deployment Tool, MSDeploy. For quite a while web deployments have been very difficult to manage and automate. With MSDeploy you can manage the complexities of web deployments. One of the great aspects of the Web Deployment Tool is that it is integrated into Visual Studio with MSBuild tasks and targets. Since Team Foundation Build can leverage MSBuild we can take advantage of those tasks and targets to automate web deployments using Team Build.

My other talk will be on creating leaner views with ASP.NET MVC View Helpers. If you are using ASP.NET MVC then this is one of the sessions you’ll be interested in. I will be getting in depth about ASP.NET View Helpers, and just talking ASP.NET MVC in general. I gave this talk at the Jacksonville Developers User Group last week and it was great. I’m very excited about these two talks, I’m sure they will be great. Here is the abstract.

If you have been using ASP.NETMVC then you certainly have been using some of the built in view helper methods that are available, you know those expressions like Html.TextBox("textBoxName") and Html.ValidationMessage("Required"). View helpers are nothing more than extension methods which create HTML that is injected into your views based on the method and its parameters. Creating your own view helpers is very simple and can be extremely beneficial. By writing your own custom view helpers you will benefit in at least the following ways

• Simplifies Your Views
• Eases Re-hydrating HTML Elements with ModelState Values
• Standardizes the Creation of Common HTML Components
• Helps you Implement the DRY (Don’t Repeat Yourself) Principal

I have published a 22 page paper discussing custom ASP.NET MVC view helpers along with a sample app at http://mvcviewhelpers.codeplex.com/ if you are interested.

 

If you are in the area this weekend its going to be a great event. I think there were >400 people there last year, so it should be a good turn out this year as well. I hope to see you there.

Sayed Ibrahim Hashimi