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ā¦
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ā¦)
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ā¦
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ā¦
