Web Deploy: IIS6 to IIS7 Migrations + Link Extensions

Recently I was having a conversation with one of Web Deploy (MSDeploy) users and an interesting scenario came up.  He essentially wanted to move his site from IIS 6.0 to IIS 7 and wanted to consider Web Deploy to do this.  In addition he actually was fine with just xCopy-ing the site’s content from IIS6 server to IIS7 server as it was almost 6GB+ in size and trying to create a zip package for it was not most the optimal way of using resources, nevertheless creating a zip package using Web Deploy for just the IIS configuration is what was certainly desirable due to ease of portability & use.

I thought this would be a good opportunity to write a quick note to share with you that migration from IIS 6 to IIS 7 was one of the original scenarios of Web Deploy and so if you are considering the migration from IIS 5.1 to IIS 7 & above then for sure you should consider Web Deploy to help you with it.

Now as you know IIS 6 configuration is based on Metabase and IIS 7 configuration is based on new XML based configuration system so even trying to migrate just the configuration part might be challenging to do manually.  Web Deploy does a fantastic job with this configuration migration and more.

In IIS 7 there is a great UI for you to use to export a Web Site, Web Site or Web Application package from IIS Manager but in IIS 6 there was no way to introduce any UI without servicing IIS 6 which when you consider the impact worldwide is not most ideal thing to do. But anyways the long and short of it is that you will have to use msdeploy.exe command line in IIS 5.1/IIS6 to create a package. When you get the package on to IIS 7+ box then you can of course use the “Import Application” UI on the IIS7 Action pane (right column) even if the package was generated by IIS 5.1 or 6…

One other interesting area to know about is Web Deploy Link Extensions coz they will come very handy when you go about migrating your IIS 6 sites & servers to IIS 7.  Earlier I have talked about how Web Deploy works and what Web Deploy providers are. In addition to Web Deploy providers it is useful to understand the concept of Link Extensions. Well as the name suggests a “Link Extension” is some artifact which Web Deploy can decipher from a parent provider based on some kind of meta data or link which might be present in the parent. Some of the notable link extensions are:

· AppPoolExtension - Application Pool configuration which resides outside the contained site configuration, but again the site configuration points to which Application Pool it uses.

· CertifacteExtension - Certificates which are external artifacts associated to the site but something which site’s IIS configuration links to.

· ContentExtension - Site’s content which resides on the disk but again technically only a pointer to it exists in the site’s IIS configuration.

· FrameworkConfigExtension - The root web.config associated with each .NET Framework (stored C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config) which some IT Admins customize and IIS configuration knows which ASP.NET version you are using so technically that can be deciphered too.

The meta point is that these are all the above link extensions can be turned on or off from Web Deploy command line when you are trying to migrate your IIS 5.1/IIS6 sites and servers to IIS 7 and above… There are more link extensions and it is likely that more might be added in the future, you can keep a link to this TechNet article as that is where we might update the information if it changes.

Finally for the scenario that we started talking about in the beginning of this blog the command line to create a package of all of IIS 6 configuration for a Site (with Site id 1) without including the content of the site would be:

MsDeploy.exe -verb:sync -source:metakey=lm/w3svc/1 -disableLink:Content -dest:package=c:\mySite1Package.zip

If you would like to sync up the entire server then the command line would be:

Msdeploy.exe -verb:sync -source:webserver60 -dest:package=c:\mySite1Package.zip -disableLink:Content

Now the generated MsDeploy package can be easily transported to IIS 7 or IIS 7.5 and configuration can be easily replicated without the content being touched in anyway.

Hope this helps,

Vishal

Web Deploy Parameterization in Action

A few weeks back I explained the key differences between Web.Config Transformation and Web Deploy (aka MSDeploy) Parameterization…  Before you read this post I recommend that you read Transformation vs. Parameterization post, it is tiny and will clear few fundamentals…

Automatic Parameterization

Before I dive in more let me clarify that if you are using VS 2010 then in common scenarios you may not even need to do custom parameterization, coz VS 2010 already parameterizes things like IIS Application Name, Application physical installation directory and connectionStrings… So when you actually create a web deploy .zip package you can easily build it once and deploy it several number of times by changing the parameters values…

