Plugin filtering

Tag matching enables the inclusion or exclusion of plugins based on the tags defined in their sitecore.plugin.manifest file. These tags are provided by the author of the plugin. A single tag can match zero or more plugins.

Syntax

When matching tags, you can include or exclude based on the tag name:

Syntax details

The value after the + or - character can be any alphanumeric string or the period character (.).  If multiple plugins have the same tag, the match applies to all plugins. Filters are not case sensitive (so MyTag is the same as mytag).

Example: remove plugin by tag

In this example, you edit the sitecorehost.xml file to exclude any plugin that has the tag TagB. All plugins are loaded except the ones tagged with TagB:

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>-TagB</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

Example: include plugin by tag

In this example, you edit the sitecorehost.xml file to include only plugins that has the tag TagA. No other plugins are loaded except ones tagged with TagA:

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>+TagA</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

Plugin matching allows you to be more precise about which plugins are matched. By using the plugin matching syntax you can match by the ID and the version of a plugin. A plugin match can only match zero or one plugin.

Syntax

When you match plugins, you can include or exclude based on the plugin ID and ,optionally, on the plugin version.

Syntax details

The value after the + or - character can be any alphanumeric string or the period character (.) .Filters are not case sensitive (so MyPluginId is the same as mypluginid).

Example: exclude plugin by ID

In this example, you edit the sitecorehost.xml file to exclude any plugin that has the ID (name) PluginB. All plugins are loaded except the ones whose names match PluginB:

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>-@PluginB</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

Example: include plugin by ID

In this example, you  edit the sitecorehost.xml file to include only plugins that have the ID PluginOne. No other plugins are loaded except ones with the ID PluginOne:

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>+@PluginOne</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

Example: exclude plugin by ID and version

In this example, you edit the sitecorehost.xml file to exclude a plugin that has the ID PluginOne and the version 1.0.0:

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>-@PluginOne:1.0.0</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

You can supply any number of filters in configuration as separate keys. They are joined when the filter is applied. The following two configurations will result in the same filter:

<Sitecore>
    <!-- Single Entry -->
    <Plugins>
        <Filters>
            <Defaults>+TagA +TagB</Defaults>
        </Filters>
    </Plugins>
    <!-- Multiple Entries -->
    <Plugins>
        <Filters>
            <TagA>+TagA</TagA>
            <TagB>+TagB</TagB>
        </Filters>
    </Plugins>
</Sitecore>

By providing separate keys for each part of the filter it makes it easier to override the configuration at the command line or through environment sitecorehost files.

In the first example (above), you can only patch the configuration key Plugins:Filters:Defaults.

In the second example (below), you can provide a sitecorehost.development.xml file with a patched configuration section:

<Sitecore xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <Plugins>
        <Filters>
            <TagB>
                <patch:delete />
            </TagB>
        </Filters>
    </Plugins>
</Sitecore>

If you remove one or more plugins, but other plugins depend on them, this will cause an error. This can happen when a custom plugin filter is applied. For example, if you change the sitecorehost.xml to remove PluginA, which is tagged with TagA :

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>-TagA</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

However, if another plugin (PluginB) has a dependency on it, then when you run the Sitecore Host application it throws an error:

Unhandled Exception: Sitecore.Framework.Runtime.Plugins.MissingPluginDependencyException: Plugin dependency could not be found.
Loading plugin PluginB : PluginB -> PluginA
Missing dependency: PluginA

To resolve the issue, you can exclude all dependent plugins:

<Sitecore>
    <Plugins>
        <Filters>
            <Defaults>-TagA -TagB</Defaults>
        </Filters>
    </Plugins>
</Sitecore>

When you invoke the application,  you can pass a command line argument to set the plugin filter. You can add a configuration override after the application is invoked by providing the path to the config section and the new value(s). For example:

--Plugins:Filters:Defaults '-TagB -TagA'