Attention: We are retiring the IIS.NET Community Blogs. Learn more >

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

19 Comments

  • If you install the "Web Deployment" addin to VS 2008 with sp1, do you need to re-install sp1 (for VS 2008) ?

  • Hey there!

    If I want the Deploy Tool to skip attempting to move a file entirely is there a variation of the -skip within the command line? I am attempting to move over a good sized IIS6 installation to a new IIS7 box. When using the IIS Deploy tool on the IIS6 machine, I keep getting an error when it hits the index.dat file. Which is a pain, to be blunt, because I am not sure why it's even trying to copy that in the first place.

    Thanks!
    - E

  • Yep, if you look at the very bottom of #1 in the blog, it shows the syntax for the command line. If you have any other issues with this, please ask on the MS Deploy forum.

  • The replace not work for me.




    Why ?

  • Try this,

    msdeploy.exe -verb:sync -source:metaKey=/lm/w3svc/1 -dest:metaKey=/lm/w3svc/2 -replace:objectName=metaProperty,scopeAttributeName=name,scopeAttributeValue="ServerBindings",match=x\.x\.x\.x,rep
    lace=y.y.y.y.

    Please post on the MSDeploy forums in the future for a quicker response

  • thank you for the infos. http://www.giffits-partner.de

  • I'm having a basic problem with Web Deploy's config file. First off, I don't see a Microsoft.Web.Deployment.Config-- I only see msdeploy.exe.config and msdepsvc.exe.config (which I understand to be used for the remote service). If I try to edit any of the suggestions in this post into msdeploy.exe.config, I get an error stating
    ` Error: Configuration system failed to initialize
    Error: Unrecognized configuration section rules. (C:\Program Files\IIS\Microsoft Web Deploy\msdeploy.exe.config line 6)
    Error count: 1. `

    Even if I rename the msdeploy.exe.configsettings.example file to msdeploy.exe.config, I get this same error, complaining about the supplied tag.

    I am trying to add a skip rule to not delete files on the destination. When I add this to the command line (-skip:objectName=filepath,skipAction=delete
    ), it's ignored, so I am trying to add it to the config file and running into these problems...

    Any suggestions would be appreciated...

    Thanks!

  • I am having a problem with the syntax to skip a local file from being included in a sync. The original error was:

    C:\>msdeploy -verb:sync -source:metakey=lm/w3svc/228398852 -dest:package=d:\!WebStores\swaintoursapp
    s.zip,encryptPassword=password -enableLink:apppool > d:\!WebStores\swaintoursapps.log
    Error: An error was encountered when processing 'index.dat'.
    Error: The error code was 0x80070020.
    Error: The process cannot access 'c:\Documents and Settings\administrator.SWAINTOURS\Cookies\index.d
    at' because it is being used by another process.
    Error count: 1.

    I added this to the config file in the rule section:



    which returned:

    C:\>msdeploy -verb:sync -source:metakey=lm/w3svc/228398852 -dest:package=d:\!web
    stores\swaintoursapps.zip,encryptPassword=password -enableLink:apppool > d:\!web
    stores\swaintoursapps.log
    Error: Unexpected/unrecognized element ''.
    C:\Program Files\IIS\Microsoft Web Deploy V2\msdeploy.exe.configSettings: (line
    70, position 44)
    Error count: 1.

    Then tried to use skip on the command line:

    C:\>msdeploy -verb:sync -source:metakey=lm/w3svc/228398852 -dest:package=d:\!web
    stores\swaintoursapps.zip,encryptPassword=password -enableLink:apppool -skip:obj
    ectname=filepath,absolutePath="C:\Documents and Settings\administrator.SWAINTOUR
    S\Local Settings\Application Data\Microsoft\Windows\*" > d:\!webstores\swaintour
    sapps.log
    Error: The regular expression 'C:\Documents and Settings\administrator.SWAINTOUR
    S\Local Settings\Application Data\Microsoft\Windows\*' is invalid.
    Error: parsing "C:\Documents and Settings\administrator.SWAINTOURS\Local Setting
    s\Application Data\Microsoft\Windows\*" - Unrecognized escape sequence \L.
    Error count: 1.

    Any help is appreciated. Thank You,
    Den

  • All,

    I realize there is an inconsistancy between the original index.dat error and the usrClass.dat correction. This was a result of logging on to the server with different credentials in an effort to eliminate that as a possible cause of the problem. Still, the question remains as to how to properly code the config file or command line to exclude files.

    Thanks again,

    Dennis

  • All,

    I have been able to work out the command line script with information I have gained on this excellent site.
    C:\>msdeploy -verb:sync -source:metakey=lm/w3svc/228398852 -dest:package=d:\!web
    stores\swaintoursapps.zip,encryptPassword=password -enableLink:apppool -skip:obj
    ectname=filepath,absolutePath="Documents and Settings\\*" > d:\!webstores\swaint
    oursapps.log


    I understand now that I had to escape the backslashes and periods in the path. However, I continue to get "cannot access 'path' because it is in use. I do not understand this well enough to know what can and cannot be skipped.
    Is it best to stop the iis service before doing the package creation? For example, the current inaccessable file is c:\Inetpub\catalog.wci\00000002.ps1 which would seem to me to be required.


    Sorry for my ignorance, any help is appreciated.


    Dennis

  • OK, so I have continued to research and found the ignoreErrors switch. This apparently works with the objectname filepath or dirpath. I have not specified either of those parameters on the source or destination and instead have used the metakey to move individual websites. I do use filepath with a skip switch to skip files in /documents and settings, not sure why they would be needed, but now get error 0x80070020, being used by another process, on \inetpub\catalog.wci\ . I guess I could continue to skip folders that return errors but I don't know how that wil affect the migration results.

    I paste the latest command line and error below. The question is, can I safely skip these folders, can i use the ignoreErrors option, or should I just stop the websites for the duration of the package creation? Any other ideas?



    C:\>msdeploy -verb:sync -source:metakey=lm/w3svc/228398852 -dest:package=d:\!webstores\swaintoursapp
    s.zip,encryptPassword=password -enableLink:apppool -skip:objectname=filepath,absolutePath="Documents
    and Settings\\*" > d:\!webstores\swaintoursapps.log
    Error: An error was encountered when processing '00000002.ps1'.
    Error: The error code was 0x80070020.
    Error: The process cannot access 'c:\Inetpub\catalog.wci\00000002.ps1' because it is being used by a
    nother process.
    Error count: 1.

    Thanks Again,

    Dennis

  • All -

    Is this the proper Syntax to not override the IP addresses on the Destination Server??

    msdeploy -verb:sync -source:computername=web-dev1,contentpath=D:\Sites\MySite\wwwroot -dest:computername=web-iis1bl,contentpath=D:\Sites\MySite\wwwroot,-skip:objectName=binding,skipAction=destination

    or

    msdeploy -verb:sync –source :computername=web-iis1bl,metakey=lm/w3svc/2126524491 -dest:computername=web-iis2 bl,metakey=lm/w3svc/2126524491 -skip:objectName=binding;skipAction=destination

  • I'm trying to publish from a site from "Server A" to "Server B" and the publish keeps overwriting the IP address of the destination site with an IP from the original site. I've tried a few suggestions that I have seen, but both overwrite the IP address. Below are the 2 options that I have tried. Does anyone see what I'm doing wrong?
    Option 1
    msdeploy -verb:sync -source:apphostconfig="NAME OF SITE GOES HERE" -dest:apphostconfig="NAME OF SITE GOES HERE",computername="DESTINATION SERVER NAME" -skip:objectName=binding;skipAction=destination
    Option 2
    msdeploy -verb:sync -source:apphostconfig="NAME OF SITE GOES HERE" -dest:apphostconfig="NAME OF SITE GOES HERE",computername="DESTINATION SERVER NAME" -skip:objectname=metaProperty,keyAttribute="serverbindings"

  • I'm trying to publish from a site from "Server A" to "Server B" and the publish keeps overwriting the IP address of the destination site with an IP from the original site. I've tried a few suggestions that I have seen, but both overwrite the IP address. Below are the 2 options that I have tried. Does anyone see what I'm doing wrong?
    Option 1
    msdeploy -verb:sync -source:apphostconfig="NAME OF SITE GOES HERE" -dest:apphostconfig="NAME OF SITE GOES HERE",computername="DESTINATION SERVER NAME" -skip:objectName=binding;skipAction=destination
    Option 2
    msdeploy -verb:sync -source:apphostconfig="NAME OF SITE GOES HERE" -dest:apphostconfig="NAME OF SITE GOES HERE",computername="DESTINATION SERVER NAME" -skip:objectname=metaProperty,keyAttribute="serverbindings"

  • I think I figured out how to skip the IP during a publish. Does anyone see an issue with doing it this way?

    Publish a SINGLE website
    msdeploy -verb:sync -source:apphostconfig="NAME OF SITE GOES HERE" -dest:apphostconfig="NAME OF SITE GOES HERE",computername="DESTINATION SERVER NAME" -skip:objectName=binding

    Publish the ENTIRE server
    msdeploy -verb:sync -source:webServer,computerName="SOURCE SERVER NAME" -dest:webServer,computerName="DESTINATION SERVER NAME" -skip:objectName=binding

  • The replace rules are not working for me on IIS 7+webdeploy 3.0 using the same syntax as showed above(only in commandline mode i got it works):



    At this link - http://forums.iis.net/t/1152939.aspx - you are talking about an internal fix that should've been included in the latest release, could you confirm that?

    I opened a thread on IIS support forum - http://forums.iis.net/t/1192934.aspx - could you take a look?

    Regards,
    a.

  • what rule shoud skip changes of IIS ftp setting "External Ip Address Of Firewall"?

Comments have been disabled for this content.