What has changed about skip-replace rules in RC?

There has been a lot of buzz around the way skip rules have changed in the RC version of MSDeploy. Here is a blog post that will explain what has changed and what are the current limitations.

Currently there are two different features in MS Deploy that enable you to skip objects, and one feature that enables you to replace objects.

1) Skip rules are of type Microsoft.Web.Deployment.DeploymentSkipRuleHandler and can be specified:

a) In <rules> section of msdeploy.exe.configsettings file

They cannot be created on the fly via the command-line, they have to be created in the registry or config. However, you can enable or disable a skip rule from the command-line using -enableRule or -disableRule.

2) Skip directives are of type Microsoft.Web.Deployment.DeploymentSkipDirective and can be specified:

a) On the fly using the command-line exe with the -skip flag

b) In <skipDirectives> section of msdeploy.exe.configsettings

You cannot disable or enable skip directives from the command-line in RC1. You have to disable or enable the rules by putting them in config or the registry.

3) Replace rules are of type Microsoft.Web.Deployment.ReplaceRuleHandler and can be specified:

a) On the command-line using the –replace

b) In <rules> section of msdeploy.exe.configsettings file

You can enable or disable a replace rule from the command-line using -enableRule or -disableRule.

Basic difference between a skip rule and a skip directive

A Skip Directive is what you get when you specify -skip on the command-line. This will cause objects to be skipped from “Dump” (read) as well as “Sync” (write) operations and thus they are removed before any authorization is done. This is a way to avoid objects that you do not have permission to touch. In other words, when we actually form XML views of source and destination objects before performing the actual operation, the Skip Directives will remove the item from the XML view on the source and destination as well.

A skip rule on the other hand comes into effect only when the actual sync takes place after all authorization is done.

To see the difference, add the following skip rule in msdeploy.exe.configsettings

<rule name="SkipAllOperations" type="Microsoft.Web.Deployment.DeploymentSkipRuleHandler" skipAction="AddChild" objectName="dirpath" absolutePath="d:\\inetpub\\wwwroot" enabled="false"/>

Now, do a dump of webserver using “msdeploy.exe -verb:dump -source:webserver”. You will notice that “d:\inetpub\wwwroot” exists in the dump

Now, use a skip directive and do a webserver dump on the command-line as follows

msdeploy.exe -verb:dump -source:webserver -skip:objectName=dirpath,absolutePath="d:\\inetpub\\wwwroot"

You will see that the dump does not show “d:\inetpub\wwwroot” or any of the dirpath objects under it.

Syntax

1) Skip Rules (you can refer the older skip-replace blogpost for more information on syntax and examples)

skipAction is a required attribute in RC. Supported values in RC version for skipAction are “AddChild”, “Update”, “Delete”

2) Replace Rules (you can refer the older skip-replace blogpost for more information on syntax and examples)

3) Skip Directives

A skipdirective is any combination of objectName, keyattribute,xpath, absolutePath or any attribute in the form of attributes.<name>. Multiple skips can be passed as well. All conditions in a skip should be met to make you skip an object.

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.

xPath – optional xPath expression for entry which should be skipped. You can use a non-xml dump to see xPaths of various entries.

keyAttribute – Optional case-insensitive regular expression. KeyAttribute is an attribute that can uniquely identify the object that you would like to skip. The usage is keyAttribute=”<keyAttributeValue>”. To identify keyAttribute names, sync to an archive and look for MSDeploy.MSDeployKeyAttributeName.

          Example of usage:

          When you sync a contentpath to an archive, your archive.xml will look something like

      <MSDeploy.contentPath MSDeploy.ObjectResolver.dirPath="Microsoft.Web.Deployment.DirPathObjectResolver">
       <contentPath path="d:\inetpub\wwwroot" MSDeploy.path="2" MSDeploy.MSDeployKeyAttributeName="path" >
        <MSDeploy path="d:\inetpub\wwwroot" MSDeploy.MSDeployLinkName="contentPath" />
       </contentPath>
      </MSDeploy.contentPath>

          In the above scenario, you can see that your KeyAttributeName=”path”, hence the value of “path” attribute ("d:\inetpub\wwwroot") is what you would have to specify in your skip directive as 

          –skip:objectName=contentpath,keyAttribute=”d:\\inetpub\\wwwroot”