Custom Parameterization

The typical scenarios where you will need to do custom parameterization is for scenarios like:

• You have an appSetting  which needs to be changed by server admin at install time…
• You are using a WCF Service and you want to change the end point at install time…
• You have created re-usable web package for community apps and have bunch of questions to ask the users before they install the app (similar to all of the apps that you find in Application Gallery eg ScrewturnWiki, DNN, etc…)

Scenario

In today’s post I am going to use Parameterization with VS 2010 for changing an appSetting & WCF Service end point… Before we do that let us look at the web.config settings which we want to change at install time…

App Settings  - The Log Folder location here (“value” attribute) is something which I want my admin to be able to change at production install time to a shared location so that if my app is virtualized and put on a web farm then I have a common place to go and look at the log…

WCF Endpoint – Below is my WCF EndPoint URL (“address” attribute) which I would like my admin to change to the servers/sites on which the WCF Services will get deployed…

Install Time Experience

Installation of Web Packages can be done in couple of different ways:

• Installation using IIS Manager
• Installation using Command Line

We want to make sure that no matter which direction our IT Admin takes he/she gets an opportunity to provide values for the above two parameters…

Parameters.xml File format

As I explained in the earlier post Parameters.xml file can be passed to Web Deploy when your .zip Web package is being created and that allows Web Deploy to determine what items in your web should it mark as “changeable” at install time…  VS 2010 makes your life easier by allowing you to simply drop the Parameters file in the root of your web project and if a file with the name Parameters.xml is found in the root of your project it passes it to Web Deploy which then parameterizes your web…

The Parameters.xml file follows a specific format, the key attributes to note for each parameter that you declare within parameters.xml file are:

name – Required unique name to identify the parameter with e.g. “Service 1 endpoint address”

description – This text shows up in the UI of IIS Manager to help the user fill in the value so anything clarifying the parameter is cool…

defaultValue - Optionally you can specify a default value for a parameter so that while installing the package a user may know what kind of values are permissible…

scope – Regular Expression to determine what entities (files e.g. web.config, DBs, Web Deploy providers etc) does the parameter apply to

kind – There are several kinds of parameters but the key ones to remember are:

• XmlFile – Use this for web.config, any settings XML files etc where you can make replacements using XPath
• TextFile – Use this for non-XML file where you can make replacements by looking for fixed text or token within a file. e.g. you can put @@replaceme@@ in the a settings.ini file and during installation that text can be replaced

match -  This depends upon the parameter kind… For e.g. for XmlFile parameter the match expression would be a XPath… For TextFile the match expression could be @@replaceme@@ which you might pre-place in the file…

Declaring Parameters using Parameters.xml

Below is the content of Parameters.xml file that I dropped to the root of my MVC Application

<?xml version="1.0" encoding="utf-8" ?>
<parameters >

  <parameter name="Log Folder Location" description="Please provide a shared location where the app can write log files to" defaultValue="\\Logs\MvcApp\Logs\" tags="">
    <parameterEntry kind="XmlFile" scope="\\web.config$" match="/configuration/appSettings/add[@key='LogFolder']/@value" />
  </parameter>

  <parameter name="WCF Service1 Endpoint Address" description="Please provide the Endpoint address for Service1 that this MVC App needs to call" defaultValue="http://localhost:61938/Service1.svc" tags="">
    <parameterEntry kind="XmlFile" scope="\\web.config$" match="//system.serviceModel/client/endpoint/@address" />
  </parameter>
  
 </parameters>

 

If you notice each of the Parameter above you can see that I am using XmlFile parameter kind with Xpath as the match syntax…  After adding this Parameters.xml file into my project my solution explorer looks as below:

Now I can simply right click on my MvcApplication and hit “Build Deployment Package”…  The resultant .zip file should be created at obj\Debug\Package\MvcApplication1.zip…

Validating that Parameters really worked

• Now to validate whether the parameters really worked you can very quickly open IIS Manager (Start –> Run –> InetMgr) and select your Default Web Site



