'Web Deploy: Replace Rule vs. Parameterization'

When should you use Replace Rules vs. Parameters with Web Deploy? Read on, brave reader!

Web Deploy supports several ways to transform objects during deployment. Why would you want to do this? Because, as I have noted in earlier blog posts, connection strings and even site bindings differ from environment to environment.

The first way is to parameterize. I have covered parameterization in a previous blog post, but I’ll give a quick recap here. A parameter defines a part of an object that should be changed every time the deployment happens. For example, you may want to build a deployment package and parameterize a database connection string. The person who does the deployment is responsible for providing a value for this parameter each time the deployment happens. Here’s how you declare the parameter:

<div><span style="color: #000000;">msdeploy</span><span style="color: #000000;">.</span><span style="color: #000000;">exe -verb</span><span style="color: #800000;">:sync</span><span style="color: #000000;"> -source</span><span style="color: #800000;">:apphostconfig</span><span style="color: #000000;"> -dest</span><span style="color: #800000;">:package</span><span style="color: #000000;">=</span><span style="color: #000000;">c:</span><span style="color: #000000;"></span><span style="color: #000000;">temp</span><span style="color: #000000;"></span><span style="color: #000000;">package</span><span style="color: #000000;">.</span><span style="color: #000000;">zip -declareParam</span><span style="color: #800000;">:name</span><span style="color: #000000;">
</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">Handler Mappings Access Type</span><span style="color: #000000;">"</span><span style="color: #000000;">,</span><span style="color: #000000;">scope</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">apphostconfig</span><span style="color: #000000;">"</span><span style="color: #000000;">,</span><span style="color: #000000;">match</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">//handlers[@accessType]</span><span style="color: #000000;">"</span><span style="color: #000000;">,</span><span style="color: #000000;">kind</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">ProviderPath</span><span style="color: #000000;">"</span></div>

If you look at the ZIP of the package, it now contains a file called parameters.xml with the following contents:

<div><span style="color: #0000FF;"><</span><span style="color: #800000;">parameters</span><span style="color: #0000FF;">></span><span style="color: #000000;">
  </span><span style="color: #0000FF;"><</span><span style="color: #800000;">parameter </span><span style="color: #FF0000;">name</span><span style="color: #0000FF;">="Handler Mappings Feature Permissions"</span><span style="color: #0000FF;">></span><span style="color: #000000;">
    </span><span style="color: #0000FF;"><</span><span style="color: #800000;">parameterEntry </span><span style="color: #FF0000;">kind</span><span style="color: #0000FF;">="DeploymentObjectAttribute"</span><span style="color: #FF0000;"> scope</span><span style="color: #0000FF;">="appHostConfig"</span><span style="color: #FF0000;"> match</span><span style="color: #0000FF;">="//handlers/@accessPolicy"</span><span style="color: #FF0000;"> </span><span style="color: #0000FF;">/></span><span style="color: #000000;">
  </span><span style="color: #0000FF;"></</span><span style="color: #800000;">parameter</span><span style="color: #0000FF;">></span><span style="color: #000000;">
</span><span style="color: #0000FF;"></</span><span style="color: #800000;">parameters</span><span style="color: #0000FF;">></span></div>

When installing the package, you can specify a value for the parameter like this:

<div><span style="color: #000000;">msdeploy</span><span style="color: #000000;">.</span><span style="color: #000000;">exe -verb</span><span style="color: #800000;">:sync</span><span style="color: #000000;"> -source</span><span style="color: #800000;">:package</span><span style="color: #000000;">=</span><span style="color: #000000;">c:</span><span style="color: #000000;"></span><span style="color: #000000;">temp</span><span style="color: #000000;"></span><span style="color: #000000;">package</span><span style="color: #000000;">.</span><span style="color: #000000;">zip -dest</span><span style="color: #800000;">:auto</span><span style="color: #000000;"> -setParam</span><span style="color: #800000;">:name</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">Handler Map
pings Feature Permissions</span><span style="color: #000000;">"</span><span style="color: #000000;">,</span><span style="color: #000000;">value</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">Read,Script</span><span style="color: #000000;">"</span></div>

The second way is to use a replace rule. A replace rule literally replaces an object or a piece of an object at the time of deployment. You should use replace rules when you know the new value. This blog post covers replace rules. Here’s a sample replace rule which changes an attribute in a node in applicationHost.config from “Read” to “Read,Script” (this sets a Handler Mappings feature setting):

<div><span style="color: #000000;">msdeploy</span><span style="color: #000000;">.</span><span style="color: #000000;">exe -verb</span><span style="color: #800000;">:sync</span><span style="color: #000000;"> -source</span><span style="color: #800000;">:apphostconfig</span><span style="color: #000000;"> -dest</span><span style="color: #800000;">:package</span><span style="color: #000000;">=</span><span style="color: #000000;">c:</span><span style="color: #000000;"></span><span style="color: #000000;">temp</span><span style="color: #000000;"></span><span style="color: #000000;">package</span><span style="color: #000000;">.</span><span style="color: #000000;">zip -</span><span style="color: #0000FF;">replace</span><span style="color: #800000;">:objectName</span><span style="color: #000000;">=</span><span style="color: #000000;">handlers</span><span style="color: #000000;">,</span><span style="color: #000000;">scopeAttributeName</span><span style="color: #000000;">=</span><span style="color: #000000;">accessPolicy</span><span style="color: #000000;">,</span><span style="color: #000000;">match</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">Read</span><span style="color: #000000;">"</span><span style="color: #000000;">,</span><span style="color: #0000FF;">replace</span><span style="color: #000000;">=</span><span style="color: #000000;">"</span><span style="color: #000000;">Read,Script </span><span style="color: #000000;">"</span></div>