The next component that may be included in the DNN 5 manifest is the Config component installer which in it's basic form follows this example (portion taken from the Telerik assembly extension manifest):

<component type="Config">

  <config>

    <configFile>web.config</configFile>

    <install>

      <configuration>

        <nodes>

          <node path="/configuration/system.web/httpHandlers" action="update" key="path" collision="overwrite">

          <add verb="*" path="Telerik.Web.UI.WebResource.axd" validate="false"

          type="Telerik.Web.UI.WebResource, Telerik.Web.UI" />

          </node>

        </nodes>

      </configuration>

    </install>

    <uninstall>

      <configuration>

        <nodes />

      </configuration>

    </uninstall>

  </config>

</component>

Under the "covers", the config component makes use of the DotNetNuke.Services.Installer.XMLMerge class to perform XmlSplicing of any configuration file. Documentation of the capabilities and xml markup for XmlMerge will be included as a separate entry in this Wiki.

Although all core provider and module extension manifests which I examined wrote the root Config component node as <component type="Config"> , an examination of the installer code reveals that other attributes which may be applied to any component node include:

installOrder - integer specifying order in which component will be processed during install

uninstallOrder -integer specifying order in which component will be processed during uninstall

version - version string of form xx.xx.xx or xx.xx.xx.xx specifying component version(br)

Specific to the config component node, the following attributes may be applied:

fileName - specifies an external file as the source of configuration modifications applied during extension install. If the fileName attribute is applied, the entire <config> . . . </config> section should not be present. If it is present, it will be ignored. When an external file is specified as the source of the configuration modifications, the target configuration filepath must be specified in the external file. See the XML Merge Wiki entry for details.

uninstallFileName - specifies an external file for the source of configuration modifications applied during extension uninstall. If the uninstallFileName attribute but not the a fileName attribute is applied, an <uninstall> . . . </uninstall> section with an empty <nodes> collection must be present.

External configuration source files must contain propoperly structured xml required by the XmlMerge class, namely:

<configuration>

  <nodes configfile="targetFilePath">

    <node>

      . . .

    </node>

  </nodes>

</configuration>

Note how the root relative target filepath (usually "web.config") is specified in the configfile attribute of the <nodes> element.

Looking at our first example, we see that the <configFile> . . . </configFile> node allows specification of the root relative path to the target config file to be modified. In most cases this will be simply web.config but could just as easily be a config file located anywhere within the web application.

Next, notice that when an external source file for the configuration modifications performed during install of the extension is not specified, the manifest's Config component section must include both <install> . . .</install> and <uninstall> . . . </uninstall> sections with the install modifications being applied during extension installation and the uninstall modifications being applied during extension uninstallation. Note that it is required for both sections and their first child node <configuration> . . . </configuration> and an (empty) <nodes /> element to be included in the xml markup even if there will be no modification made during the respective install or uninstall extension phase. As I found when writing my first config component which included no <uninstall> . . .</uninstall> section, a non-specific null reference error will be thrown as the extension manifest is read.

Within the <install> . . . </install>> or <uninstall> . . . </uninstall> sections, next will come a nested <configuration><nodes> . . . </nodes></configuration> node containing a collection of <node> elements. Each <node> element and its contained modification must follow the specifications for the Xml Merge class.

Samples

Here are several examples of config components taken from core module and provider extension manifests included in the DotNetNuke framework packages:

Example 1 - FilebasedCachingProvider

<component type="Config">

  <config>

    <configFile>web.config</configFile>

    <install>

      <configuration>

        <nodes>

          <node path="/configuration/dotnetnuke/caching/providers"

                action="update" key="name" collision="overwrite">

          <add name="FileBasedCachingProvider"

               type="DotNetNuke.Services.Cache.FileBasedCachingProvider.FBCachingProvider,

                     DotNetNuke.Caching.FileBasedCachingProvider"

               providerPath="~\Providers\CachingProviders\FileBasedCachingProvider\" />

          </node>

        </nodes>

      </configuration>

    </install>

    <uninstall>

      <configuration>

        <nodes>

          <node path="/configuration/dotnetnuke/caching/providers/

                      add[@name='FileBasedCachingProvider']" 

                action="remove" />

        </nodes>

      </configuration>

    </uninstall>

  </config>

</component>

Example 2 - TelerikEditorProvider

<component type="Config">

  <config>

    <configFile>web.config</configFile>

    <install>

      <configuration>

        <nodes>

          <node path="/configuration/dotnetnuke/htmlEditor/providers"

                action="update" key="name" collision="save">

            <add name="TelerikEditorProvider"

               type="DotNetNuke.HtmlEditor.TelerikEditorProvider.EditorProvider, 

                      DotNetNuke.HtmlEditor.TelerikEditorProvider"

               providerPath="~/Providers/HtmlEditorProviders/Telerik/"

               toolsFile="~/Providers/HtmlEditorProviders/Telerik/Config/ToolsDefault.xml"

               configFile="~/Providers/HtmlEditorProviders/Telerik/Config/ConfigDefault.xml"

               FilterHostExtensions="True" />

          </node>

          <node path="/configuration/system.webServer/handlers" action="update" key="name" collision="overwrite">

            <add name="HtmTemplateFileHandler" verb="*" path="*.htmtemplate"

               type="DotNetNuke.HtmlEditor.TelerikEditorProvider.HtmTemplateFileHandler, 

                    DotNetNuke.HtmlEditor.TelerikEditorProvider" preCondition="integratedMode" />

          </node>

          <node path="/configuration/system.web/httpHandlers" action="update" key="name" collision="overwrite">

            <add verb="*" path="*.htmtemplate"

              type="DotNetNuke.HtmlEditor.TelerikEditorProvider.HtmTemplateFileHandler, 

                    DotNetNuke.HtmlEditor.TelerikEditorProvider" />

          </node>

        </nodes>

      </configuration>

    </install>

    <uninstall>

      <configuration>

        <nodes>

          <node path="/configuration/dotnetnuke/htmlEditor/providers/add[@name='TelerikEditorProvider']" action="remove" />

          <node path="/configuration/system.webServer/handlers/add[@name='HtmTemplateFileHandler']" action="remove" />

          <node path="/configuration/system.web/httpHandlers/

                    add[@type='DotNetNuke.HtmlEditor.TelerikEditorProvider.HtmTemplateFileHandler, 

                        DotNetNuke.HtmlEditor.TelerikEditorProvider']" 

                action="remove" />

        </nodes>

      </configuration>

    </uninstall>

  </config>

</component>

References

• XmlMerge - What Is It? Blog post by Charles Nurse
• Leveraging XML Merge Scripts Blog post by Joe Brinkman