• You can now click the “Import Application” command on the right side bar and pass the newly created .zip package to it.

• On Hitting  next on the Import Application wizard you will be able to see the “Parameterization” screen which user will be able to pass values to the parameters.  Notice even our defaultValues provided in the Parameters.xml show up:

• I am now changing the value of these variables as shown below:

• When I now go ahead and finish the wizard by clicking “Next” and go ahead and inspect the Web.Config file in the deployed location, I can see that the changed parameter values were applied to the web.config file seamlessly…

• Also do note that in the process above “Parameters.xml” will also get deployed with your web application, in reality you do not need that file… To avoid that file from getting deployed you can go to its properties (select the file and hit F4) and set “Build Action” = None as shown below:

 

There is a ton more power of parameters.xml file that you can explore via Technet Article on Web Deploy Parameters or IIS.NET Articles about Parameters.xml but for scenario like ours the above information should hopefully suffice…

Thanks for reading :-)

-Vishal

Parameterization vs. Web.Config Transformation

I was recently asked about being able to change values of different variables like ConnectionStrings, Installation physical directory, app Settings etc during install time rather than build time, so I thought it might be worth while to de-mystify the concepts around Web.Config Transforms and Parameterization…

Web.Config Transformation

Geeks say Web.Config Transformation is a great feature of Web Deploy (aka MsDeploy), well the first part about being a great feature is true :-) but it is important to note that Web.Config Transformation is not a Web Deploy feature but it instead is a VS 2010 only feature.  Web.Config Transformation is connected with Build configuration of MSBuild/VS/Team Build etc…  Its XML transformation engine is wrapped in MSBuild and has a UI around in VS 2010 which yeilds following benefits:

• You get to tie Web.Config Transform with various build configurations and access it independently from Team Build.
• You can use it with any deployment mechanism like File System, FTP, FTPS, or Web Deploy
• You can use it in projects other than Web Projects where you want to transform XML files

If you are building a deployment web package (.zip) and know which environment you are building for then web.config transformation is great.  This is the category where many of us fall coz we build for a release environment and need the right config file to go in that deployment package.  For that matter many people are just fine creating web packages for the correct environment they are deploying to…

Now for others who want to be able to build just once and deploy to both test as well as staging/release environment then an embedded web.config file for one environment may not work.  For this scenario there is parameterization.

Parameterization

Parameterization, unlike Web.Config Transform is Web Deploy (aka MsDeploy) only feature, which means that it will not work in non-Web projects or when you are using other protocols like FTP/FTPS etc.  Parameterization from Web Deploy standpoint is a 2 step process

1. Declare Parameters: You create a Parameters.xml file and pass it to Web Deploy while creating the package…  In this file you need to indicate what file you want to parameterize  (e.g. web.config), what variable inside the file needs to be parameterized (e.g. connectionString) and what would be the default value of the variable (e.g. release connectionString)… Using Parameters.xml file, Web Deploy will create an internal meta data file within your .zip package which guides Web Deploy to know what “Questions” to ask the person who is installing the .zip package… 
2. Set Parameters: When user is about to install the web package the value of the Parameters can be provided to Web Deploy via several means.  In case you are using IIS Manager to install the package then the IIS Manager UI will automatically show the Parameters with filled in default values.  If you are using Web Deploy command line to install the package then you can provide a setParameters.xml file to the commandline (in case of VS 2010 generated deploy.cmd file just having setParameters.xml file in same folder as the .cmd and .zip file is sufficient).  The setParameters.xml file is a very simple name-value pair file in which you can provide the value of the parameter adjacent to its name.

In one of the future posts I will write more about how to use Parameterization for some canonical deployment scenarios, but hopefully this will lay the foundation of how to differentiate between build time transforms from install time parameters.

Conclusion

If you can know your environment settings during build time use Web.Config transformation. 

If you would want to create deployment package only once and then enter the settings during install time then use Parameters.xml

VS 2010 actually uses a combination of Parameters and Web.Config transforms to provide you with a seamless experience (i.e. connectionStrings, IIS Application Name etc are already parameterized by default) so for most common scenarios you would hopefully not have to delve into understanding all the details but if you have any questions then of course feel free to ask here or via email…

