Using declareParam and setParam
Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista, Windows XP
declareParam
-declareParam is used during package or archive creation. You use it to identify an attribute in the package or archive, and to create a named parameter that will be assigned to the attribute. The parameter for the attribute is stored inside the created package or archive. When the package or archive is later synchronized, the user can specify a custom value for the parameter that was declared. You can also specify a default value for the parameter. If you do not specify a default value, the user who synchronizes the package will be required to specify a value at synchronization time. -declareParam can be used only with the package or archiveDir providers.
The parameters that you declare are stored in the Parameters.xml file inside the package, as the following sample shows.
<parameters>
<parameter name="DataBaseUserName"
description="Database username"
defaultValue="MySQLDatabaseUser"
tags="MySQLParam"
<parameterEntry
type="TextFilePosition"
scope="application\\settings.php"
match="92;21;11" />
</parameter>
</parameters>
setParam
-setParam enables you to specify, at synchronization time, a value for parameter that you declared by using -declareParam when you created the package or archive. It can also be used to specify a value for certain built-in kinds of parameters without having used -declareParam first. Unlike -declareParam, which can be used only with the package or archiveDir providers, -setParam can be used with any other provider to customize a sync operation.
Note
If a parameter was declared in a package by using -declareParam, but the parameters that were declared are forgotten or unknown, you can use the getParameters verb to display the parameters. For more information about getParameters, see Web Deploy getParameters Operation.
Syntax
-declareParam:name=<ParameterName>
,kind=<ParameterKind>
,scope=<ParameterScope>
,match=<RegularExpression>
,defaultValue=<string>
,description=<ParameterDescription>
,tags=<tag>[,<tag>,...]
-setParam:name=<ParameterName>
,kind=<ParameterKind>
,scope=<ParameterScope>
,match=<RegularExpression>
,value=<string>
,description=<ParameterDescription>
declareParam Settings
The following table describes the settings for -declareParam.
| Setting | Description |
|---|---|
defaultValue |
Optionally specifies a default value for a parameter for a package or archive that has been created with -declareParam. At synchronization time, the default value will be used if the user does not specify a value for the parameter by using -setParam. |
description |
An optional user-supplied string that describes the purpose of the parameter. The description will be visible in the Parameters.xml file and can be displayed by using the Web Deploy getParameters verb. For more information about getParameters, see Web Deploy getParameters Operation. |
match |
Specifies an item to be matched. The exact usage of match depends on the parameter kind. In most cases the value that you specify for match will be an XPath Expression. You cannot use match with setParam if the parameter that match specifies has already been declared in the source package or archive by using declareParam. For more information about the usage of match, see the Parameter Kind Settings section of this topic. |
name |
A required user-supplied string that uniquely identifies the parameter. |
scope |
A required regular expression that specifies the scope of the specified parameter kind. The exact meaning depends on the parameter kind. For more information, see the Parameter Kind Settings section of this topic. |
tags |
Optionally sets attributes about the parameter for later reference. For example, the parameter might be tagged as a password so that a user interface will not display the password value. |
kind |
A required string that specifies the parameter kind. The possible kinds of parameters are DeploymentObjectAttribute, DestinationBinding, DestinationVirtualDirectory, ProviderPath, TextFile, TextFilePosition, and XmlFile. Each of these is described in the Parameter Kind Settings section. |
setParam Settings
The following table describes the settings for -setParam.
| Setting | Description | ||
|---|---|---|---|
defaultValue |
Used with -declareParam to specify a default value for a parameter when a package or archive is created. When the package is later synchronized, the default value will be used if you do not specify a value by using the -setParam parameter. |
||
match |
Specifies an item to be matched. The exact usage of match depends on the parameter kind. For more information, see the Parameter Kind Settings section of this topic. |
||
name |
A user-supplied string that uniquely identifies the parameter. A name is required when -declareParam was used to create the archive or package that is the source for the operation.
|
||
scope |
A required regular expression that specifies the scope of the specified parameter kind. The exact meaning depends on the parameter kind. For more information, see the Parameter Kind Settings section of this topic. |
||
kind |
Specifies the parameter kind. A kind is required if no declared parameter exists in the source. The available kinds of parameters are DeploymentObjectAttribute, DestinationBinding, DestinationVirtualDirectory, ProviderPath, TextFile, TextFilePosition, and XmlFile. Each of these is described in the Parameter Kind Settingssection of this topic. |
||
value |
A required string that specifies a value for a parameter. |
.gif)
NoteParameter Kind Settings
The following describes the settings for kind and how the scope and match are used with them.
Note
Setting
match usage
match=<XPathExpression>
A required XPath expression that identifies the attributes whose values will be replaced.
Setting |
DestinationBinding |
Description |
When used with -declareParam, assigns a parameter to the specified source binding. At synchronization time, a new value for the binding can be specified by using -setParam. By using DestinationBinding, you can create a site on the destination that has a binding that is different from the binding on the source. DestinationBinding can be used with either IIS 6.0 or IIS 7. |
scope usage |
scope="Default Web Site" scope=lm/w3svc/1 A required regular expression that specifies the name of an IIS 7 Web site or the site ID of an IIS 6.0 Web site. For more information about regular expressions, see Regular Expressions. |
match usage |
match=<Regular Expression> An optional regular expression that can be used to match any HTTP or HTTPS binding when there are multiple bindings for a site. The bindings that match will be targeted for replacement. |
Setting |
DestinationVirtualDirectory |
Description |
Used with -declareParam to specify a parameter for the physical path of a source virtual directory. At synchronization time, a new value for the physical path can be specified by using -setParam. |
scope usage |
scope="Default Web Site" A required regular expression that identifies a virtual directory or directories by matching the absolute virtual directory path. For more information about regular expressions, see Regular Expressions. |
match usage |
Not applicable. |
Setting |
ProviderPath |
Description |
Enables you to parameterize a provider path so that it can be changed during a synchronization operation. For example, when you synchronize a site, you can change the site name during synchronization and create a completely new site on the destination. |
scope usage |
scope=<ProviderName > A required regular expression that specifies the provider for the operation. If you are not using a manifest, scope by default specifies the provider that you are using for the source and destination. If you are using a manifest, scope specifies one or more of the providers listed in the manifest. For more information about regular expressions, see Regular Expressions. |
match usage |
match=<Regular Expression> When you use a manifest in which a provider is referenced multiple times, optionally identifies the path to be affected by parameterization. For more information about regular expressions, see Regular Expressions. |
Setting |
TextFile |
Description |
Specifies a string or strings to be replaced in a text file. |
scope usage |
scope=<RegularExpression> A required regular expression that matches the absolute path of the target file. For example, when you use the contentPath provider, scope can specify the name of the file that contains the text that you want to change. For more information about regular expressions, see Regular Expressions. |
match usage |
match=<text> <text> is a required text string or regular expression that matches the text to be replaced. The simplest usage is to just provide the exact text. |
Important
Setting
Setting |
XmlFile |
Description |
Replaces content in any XML file. For example, you can use this kind of parameter to parameterize an attribute in a Web.config file. |
scope usage |
scope=<RegularExpression> A required regular expression that identifies the absolute path of the XML file. For instance, when you use the contentPath provider, scope can be the name of the specific XML file that will be altered. For more information about regular expressions, see Regular Expressions. |
match usage |
match=<Xpath> <Xpath> is a required XPath expression that identifies the attributes whose values will be replaced. |
Example usages
1) The following example creates a package based on the default Web site and declares a parameter for an <add> element in the Web.config file with a default value of "DefaultWebPage.htm".
msdeploy –verb:sync –source:apphostconfig="Default Web Site" –dest:package=parameterpackage.zip –declareParam:name=param,kind=XmlFile,scope=web.config,match=//add/@value,defaultValue=DefaultWebPage.htm
2) The following partial example shows syntax that uses DeploymentObjectAttribute for the kind parameter.
-setParam:kind=DeploymentObjectAttribute,scope=virtualDirectory,match=virtualDirectory/@physicalPath,value=c:\physicalDirectory
3) The following partial example shows syntax that uses DestinationBinding for the kind parameter.
-setParam:kind=DestinationBinding,scope=MySite,value=:82:
4) The following partial example shows syntax that uses DestinationVirtualDirectory for the kind parameter.
-setParam:kind=DestinationVirtualDirectory,scope=MySite/MyAppRoot,value=c:\newRoot
See also
Web Deploy archiveDir Provider