Your official information source from the .NET Web Development and Tools group at Microsoft.
In Visual Studio 2013 we have added a couple of small features for web publishing that I’d like to share with you. Those updates are; how to take your app offline during publishing and how you can update the default file compare option.
In Visual Studio when you publish your web application we do not force the remote app to be stopped/restarted. Based on your publishing artifacts your site may end up being restarted (for example you change web.config) but Visual Studio never had a way to take your application offline during a publish operation.
There are a lot of reasons why you may want to take your app offline during publishing. For example you app has files locked which need to be updated, or you need to clear an in-memory cache for changes to take effect. We heard a good amount of feedback from ASP.NET users regarding the lack of this support on our uservoice site. From that suggestion we worked with the Web Deploy team to introduce a new AppOffline rule which enables this.
We also added support for this in Visual Studio 2013 as well. We have not yet created any specific UI for this feature but it’s very easy to enable. Since Visual Studio 2012 web publish profiles are stored as MSBuild files under Properties\PublishProfiles (My Project\PublishProfiles for VB). These files end with a .pubxml extension (not to be confused with .pubxml.user) and have the same name as the Publish Profile in Visual Studio.
Each of these publish profiles contain the settings for that publish profile. You can customize these files to modify the publish process. To enable this find the .pubxml file corresponding to the publish profile you’d like to update. Then add the following element in the PropertyGroup element.
So the resulting publish profile will look something like the following.
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<DeployIisAppPath>Default Web Site</DeployIisAppPath>
After that you can save and close the file. When you publish (either in Visual Studio or the command line) using that profile your app will be taken offline during publishing.
This feature was implemented as a direct result of your feedback so please keep letting us know how we can improve.
Web Deploy has two methods of determining which files will be synced when a publish operation is performed.
By default Visual Studio uses the time stamps method. The reason for this is that there is a noticeable performance impact when using the CRC checksum.
In team scenarios, or on build servers, it may make sense for you to use the CRC method instead. Enabling this is very similar to the app offline support. Find the .pubxml file which is associated with your web project and add the following element under the PropertyGroup element.
After that when you publish using that profile (from Visual Studio or the command line) the CRC checksum method will be used instead of time stamps.
If you would like to enable this for multiple project, or multiple profiles it may get a bit cumbersome to modify every .pubxml file. These properties are standard MSBuild properties so there are several different ways you can apply these settings. Below I’ve outlined a few different options, but if these don’t meet your needs there may be additional options.
When you invoke msbuild.exe you can pass this property in as you would any other MSBuild property. Use the following syntax,
In this post I suggested that you place the properties directly inside of the .pubxml file. Instead of this you can place this property directly inside your .csproj/.vbproj file. You should place the following PropertyGroup in your project file.
If you have a build server (or your own dev box) that you’d like to apply these settings for every build you can create an environment variable with the name/value desired.
You can also use the CustomBeforeMicrosoftCommonTargets MSBuild property. I’ve blogged about how you can use this technique in the past.
Sayed Ibrahim Hashimi | http://msbuildbook.com | @SayedIHashimi
Is there a way to customise the App_Offline.htm?
Awesome Sayed, thanks to you and the team.
I did get the error "Unrecognized rule 'AppOffline'" when trying to publish to one of my older servers with Web Deploy 2.0. Upgrading the server to Web Deploy 3.5 fixed this.
Sayed, what does "The reason for this is that there is a noticeable performance impact when using the CRC checksum." mean? That publish takes longer? That it just uses more CPU during publish/preview?
Related, has there been consideration given to TimestampThenCRC? Such that first it uses cheap timestamp comparisons, then it will do CRC comparisons for files that are newer, but only do the CRC calculations for the files that might be relevant according to newer timestamp.
@Chris Foster, check stackoverflow.com/.../custom-app-offline-htm-file-during-publish for customizing App_Offline.htm
@Chris Foster, the custom app offline support was just added in Web Deploy 3.5. For info on how to enable that when calling msdeploy.exe take a look at blogs.iis.net/.../webdeploy-3-5-rtw.aspx.
We have not had the time yet to add the VS support for this. We have that on our backlog for consideration in a future release. I blogged a while back about how you can take your app offline (pre Web Deploy 3.0) which has support for a custom app offline. It's a bit involved but if you really need it now take a look at my previous blog post at sedodream.com/.../HowToTakeYourWebAppOfflineDuringPublishing.aspx.
@Nick, yes Web Deploy 3.0 is required for the App offline support.
@Chris Marisic, when using the CRC check your publish will take longer. I am not sure if the Web Deploy team has considered your time stamp/CRC check. I will pass along the suggestion.
Awesome article and very timely, thank you.
I am having some difficulty using the EnableMSDeployAppOffline setting. I have specified EnableMSDeployAppOffline in my .pubxml file, as well as adding /p:EnableMSDeployAppOffline=true to my msbuild parameter list but I still do not see the app_offline.htm file ever getting placed into the application directory.
Environment: TFS2012, MSDeploy v3, VS2012 Update 3
Are there any log files I can examine? The article indicates VS2013 but it was available in MSDeploy v3 correct?
Appreciate any help you can offer.
@Steve, even though the support is in Web Deploy 3.0, we still need to add the support to the Visual Studio publish process (which invokes Web Deploy).
For Visual Studio 2012 you'll need to pickup the latest Azure SDK at www.windowsazure.com/.../downloads. The support should also be included in VS2012 Update 4 when it is released. Passing that property to previous versions won't change the publish behavior. It will just be ignored.
Thanks Sayed, I'll keep an eye out for the final VS2012 Update 4. :)
It's not mentioned in the article, but it seems that EnableMSDeployAppOffline property is only considered when there is a direct publish from VS. If we write to msdeploy package (zip) it's all completely ignored and there doesn't seem to be trace of AppOffline rule in the package.
Am I correct about this? Are there plans to include it in the package scenario? Do you know of ways to workaround it already (I'm on VS 2012 - update 4) and include the AppOffline rule somehow in deploy.cmd script?
@Artur you are correct. The offline switch is controlling behavior of the sync that is being performed at that time. Because of that if you are creating a package the MSBuild property is ignored. If you are creating a package and then publishing that you when you invoke msdeploy.exe you will need to pass the offline switch. You can find more info there at www.iis.net/.../taking-an-application-offline-before-publishing.
Regarding the .cmd file, we are not investing in updating that support at this time. We will be looking at other alternatives in future versions but we do not have any specific plans as of yet. After generating the .cmd file you should be able to manually edit it to pass this additional switch.
Sayed, thanks for the clarifications. It sounds like EnableMSDeployAppOffline is only valid when manually publishing through Visual Studio.
We are utilizing TFS to generate/deploy directly to the servers, and the build definitions contain MSBuild statements. The /p:PublishProfile is being passed into the MSBuild statement so I was thinking that MSBuild would be able to parse that argument out of the .pubxml file similar to Visual Studio, but that does not appear to be happening.
Is there another way to get MSBuild to utilize the EnableMSDeployAppOffline functionality? I see from the other article how to pass it to MSDeploy, but I'm not sure how MSBuild passes through arguments to MSDeploy (specifically the EnableMSDeployAppOffline argument).