Thanks

Vishal

Web Deployment Projects Released to Beta (WDP for VS 2010)

 

Our team recently released WDP for VS 2010… The key features to note for WDP for VS 2010 are:

1. All the core features of WDP 2008
2. Migration from WDP 2008 to WDP 201o
3. Multi-Targeting support in WDP 2010
4. Support Web Deploy Packages in the WDP project..

You can read more about the above features on our team blog at Visual Web Developer Team Blog

Download WDP 2010 Beta by clicking here!!

The guidance around using WDP 2010 is

• Use it if you want to migrate to VS 2010 and are currently using WDP for VS 2008
• Use it for TeamBuild/MSBuild based deployment of Web Site Projects in VS 2010…
• Use them for Web Application Projects (WAPs) if you feel it is extremely important for you to pre-compile/merge your projects… If not then you can use Web Deployment features built into VS 2010…

Hope this helps!!

-Vishal

Web Deployment Demos, Slides & Videos for VS 2010 launch

I have been dormant for ever, have been keeping busy on a very exciting project… Anyways April 12th 2010 was a big day with VS 2010 formally launching…  Few days back I asked Twitter whether people needed a ready made talk to talk about VS 2010 Web Deployment as part of the community launch events of VS 2010 and got a lot of asks for the content so here it is… 

Titles & Abstract I would recommend you do not use are below… :-)  The reason I say that is coz VS 2010 & Web Deploy are way more exciting than the way I present here; so get creative and make a fun abstract & title…  The only reason I have them descriptive is so that you know what are the key items to put in there…

Title: Web Deployment with VS 2010 & Web Deploy

Abstract: Web deployment is not as easy as it should be; whether you are deploying to a shared hosting environment or to your company’s web servers there are a lot of manual steps involved.  Check out how new VS 2010 and Web Deploy can help you deploy your web along with its dependencies like databases and IIS settings to any environment with just One Click Publish.  Also check out how  you can transport your entire web in a single .zip file and finally hear all about the web.staging.config, web.release.config etc  and the simple transformation syntax in them to create web.config per deployment configuration… Finally also learn how you can automate your Web Deployments using Team build so you no more have to worry about daily builds and setting up of environments…

Video:  Check out the video at http://microsoftpdc.com/Sessions/FT56, this should prep you up on what are the talking points…

Demos & Slides: You can download it from my SkyDrive

If you have any questions/thoughts on the content you can feel free to write comments here or reach me at @VishalRJoshi 

Hope this helps!!

-Vishal

VS 2010 Beta 2 Read Me Items for Web Deployment

There are some known issues/bugs related to VS 2010 Web Deployment features in VS 2010 Beta 2 Read Me… I can imagine reading the entire Beta 2 read me file can be daunting so I thought I can just copy paste the ones related to Web Deployment here…

DB Deployment will fail if the Database Name is longer than 127 characters

Description: If you are using latest VS 2010 Web Deployment Features and trying to deploy your database using the Deploy SQL property page then at times you might get error from VSMsDeploy task. 

There might be several reasons for the failure including connection and authentication issue but a current bug in the product does not allow you to script schema/data from a database (typically SQL Express MDF file) if the file path is longer than 127 characters.  In the OS like XP or Win2K3 the default path for the VS project & its default ASP.NET Login/Profile DB could be something like C:\Documents and Setting\... \Visual Studio 2010\Projects\MyProject\App_Data\ASPnet_DB.mdf... This path can potentially exceed 127 characters and result into Deployment failure...

Workaround: The easy work around is to have the project copied to a location where the path will not exceed 127 characters for e.g. C:\MyProject\App_Data...  This issue will eventually be resolved in the product...

Some VS 2010 Web Deployment Features will not work if VS 2010 is installed on Vista RTM instead of Vista SP1

Description:  If you are using the new Web Deployment feature set in VS 2010 and are using the below features which integrate with MSDeploy:

• Web Packaging
• One-Click Publishing
• DB Deployment

