Web Deploy Rules
Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista, Windows XP
Web Deploy configuration rules modify the behavior of sync (but not dump) operations. For example, a rule can cause UNC paths to be skipped, or normalize paths that contain environment variables. Before Web Deploy adds, updates, or deletes an object, it checks to see whether a rule exists that applies to the operation.
The <rules> section of the Msdeploy.exe.configsettings.example configuration file, which is located in the %program files%\IIS\Microsoft Web Deploy folder, shows how rule definitions map rule names to rule handlers. A rule will be used only if its isDefault attribute is set to true. Each rule will be applied to every element in an operation, but the rule itself will determine whether to process the element that has been passed to it.
By default, no Msdeploy.exe.configsettings file exists, but you can create your own by renaming and editing the Msdeploy.exe.configsettings.example file. If no Msdeploy.exe.configsettings file exists, the rules that are enabled by default will be used.
Built-in Web Deploy rules
The rules that are installed with Web Deploy are listed in the following table. The display names of the rules are in parentheses. The relative processing order is given in brackets. A lower number indicates an earlier processing order.
| Rule Name | Description | ||
|---|---|---|---|
AboFilter (ABO Filter Rule) [0.50] |
Handles the details of dealing with Admin Base Objects (ABO) when you synchronize from IIS 5.1 or IIS 6.0 to IIS 7. This rule is enabled by default. For more information, see ABO Filter Rule. |
||
AnonymousUser (Anonymous User Rule) [0.50] |
Safely converts the anonymous user when you synchronize from IIS 6.0 or earlier to IIS 7 by using the metaKey provider. The rule checks whether AnonymousUserName or AnonymousUserPass are being synchronized. For AnonymousUserName, the rule changes IUSR_<MachineName> to IUSR. For AnonymousUserPass, the rule stops synchronization of the corresponding password. This rule is enabled by default. |
||
ApplicationExistsRule (Application Exists Rule) [0.55] |
In Web Deploy 2.0, skips the creation of the application when it already exists on the destination. This rule is enabled by default, and is always enabled when the remote server is using Web Deploy 2.0. When synchronizing to a remote destination, the source cannot override the behavior of this rule.
|
||
AppPoolIdentity (App Pool Identity Rule) [0.50] |
Ensures the proper transfer of application pool identity credentials. When the metaKey provider is used in a sync operation from IIS 6.0 to IIS 7, this rule ensures that the values for WAMUserName and WAMUserPass are synchronized only if the AppPoolIdentityType metabase property on the source is set to 3 (Specific User). This rule prevents the IWAM_<ComputerName> account, which is the default value for WAMUserName in IIS 6.0, from being transferred to IIS 7, where the IWAM_<ComputerName> account does not exist. This rule is enabled by default. |
||
AppRootNormalize (App Root Rule) [0.50] |
Matches two application roots that have different site IDs. For example, this rule enables /lm/w3svc/3/root to be synchronized with /lm/w3svc/4/root when you synchronize site 3 to site 4. This rule is enabled by default. |
||
BlockHarmfulDeleteOperations (Block Harmful Provider Delete Operations Rule) [0.50] |
Prevents certain providers from performing delete operations that could be harmful. The blocked providers include appHostSchema, auto, dbFullSQL, dbMySQL, machineConfig32, machineConfig64, manifest, recycleApp, rootWebConfig32, rootWebConfig64, WebServer, and WebServer60. This rule is enabled by default. Warning You should not disable this rule.
|
||
BlockUnsupportedDeleteOperations (Block Unsupported Provider Delete Operations Rule) [0.50] |
Prevents certain providers from performing delete operations that could cause unexpected results. The blocked providers include archiveDir, comObject32, comObject64, fcgiExtConfig, gacAssembly, metaKey, package, regKey, regValue, runCommand, setAcl, and urlScanConfig. This rule is enabled by default. Warning Disabling this rule is not recommended.
|
||
ClassicAppPoolProtectRule (Classic App Pool Protect Rule) [0.50] |
In an operation that uses the metaKey provider to synchronize from IIS 6.0 or earlier to IIS 7, prevents the IIS 7 "Classic .NET AppPool" application pool and IIS 7 ManagedPipelineMode settings from being deleted. This rule is enabled by default. |
||
CreateApplicationRule (Create Application Rule) [0.50] |
1) In Web Deploy versions 1, 1.1, and 2.0, the CreateApplicationRule rule checks to ensure that the destination application pool's ManagedRuntimeVersion, Enable32BitAppOnWin64, and ManagedPipelineMode attribute settings match the corresponding provider settings that were passed to the iisApp or createApp provider in the command. If the settings do not match, the operation will be blocked. This rule is enabled by default. 2) In Web Deploy versions 1 and 1.1, skips the creation of the application when it already exists on the destination. This rule applies to the createApp and iisApp providers. Note In Web Deploy 2.0, this functionality is performed by the ApplicationExistsRule rule.
|
||
CrossPlatformRule (Cross Platform Rule) [0.50] |
Handles issues with synchronizing between 32 and 64 bit platforms. Adds ASP.NET preconditions and bitness preconditions, and sets application pool configurations based on the ASP.NET script maps that it finds. If an application pool is being moved, the application pool's Enable32BitAppOnWin64 attribute is set to true. The CrossPlatformRule rule applies to the metaKey, webServer, and webServer60 providers. For more information about sync operations from a 32–bit server to a 64–bit server, see Synchronizing from 32–bit to 64–bit. This rule is enabled by default. |
||
DependencyCheckAppPoolExists (Dependency Check AppPool Exists Rule) [0.50] |
Issues an error if an application pool that is being used on the source server does not exist on the destination server, or if the application pool that is being used has not been included in the source specified for the sync operation. This rule is enabled by default. |
||
DependencyCheckFailOnError (Stop Sync Operation on Errors Rule) [0.90] |
Stops a sync operation if one or more dependency check rules flags an Error. This rule and the DependencyCheckFailOnWarning rule are processed after all other rules. This rule is enabled by default. |
||
DependencyCheckFailOnWarning (Stop Sync Operation on Warnings Rule) [0.90] |
Stops a sync operation if one or more dependency check rules has produced either a Warning or an Error. This rule and the DependencyCheckFailOnError rule are processed after all other rules. This rule is disabled by default. |
||
DependencyCheckInUse (Dependency Check In Use Rule) [0.50] |
Issues a warning if a feature on the source server is either not installed on the destination server or not supported on IIS 7. This rule only applies to sync operations in which the destination server is IIS 7. If the following features are installed on the source server, this rule checks whether they are installed on the destination server: ASP, ASP.NET 2.0, Anonymous authentication, Basic authentication, CGI, Digest authentication, dynamic compression, FTP Server, HTTP Redirect, internet Protocol security (IPsec), ISAPI extensions, ISAPI filters, server-side includes (SSI), static compression, and Windows authentication. For ASP.NET, the rule issues a warning if the version on the source server is not installed on the destination server. If WebDAV, Front Page Server Extensions, or .NET Passport authentication are installed on the source server, this rule will report that these features are not supported on IIS 7. |
||
DoNotDeleteRule (Do Not Delete Content Rule) [0.50] |
In a sync operation, blocks deletions of files on the destination computer that do not exist on the source computer. This rule applies to the contentPath, dirPath, and filePath providers. This rule is disabled by default. |
||
EnvironmentVariableNormalize (Environment Variable Rule) [0.20] |
Normalizes environment variables or paths that contain environment variables to a standard form before they are compared. This rule enables the variables %windir%, %program files%, and %inetpub% to be considered the equivalent of their corresponding Windows, Program Files, or inetpub directory path strings. This rule is enabled by default. |
||
IgnoreFileLastWriteTime (Ignore File Last Write Time Rule) [0.60] |
When the useCheckSum operation setting is used in a command, the IgnoreFileLastWriteTime rule ignores the last write time of files and compares them based on their checksums. This rule is enabled by default. If you use the useCheckSum operation setting and disable the IgnoreFileLastWriteTime rule, both last write time and checksum will be used in file comparisons. If useCheckSum is not present in the command, checksums will not be calculated, and the IgnoreFileLastWriteTime rule setting will be ignored. The IgnoreFileLastWriteTime rule is useful if you are deploying files between different time zones and the write time of the files can be safely ignored. This can be especially useful if you have hundreds of files whose only difference is their time stamp. |
||
IISConfigFrom64To32 (IIS Configuration from 64-bit to 32-bit Rule) [0.50] |
Prevents synchronization of IIS configuration from a 64-bit source to a 32-bit destination. When this rule is enabled, the following providers are blocked: appHostConfig, appHostSchema, appPoolConfig, comObject64, machineConfig64, metaKey, regKey, regValue, rootWebConfig64, webServer, webServer60. This rule is enabled by default. |
||
MetakeyToIIS6 (Metakey from IIS 7 to IIS 6 Rule) [0.50] |
Prevents the use of the metaKey provider to synchronize IIS metabase configuration from IIS 7 to previous versions of IIS. This rule is enabled by default. Disabling this rule is not recommended. |
||
Parameterization (Parameterization Rule) [0.30] |
Supports parameters that are declared and set by using the -declareParam and -setParam operation settings. This rule is for infrastructure support and is not intended to be used directly. This rule is enabled by default and is processed before all other rules. |
||
SchemaSection (Schema and Section Handling Rule) [0.50] |
Blocks adding, updating and deleting of schema and section definitions that affect the configuration system. This rule is enabled by default. This rule can be configured. For more information, see Configuring the Schema and Section Handling Rule. |
||
SkipInvalidSource (Skip Invalid Source Rule) [0.50] |
Skips the synchronization of data from a provider if the source of the data cannot be found (for example, you use the appHostConfig provider and the applicationHost.config file cannot be found, or you use the regKey provider and the registry key that you have specified does not exist). If the rule is not enabled and a source is invalid, the operation will fail. This rule is enabled by default. |
||
SkipNewerFilesRule (Skip Overwriting Newer Files Rule) [0.50] |
Skips updates to files that have a more recent write time. This rule is disabled by default. |
||
SkipUNC (Skip UNC Rule) [0.50] |
Prevents UNC paths from being synchronized. For example, if a source Web site points to a UNC path, the UNC path will not be copied to the destination. This rule is enabled by default. |
||
SyncGeneral (Sync General Rule) [0.50] |
Implements file synchronization. This rule is enabled by default. This rule is for infrastructure support and is not intended to be used directly. |
||
SyncXP (Sync XP Rule) [0.50] |
When synchronizing from IIS 5.1 (the Windows XP version of IIS) to IIS 6.0 or IIS 7, prevents the deletion of certain metabase properties that exist on IIS 6.0 and IIS 7 but not on IIS 5.1. These properties include AppPoolId, IIs5IsolationModeEnabled, DontLog, TraceUriPrefix, SSIExecDisable, AccessSSLFlags, WebSvcExtRestrictionList, ApplicationDependencies, and RedirectHeaders. Because IIS 5.1 does not have an AppPools metabase node, this rule also prevents the AppPools node from being deleted from IIS 6.0 and IIS 7. This rule is enabled by default and should not be disabled. |
||
UrlScanSkipIncompat (URLScan Skip Incompatibility Rule) [0.50] |
When using the urlScanConfig provider to synchronize URLScan settings with request filtering settings, prevents the contents of the requestFiltering/hiddenSegments element from being deleted from the destination configuration file. This rule is enabled by default. |
||
WarnForEncryptedDataRule (Warn for Encrypted Data Rule) [0.50] |
Checks for encrypted data or for a <configProtectedData> section in the Web.config file. If the encrypted data is found in the file during a synchronization operation and the rule is enabled, Web Deploy issues a warning, but the operation proceeds. This rule is not enabled by default. Note This rule is available only in Web Deploy versions later than 1.1. If all versions of Web Deploy in your environment are later than 1.1, it is strongly recommended that you enable this rule.
|
||
XpIsapis (XP ISAPI Cleanup Rule) [0.50] |
Prevents sspifilt.dll, pwsdata.dll, and md5filt.dll ISAPI filters from being moved from IIS 5 to later versions of IIS. These filters will not run on later versions of IIS. This rule is enabled by default. Warning Disabling this rule may cause loss of request processing functionality.
|
.gif)
WarningControlling Web Deploy rules with command line switches
Web Deploy operation settings (command line switches) can be used to control how you apply Web Deploy rules, or to skip or replace objects in an operation. For example, you can use the -enableRule and -disableRule operation settings to explicitly enable or disable a rule for an operation.
The following table briefly lists operation settings that apply to rules.
| Operation Setting | Description |
|---|---|
-enableRule:<ruleName>,<ruleName >... |
Enables a specified rule or rules. For more information about -enableRule, see Web Deploy Operation Settings. |
-disableRule:<ruleName>,<ruleName >... |
Disables a specified rule or rules. For more information about -disableRule, see Web Deploy Operation Settings. |
-replace:<replaceArguments> |
Specifies an object match and replace rule. For more information about the values for <replaceArguments>, see Web Deploy Operation Settings. |
-skip:<skipArguments> |
Specifies an object to skip in an operation. For more information about the values for <skipArguments>, see Web Deploy Operation Settings. |
Custom rules
You can add your own rules to the Msdeploy.exe.configsettings configuration file or create custom rules that are variations of existing rules. Custom rules can be a convenient way of avoiding repeated use of the -skip operation setting. For example, the first of the following two rules causes the application pool temp directory to be skipped by default. The second rule example replaces one IP address binding with another.
1. <rule name="SkipLockedFilesRule" type="Microsoft.Web.Deployment.DeploymentSkipRule" objectName="contentPath" absolutePath="c:\\inetpub\\temp\\apppools" isDefault="true" />
2. <rule name="ReplaceIPAddressInBinding" type="Microsoft.Web.Deployment.DeploymentReplaceRule" isDefault="true" objectName="binding" targetAttributeName="bindingInformation" match="x\.x\.x\.x" replace="y.y.y.y" />
Ensuring the availability of custom rules
There are two ways to ensure the availability of custom rule DLLs to Web Deploy operations.
Place the DLL in a folder called "Extensibility" inside the folder or share that contains the Web Deploy program files. If you run Web Deploy from a share, all sync operations will be able to use the custom rule as long as the Extensibility folder that has your DLL exists on the share.
You can add your assembly to the Global Assembly Cache (GAC), and add a registry key that specifies the fully qualified name of the DLL. The registry key should appear as a string (REG_SZ) value under the registry node HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\IIS Extensions\MSDeploy\1\Extensibility. If you choose this method, each DLL must be registered on every server that uses the DLL in a sync operation.
Warning
If you have Msdeploy.exe.configsettings, Msdepsvc.exe.configsettings, or Wmsvc.exe.configsettings files in your environment, you must make sure that these files (and any rules in them) are identical on both the source and destination computers before you perform a sync operation. If you change the Msdepsvc.exe.configsettings file while the Web Deployment Agent Service (MsDepSvc) is running, the change will not be detected, and you must stop and start the service before the change will take effect. On Windows XP or later versions of Windows, you can stop the service by typing net stop msdepsvc at a command prompt, and start it by typing net start msdepsvc.
Example Usages
1) Include UNC content in a sync operation between two IIS 7 Web servers by disabling the default rule that skips all UNC content.
msdeploy -verb:sync -source:webServer -dest:webServer,computerName=Server2 -disableRule:SkipUNC
2) Use the -replace operation setting in a sync operation to change the virtual directory content of a Web site from c:\content to c:\content2.
msdeploy -verb:sync -source:archivedir=c:\TestSiteArchive -dest:appHostConfig=TestSite -replace:objectName=virtualDirectory,match="c:\\content\\(.*)",replace="c:\content2\$1"
See Also
Web Deploy Command Line Reference
Web Deploy Command Line Syntax