Merging XML in Feature and Package Manifests

 

Features and packages are defined by XML manifest files. These packaged manifests are a combination of data generated from designers and custom XML entered in the manifest template by users. At packaging time, Visual Studio merges the custom XML statements with the designer-provided XML to form the packaged XML manifest file. Similar elements, with the exceptions noted later in Merge Exceptions, are merged to avoid XML validation errors after you deploy the files to SharePoint, and to make the manifest files smaller and more efficient.

You cannot directly modify the packaged manifest files until you disable the feature or package designers. However, you can manually add custom XML elements to the manifest template either through the feature and package designers or the XML editor. For more information, see How to: Customize a SharePoint Feature and How to: Customize a SharePoint Solution Package.

When combining custom elements together with designer-provided elements, Visual Studio uses the following process. Visual Studio checks whether each element has a unique key value. If an element has no unique key value, it is appended to the packaged manifest file. Similarly, elements that have multiple keys cannot be merged. Therefore, they are appended to the manifest file.

If an element has a unique key, Visual Studio compares the values of the designer and custom keys. If the values match, they merge into a single value. If the values differ, the designer key value is discarded and the custom key value is used. Collections are also merged. For example, if the designer-generated XML and the custom XML both contain an Assemblies collection, the packaged manifest contains only one Assemblies collection.

Visual Studio merges most designer XML elements together with similar custom XML elements as long as they have a single, unique identifying attribute. However, some elements lack the unique identifier required for XML merging. These elements are known as merge exceptions. In these cases, Visual Studio does not merge the custom XML elements together with the designer-provided XML elements, but instead appends them to the packaged manifest file.

Following is a list of merge exceptions for feature and package XML manifest files.

DesignerXML Element
Feature designerActivationDependency
Feature designerUpgradeAction
Package designerSafeControl
Package designerCodeAccessSecurity

The following table is a list of all feature manifest elements that can be merged and their unique key that is used for matching.

Element NameUnique Key
Feature (all attributes)Attribute Name (Each attribute name of the Feature element is a unique key.)
ElementFileLocation
ElementManifests/ElementManifestLocation
Properties/PropertyKey
CustomUpgradeActionName
CustomUpgradeActionParameterName
System_CAPS_ICON_note.jpg Note


Because the only way to modify the CustomUpgradeAction element is in the custom XML editor, the effect of not merging is low.

The following table is a list of all package manifest elements that can be merged and their unique key that is used for matching.

Element NameUnique Key
Solution (all attributes)Attribute Name (Each attribute name of the Solution element is a unique key.)
ApplicationResourceFiles/ApplicationResourceFileLocation
Assemblies/AssemblyLocation
ClassResources/ClassResourceLocation
DwpFiles/DwpFileLocation
FeatureManifests/FeatureManifestLocation
Resources/ResourceLocation
RootFiles/RootFileLocation
SiteDefinitionManifests/SiteDefinitionManifestLocation
WebTempFileLocation
TemplateFiles/TemplateFileLocation
SolutionDependencySolutionID

Some manifest elements, such as ApplicationResourceFile and DwpFiles, specify a location that includes a file name. However, adding a file name entry to the manifest template does not add the underlying file to the package. You must add the file to the project to include it in the package and set its Deployment Type property accordingly.

Packaging and Deploying SharePoint Solutions
Building and Debugging SharePoint Solutions

Show: