Configuring the Schema and Section Handling Rule
Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista, Windows XP
The Schema and Section Handling (SchemaSection) Rule blocks schema files and ApplicationHost.config and Machine.config section group definitions from being added, updated or deleted. The SchemaSection rule applies only to IIS 7 and later versions. This rule is enabled by default, but can be configured.
Although it is possible to disable the rule by using the -disableRule:SchemaSection operation setting, this is not recommended. If you disable the SchemaSection rule, all schema files and section definitions will be synchronized. While the synchronization itself might not cause errors, the result can create the false impression that certain programs are installed on the destination computer even when they are not. Synchronizing all schema files can also allow configuration settings to be made that have no meaning if the related programs are not installed. If you have programs that use custom schema files, the Web Deployment Tool will not install the programs for you, nor synchronize their installation.
You can use schema lists and section lists instead to more precisely control the synchronization of section definitions and schema. This topic shows you how to do this.
Synchronizing Schema Files by using <schemaList>
When you synchronize schema files from a source to a destination, the SchemaSection rule will, by default, prevent the copying of new schema files from the source to the destination computer. If you want to override this behavior, you must create a <schemaList> section in the Msdeploy.exe.configsettings file that will let you synchronize specific schema files. A simple example follows.
<schemaList>
<add name="mySchema.xml" />
</schemaList>
The name value is a regular expression that specifies the location of a schema file. For more information about regular expressions, see Regular Expressions.
Synchronizing Section Groups by using <sectionList>
By default, the SchemaSection rule will prevent the synchronization of section groups that are defined in the source computer ApplicationHost.config or Machine.config files, but not defined in the corresponding destination computer configuration files. If you want to override this behavior, you must create a <sectionList> section in the Msdeploy.exe.configsettings file that will let you synchronize the section groups that do not exist on the destination. A simple example follows.
<sectionList>
<delete name="system.serviceModel"/>
<add name="mySchemaDefinition"/>
</sectionList>
The name value is a regular expression that specifies the location of a schema file. For more information about regular expressions, see Regular Expressions.
When you synchronize new section groups by creating a <sectionList> in the Msdeploy.exe.configsettings file, two synchronization operations will be required to update the configuration correctly. The first synchronization will create the new section groups on the destination; the second synchronization will populate the newly created section groups with data.
Important
Before configuration can be added to the new sections in the destination ApplicationHost.config file, the schema file for the new sections must also exist on the destination.
Tip
If you want to synchronize all section groups, put <add name="." /> in the section list. The regular expression "." specifies all names.
WCF Section Definitions
By default, the SchemaSection rule allows synchronization of the section definitions for the Windows Communication Foundation (WCF) elements <system.serviceModel> and <system.serviceModel/serviceHostingEnvironment>. These elements appear in the root Web.config file. Because WCF writes to these root Web.config sections, the SchemaSection rule synchronizes all WCF section definitions that begin with <system.ServiceModel>. To override this default behavior, see the relevant example in the Example Usages section. For more information about the WCF Configuration Schema, see Windows Communication Foundation Configuration Schema.
Synchronization Handling When Schema or Section Groups Exist Only on the Destination
If the destination has a section definition that does not exist on the source, and the destination configuration file has no values specified for the definition, the section definition on the destination will be removed. However, if the destination configuration has a non-empty section that does not exist on the source, the destination section will be preserved in the sync operation.
Example Usages
1) Leave the SchemaSection rule enabled, but override it to allow the Rewrite_schema.xml file to be synchronized.
<configuration>
<rules>
<rule name="SchemaSection" enabled="true" >
<schemaList>
<add name="C:\CustomSchemas\rewrite_schema.xml" />
</schemaList>
</rule>
</rules>
</configuration>
2) Leave the SchemaSection rule enabled, but allow both a new <rewrite> section and its corresponding schema file Rewrite_schema.xml to be added to the destination. The new schema file and the section definitions must be present on the destination before configuration data can be written to the new sections. A second sync operation will be required to synchronize the configuration data itself.
<configuration>
<rules>
<rule name="SchemaSection" enabled="true" >
<sectionList>
<add name="rewrite"/>
</sectionList>
<schemaList>
<add name="rewrite_schema.xml" />
</schemaList>
</rule>
</rules>
</configuration>
3) Leave the SchemaSection rule enabled, but use a delete element to override the built-in exception for the <system.serviceModel> section definition. The <system.serviceModel> section definition will not be synchronized.
<configuration>
<rules>
<rule name="SchemaSection" enabled="true">
<sectionList>
<delete name="system.serviceModel"/>
</sectionList>
</rule>
</rules>
</configuration>
4) Override the SchemaSection rule by creating specifying the ".*" regular expression for both section definitions and schema. All schemas and section definitions will be synchronized. This is the same as specifying -disableRule:SchemaSection in a Web Deploy command.
<configuration>
<rules>
<rule name="SchemaSection" enabled="true" >
<sectionList>
<add name=".*"/>
</sectionList>
<schemaList>
<add name=".*" />
</schemaList>
</rule>
</rules>
</configuration>