How to write skip and replace rules for MSDeploy
MSDeploy has two built-in general purpose rule handlers (for more information about rules, take a look at the core components of MS Deploy blog post) which can be used to create rules to skip sync/migrate of some object or to replace the source information with something else on the fly. You can create and add new rules using these general purpose rule handlers in the configuration file (Microsoft.Web.Deployment.Config) or you can use –skip or –replace switches on the command line.
If you add a rule in the configuration file, you can either set isDefault attribute to true in which case the rule is enabled by default. You will need –disableRule switch on the command line to selectively disable it. Alternatively, you can keep isDefault=false and use –enableRule switch to selectively enable it.
When creating rules using –skip, -replace switches on the command line, you can specify more than one -skip/-replace switch to add multiple skip/replace rules. Before moving on to learning how to write these rules, let’s understand how each object that will be added/updated/deleted on the destination is represented internally and understand the terminology that will be useful later. As an example, let’s use an XML view of few source entries that are generated by the command below.
msdeploy.exe -verb:dump "-source:appHostConfig=DefaultWeb Site/abc" -xml
<appHostConfig path="Default Web Site/abc">
<application path="/abc"
applicationPool="DefaultAppPool"
enabledProtocols="http">
<virtualDirectoryDefaults path=""
physicalPath=""
userName=""
password=""
logonMethod="ClearText"
allowSubDirConfig="true" />
<virtualDirectory path="/"
physicalPath="d:\Compiler"
userName=""
password=""
logonMethod="ClearText"
allowSubDirConfig="true">
<dirPath path="d:\Compiler" />
</virtualDirectory>
</application>
</appHostConfig>
Text in brown is considered the objectName, which is usually the provider name but can be something else when object are Xml/Config files. Red text is attribute names, which will be required when defining scopeAttributeName, targetAttributeName in replace rules. Blue entries are the attribute value.
Most providers entries have a “path” or “name” associated with them to uniquely identify the object from a collection of objects of same type which is what is referred to as “absolutePath” in skip rules below. You can use the xml dump to find out the values of objectNames, absolutePaths, attribute names/values, etc. Below is how you use this information to write skip/replace rules.
1. Skip Rule
You can create a skip rule to skip an entry based on objectName, absolutePath, skipAction or xPath. Each entry in the source XML view is matched with available information in the skip rule and is not considered for sync/migrate if a match is found. Below is how available information is interpreted in the SkipRuleHandler.
è objectName – optional case-insensitive regular expression. If specified, entries with matching objectName are considered for skip. If not specified, all elements are considered for skip.
è absolutePath – optional case-insensitive regular expressions and are matched against absolute path of each element. If present, entries with absolutePath matching this value are considered. If not specified, all are considered.
è skipAction – optional value to specify what operations to be considered for skip. This can be source or destination or update or delete or addchild. Default is set to source or destination which means that skip all operations on source and destination which match objectName, absolutePath, xPath criteria.
è xPath – optional xPath expression for entry which should be skipped. You can use a non-xml dump to see xPaths of various entries.
Here are some examples of skip rules which can be added to Microsoft.Web.Deployment.Config.
<rule name="SkipAllOperationsOnDefaultAppPool"
type="Microsoft.Web.Deployment.SkipRuleHandler" objectName="add"
absolutePath="DefaultAppPool" isDefault="true" />
<rule name="DoNotDeleteFilesOnDestination"
type="Microsoft.Web.Deployment.SkipRuleHandler" objectName="filePath"
skipAction="Delete" isDefault="true" />
<rule name="SkipAllRegistryOperations"
type="Microsoft.Web.Deployment.SkipRuleHandler" objectName="^reg"
isDefault="true" />
<rule name="SkipRegistryKeysUnderInetInfo"
type="Microsoft.Web.Deployment.SkipRuleHandler" objectName="regValue"
absolutePath="inetinfo" isDefault="true" />
DoNotDeleteFilesOnDestination will look like below if specified on the command line.
-skip:objectName=filepath,skipAction=delete
2. Replace rule
Replace rules require following information based on which entry is considered for replacement.
è objectName – optional case insensitive regular expression. If specified, only these entries will be considered for replace. If not specified, all entries are considered.
è scopeAttributeName – optional case insensitive regular expression. If present, entries which have an attribute matching this regular expression are picked to be matched with scopeAttributeValue. If not present, all attributes are considered for matching with scopeAttributeValue.
è scopeAttributeValue – optional case insensitive regular expression. If present, scopeAttributeName attribute value is matched with this. If an attribute with expected value is found, this entry is considered for replace. If not present, no filtering is done and all entries are considered for replace.
è targetAttributeName – optional case insensitive regular expression. If present, value of this attribute is matched with “match” value. If not present, all attribute values are matched with “match”. These are the attributes which are replaced.
è match – optional case insensitive regular expression. If present, entries with attributes whose values match this regular expression are considered for replace. If not present, all attribute values are replaced.
è replace – Required and is not interpreted as a regular expression. This is the new value of optional target attributes which match optional match. If both targetAttributeName and match are not defined, all attributes of entries which are picked for replace will be replaced by this value. Replace is done only on part which is matched in the value by regular expression.
Few examples of replace rules which can be added to config are below.
<rule name="ReplaceIPAddressInBinding"
type="Microsoft.Web.Deployment.ReplaceRuleHandler" isDefault="true"
objectName=”binding” targetAttributeName=”bindingInformation”
match=”x\.x\.x\.x” replace=”y.y.y.y” />
<rule name="ReplaceJpegWithJpgInFiles"
type="Microsoft.Web.Deployment.ReplaceRuleHandler" isDefault="true"
objectName=”filePath” targetAttributeName=”path”
match=”\.jpeg$” replace=”.jpg” />
<rule name="SetAllowSubDirConfigToFalseForImageFoldersInIIS7"
type="Microsoft.Web.Deployment.ReplaceRuleHandler" isDefault="true"
objectName=”virtualdirectory” scopeAttributeName=”physicalPath” scopeAttributeValue=”Image”
targetAttributeName=”allowSubDirConfig” match=”true” replace=”false” />
On command line, ReplaceIPAddressInBinding rule will look like following.
-replace:objectName=binding,targetAttributeName=bindingInformation,
match=x\.x\.x\.x,replace=y.y.y.y
Read this for help with regular expressions.
Thanks,
Kanwal, Faith, Yamini