IT:AD:WebDeploy:HowTo:Create a Publish Profile/Parameters.xml

When you Create a Publish Profile you are creating an IT:AD:MSBuild Project file, that by convention will be looking to see if you have created an accompanying Parameters.xml file.

By default, Visual Studio will have not made the Parameters.xml file for you – it's up to you to Add a New Item... → Xml File to the root of the Project:

• The file does not need to be packaged, just get created when you use WebDeploy, so set BuildAction=None.
• It will be compiled by Visual Studio, and output beside the output package zip, as MyApp.SetParameters.xml
• Syntax is always parameter element, with a nested parameterEntry.
• A parameter can have more than one parameterEntry to search for and replace in more than one location.
• Parameters can be validated, using the parameterValidation element nested under a parameter
• The tag is more important than it looks…

For each transformation, you'll be defining a parameter element, with a nested parameterEntry:

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

<parameters>

   <parameter name="DataBaseUserName"
      description="Database username"
      defaultValue="MySQLDatabaseUser"
      tags="MySQLParam"
      <parameterEntry
         kind="TextFilePosition"
         scope="application\\settings.php"
         match="92;21;11" />
      </parameter>

</parameters>

The element names and attributes are:

• parameter
  • name: required unique name to identify the parameter with e.g. “Service 1 endpoint address”
    • Can be any name – but the following are WellKnown/ 10 names that IIS's UI will automatically provide a friendlyName and description for the parameter:
      • MySqlConnectionString
      • SqlConnectionString
      • DbAdminPassword
      • DbAdminUsername
      • DbName
      • DbServer
      • DbUsername
      • DbUserPassword
      • IisApp
      • SetAcl
  • 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…
  • tags: tags help the UI determine how to construct the UI for end installers to install the product. The following are the choices:
    • iisapp: Identities the parameter as the application path (defaultValue should be set to Default Web Site/application1) to install the application.
      • Required (at least one tag parameter should be tagged with it) . There must be at least one parameter that has this tag and that specifies the iisApp provider as its target.
    • hidden: a Hidden parameter is not shown to the user as part of the installation UI (a defaultValue must be set though).

      • These parameters are used either to set a hard-coded default value or to set a computed default value.
        • Hard-coded defaults are sometimes used when establishing a parameter for future use.
        • Computed values are used to construct a parameter’s value from other parameters. When constructing computed values, you can refer to other parameters by putting the other parameter name surrounded by {}s in the place you want the value.
      • SQL Indicates the parameter is related to a database.
      • Password: The UI will hide the value of that password.
      • New: When used together with the Password tag, this identifies a field that will be used to set a new password.
      • For creating new databases, use all 6:
      • dbUsername
      • dbUserPassword
      • dbAdminUsername
      • dbAdminPassword
      • dbServer
      • dbName
      • SQLConnectionString: identifies that a field (usually a Hidden one) is being used as a connection string to a database.
      • Validate: only allowed when specified with one of the connection string tags. Validate will validate the database credentials before allowing the user to proceed through the rest of the installation.

      * parameterEntry:

  • 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…
  • scope: Regular Expression to determine what entities (files e.g. web.config, DBs, Web Deploy providers etc) does the parameter apply to.
    • Ref: MSDN: http://technet.microsoft.com/en-us/library/dd569084(WS.10).aspx#BKMKParameterKindSettings * parameterValidation: * type=“AllowEmpty”: * <parameterValidation type="Boolean" /> * <parameterValidation type="Enumeration" validationString="value1,value2,value3,value4" /> * <parameterValidation type="RegularExpression" validationString=".+" /> * <parameterValidation type="RegularExpression,allowEmpty" validationString="^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$" /> ### Troubleshooting ### * Parameters only transform – they are not as powerful as WCT and won't inject in settings that are not currently in the web.config or target files. * The same goes for the Creating of the Root VirtualDirectory Path parameter as well: the deployment package has to be including IIS settings for it to have something to replace. ## Resources ## * http://vishaljoshi.blogspot.co.nz/2010/07/web-deploy-parameterization-in-action.html * http://www.iis.net/learn/develop/windows-web-application-gallery/reference-for-the-web-application-package * http://vishaljoshi.blogspot.co.nz/2010/07/web-deploy-parameterization-in-action.html