attributes.<name> – Takes a case-insensitive regular expression attribute value as input. “<name>” should be replaced with the name of the attribute that you would like to skip.

You can identify attributes with a simple xml dump of the object.

           Example of usage:

           msdeploy –verb:dump –source:appHostConfig=”Default Web Site” –xml, will yield something like

      <MSDeploy.appHostConfig>
       <appHostConfig path="Default Web Site">
        <site name="Default Web Site" id="1" serverAutoStart="true">
         <bindings>
          <binding protocol="http" bindingInformation="10.10.10.10:80:" />
          <binding protocol="https" bindingInformation="*:443:">
          . . . . . . . . . 
       </appHostConfig>
      </MSDeploy.appHostConfig>

          In the above protocol, path, name, bindingInformation are all attributes, so in order to skip https bindings, you will need to specify

          -skip:attributes.protocol=”https”

Examples of commonly used Skip and Replace Rules (consolidated from forum posts)

1) Skip all operations on “DefaultAppPool”

<skipDirective name="MSDeployAppPool">
<skip objectName="add" absolutePath="AppPool2"/>
</skipDirective>

2) Skip deleting certain files on destination. Define the rule in both msdeploy,exe,configsettings and msdepsvc.exe.configsettings on the remote machine.

<rule name="DoNotDeleteFilesOnDestination" type="Microsoft.Web.Deployment.DeploymentSkipRuleHandler" objectName="filePath" 
absolutePath="welcome.png" skipAction="Delete" isDefault="true" enabled="true"/>

To skip deleting all files on the destination, you can use the following rule.

<rule name="DoNotDeleteFilesOnDestination" type="Microsoft.Web.Deployment.DeploymentSkipRuleHandler" objectName="filePath" 
skipAction="Delete" isDefault="true" enabled="true"/>

3) Replace IP address binding on IIS 7.0

<rule name="ReplaceIPAddressInBinding" type="Microsoft.Web.Deployment.DeploymentReplaceRuleHandler" isDefault="true" 
objectName="binding" targetAttributeName="bindingInformation" match="x\.x\.x\.x" replace="y.y.y.y" />

4) Replace IP address binding on IIS 6.0

<rule name="ReplaceIPAddressInBinding" type="Microsoft.Web.Deployment.DeploymentReplaceRuleHandler" isDefault="true" 
objectName="metaProperty" scopeAttributeName="name" scopeAttributeValue="serverbindings" targetAttributeName="value" 
match=":80:" replace=":82:" />

5) Change drive letters during a sync 

<rule name="ChangeDriveLetters" type="Microsoft.Web.Deployment.DeploymentReplaceRuleHandler" isDefault="true" 
objectName="metaProperty" scopeAttributeName="name" scopeAttributeValue="Path" targetAttributeName="value" 
match="c:" replace="d:" />

6) Replace anonymous user names and passwords

<rule name="ChangeAnonymousUser" type="Microsoft.Web.Deployment.DeploymentReplaceRuleHandler" scopeAttributeName="name" 
scopeAttributeValue="AnonymousUserName" match="IUSR_IIS-115" replace="IUSR_IIS124"/>
<rule name="ChangeAnonymousPassword" type="Microsoft.Web.Deployment.DeploymentReplaceRuleHandler" scopeAttributeName="name" 
scopeAttributeValue="AnonymousUserPass" match="password" replace="newpassword"/>

7) Skip syncing all files except web.config

-skip:xpath=filePath[@path!='web.config']

8) Skip syncing files all *.gif files under a folder

-skip:objectName=filepath,absolutePath=.*folder\\subfolder\\.*\.gif$

9) Skip syncing empty folders

-skip:xpath=//dirPath[count(*)=0]

10) Skip syncing https bindings

-skip:attributes.protocol=https

11) More examples are here http://blogs.iis.net/msdeploy/archive/2009/02/16/beta-2-skip-and-replace-rules.aspx.

Known Bugs and Limitations

1) Replace rules cannot replace filenames like it used to be able to. For example, you cannot rename all *.jpg files to *.jpeg on sync. This is a known issue we are looking to fix in our next release.

2) When specifying skip rules over the agent, you will need to define the rule in both msdeploy.exe.configsettings on the source and msdepsvc.exe.configsettings on the destination for it to work.

2 Comments

Comments have been disabled for this content.