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:
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