then you will have to use Vista SP1 instead of Vista RTM as your OS.

Workaround: MsDeploy requires features which are built inside Vista SP1 and hence trying to run Web Deployment features on Vista RTM fails.  This is a required dependency so you will have to use Vista SP1 as your OS for VS 2010.  Do note that you can still use any other operating system like XP, Win2K3, Win2k8 R2, Win7 etc to install VS 2010 and use the Web Deployment features, it is just advised that any of the OS versions that you use are updated with the latest Service Packs so that all the required dependencies are in place.

MsDeploy.exe.config file will be required to run Web Deployment on machines with .NET 4.0 only

Description: If you installed VS 2010 on a clean machine which does not have .NET 2.0 (e.g Win2K3)  and are trying to use the VS 2010 Web Deployment Features then when you run the deploy.cmd file to install your web package you might receive error stating "Msdeploy.exe -.NET Framework Initialization Error Unable to find a version of the runtime to run this application."  This is due to the fact that VS 2010 comes with only .NET 4/CLR4 and and CLR 4 does not allow CLR 2.0 executables to run  without having an explict exe.config file…  If you are using other .NET 2.0/3.0 or 3.5 exes on a box with just .NET 4 then you might face similar issues with those EXEs too…

Workaround: You can easily work around this by going to "%Program Files%\IIS\Microsoft Web Deploy" (& additionally also on "%Program Files (x86)%\IIS\Microsoft Web Deploy" folders and create following msdeploy.exe.config file in there

<configuration>
    <startup useLegacyV2RuntimeActivationPolicy="true">
            <supportedRuntime version="v2.0.50727" />
            <supportedRuntime version="v4.0" />
    </startup>
</configuration>

This issue will be fixed in the future releases of the product.

-Vishal

Exclude App_Data Folder from Deployment

SQL Server Express is a development time database and it is not recommended to use it on your production server.  The rationale for providing SQL Express edition was to ensure that development can be done without having to install a licensed copy of SQL Server on your development machine…

Additionally most of the hosters do not support SQL Server Express on their shared web servers and enterprises are typically running on full SQL Server in their Staging/Production environment.

When you are developing a Web Project using Visual Studio then your SQL Express MDF file is put inside App_Data folder.  VS also ensures that App_Data folder is set up with the correct read/write access so that your application can then write to the Database files in it… 

When it comes time to deploy your application you should ensure that your MDF files do not get deployed with the rest of your application.  To help with this VS provides option to exclude the content of App_Data folder.

Web Application Projects (VS 2005/ VS 2008)

If you are using Web Application Projects in VS 2005/VS 2008 then when your right click on your project and hit “Publish” then the option to Exclude the content of App_Data is available as a checkbox as shown below:

Web Application Projects (VS 2010)

In VS 2010 web deployment is hugely improved… As part of the clean up this option is now moved to project properties as shown below:

When project properties window opens then navigate to Package/Publish tab… In this tab there is a checkbox which allows you to exclude “App_Data” content while publishing…Check the box as shown below:

With this setting Visual Studio 2010 will make sure that your Web Deployment does not includes content of App_Data folder… If you would like to learn more, check out the rest of the properties of Package/Publish tab…

After setting this property it will get respected automatically while creating a web package or while using 1-Click Publish…

Are there scenarios to not exclude App_Data folder all the time?

Sometimes I have been asked why to give a specific option to Exclude App_Data folder and not exclude it all the time by default.

Well people also put bunch of other files in App_Data folder for e.g. XML files which your web updates or other flat file DBs that your web might potentially use…  In this scenario excluding App_Data would exclude those files too and you would ideally want to avoid that, hence there is an explicit option to leave out the content of App_Data folder…

Hope this helps!!

-Vishal

10 + 20 Reasons why you should Create a Web Package

Before we talk about the reasons why you should create a Web Package let us first understand what is a web package… Web Package is an atomic, transparent, self describing unit representing your web application which can be easily hydrated into any IIS Web server to reproduce your web…  It is a .zip file which not only contains your content but also contains its dependencies like IIS Settings, Databases, GAC DLLs, Registry Keys etc…

The concept of creating Web Packages for deploying your web application to an IIS Web Server is recently introduced with Microsoft Web Deployment Tool (MsDeploy) and towards the end of this post I will talk about how you can create a Web Package for your web app… But before going there let me talk about the 10 reasons why you should consider creating web packages for your web application:

1. Having all your web content and dependencies like IIS Settings & DB into a single .zip file allows you to easily transport it anywhere…
2. If the web package actually contains source code then you can replicate your dev environment to another box relatively easily…  Imagine being able to recreate a project on your home machine by simply emailing yourself a .zip file…
3. If you are deploying in a web farm environment then deploying the web package to various server boxes will allow you to very easily recreate your load balanced web servers…
4. If you are creating software for community to use then sharing web package .zip files with world creates a common handshake model…
5. Web Application Gallery, which will be common home to find reusable Web Applications also uses the same Web Package format… So you will have an opportunity to put up your web app into Web Application Gallery if you create a Web Package…
6. Most of the Package creation process is very automated so you do not need to write custom actions like you would have to do in case of MSIs…
7. Creation of Web Packages can be automated along with your nightly builds really easily using MsBuild with systems like Team Build…
8. You can create a web package for various versions of your web application and easily use the versioned packages to roll back to any version you like…
9. You get free standardized UI to install the Web Packages in IIS Manager which hopefully will become pretty standard and easy for everyone to understand…  If you do not like to use the UI the package can be installed via commandline as well…:-)
10. Most of the automated tools (providers) required for packaging  your web application and its dependencies are available out of the box (few of which are IIS Settings, SQL DBs, Web Content, GAC assemblies, COM components, Registry keys etc)… 

Finally let me mention the out of the box providers which can be invoked when you want to package your web application…  You actually have a choice to call any of these providers depending on what parts of your Web Application you like to be packaged… These are my other +20 reasons why you should create a web package…

1. File System Directory to move a files & folder which contains your web application files like .aspx, .config, images, .js, .css, .master etc – contentPath
2. Creating a new IIS Web Application for your web– iisApp
3. Moving IIS7 and above (read Vista, Win2k8, Win7, Win2k8 R2 and above) Configuration Settings associated with your web (e.g. Default Document, ApplicationPool Mapping etc) – appHostConfig
4. IIS5.1 & 6 (read XP, Win2K3 compatibility)  Metabase Configuration Settings (parallel to IIS7+ settings above) - metakey
5. Pulling data & schema from existing SQL Server Database or custom generated .SQL files which your web uses– dbfullSQL
6. Any Security Certificates (e.g. SSL & ClientAuth) that your web depends upon- cert
7. Any GACed assemblies like 3rd party controls or libraries that your web uses – gacAssembly
8. Any custom IIS7+ Application Pool that your web has created– appPoolConfig
9. Registry key associated with your webs – regkey
10. 32 bit COM Object – comObject32
11. 64 bit COM Object – comObject64
12. Security ACLs associated with folder – setAcl
13. Granular control by pulling just a registry value - regValue
14. ASP.NET root web configuration file on 32 bit machine – rootWebConfig32
15. ASP.NET root web configuration file on 64 bit machine – rootWebConfig64
16. Similar type of support for packaging MySQL DB – dbMySQL
17. Packaging Machine.Config of 32 bit machine – machineConfig32
18. Packaging Machine.Config of 64 bit machine – machineConfig64
19. If there is still a provider missing then you can very easily create one – yourCustomProvider
20. A secret provider which I am not allowed to talk about just yet :-), but trust me it is really a killer provider - secretProvider

So now that you have 10 +20 reasons to create a web package let us talk about how to create one… From end developer/IT pro standpoint you can create Web Packages from various different avenues, some of which are:

• Web Packaging from VS 2010 UI 
• Web Packaging from MsBuild in VS 2010
• Web Packaging from CommandLine
• Web Packaging from PowerShell
• Web Packaging from IIS Manager

Please follow the links above to create a web package using your preferred method… I hope you are jazzed about being able to archive and deploy your web applications using Web Packaging…