Area: Optimizely CMS

ARCHIVED This content is retired and no longer maintained. See the latest version here.

Installing add-ons

This topic describes how to install, update and disable add-ons. Episerver uses NuGet for handling add-ons in a standard package format. You can install add-ons directly from Visual Studio or via the Add-on user interface.

Note: For Azure environments, install add-on modules only through Visual Studio (and not from the Episerver Add-ons interface).

Configuring installation options

Configure your choice of installation approach in the configuration file as described below.

<episerver.packaging installationMode="MODE">

Values for installationMode are Code or UI. You should install, upgrade, manage, and uninstall add-ons from either Visual Studio or the UI and not both, because an add-on may not work as expected. For example, if you install an add-on from Visual Studio, it appears in the add-on UI, but operations (like disable and uninstall) may be unavailable.

Before installing add-ons from Visual Studio

Set installationMode to Code:

<episerver.packaging installationMode="Code">

If installationMode was set to UI, run the cmdlet Convert-EPiAddons in the Package Manager Console. This converts existing add-ons installed via the user interface to Visual Studio format.
Add http://nuget.episerver.com as a NuGet source.
Install and upgrade add-ons as normal via Visual Studio.

The Repository.config file

The modules/_protected folder contains a repository.config file, which is created during add-on system initialization. If the server has been hardened, IIS does not have write access to the _protected folder, and the site does not launch (you get an access denied message). To resolve the problem, give IIS_IUSRS modify rights to the _protected folder.

Each web server in a load-balanced environment has a repository.config file. The file contains a unique repository GUID. The add-on system allows for the execution of custom code when an add-on is installed, updated or about to be uninstalled. The add-on system uses the GUID to verify that the custom code has been executed on all servers. When deploying multiple sites, it is a good idea to copy a generated repository.config file (per machine) as part of the deployment.

Because each server's repository.config file has a unique GUID, do not commit the file to source.

Before installing add-ons from the UI

You can install add-ons from the Add-ons user interface without access to Visual Studio. To install add-on packages, you must be a member of the PackagingAdmins user group and have access to the Episerver user interface.

Set installationMode to UI:

<episerver.packaging installationMode="UI">

Installing add-on packages from the Episerver central repository

In Episerver, select Add-ons in the global menu. From here, you can install any available add-on. Episerver does the following:

Episerver adds packages to a temporary repository.
Episerver tries to resolve dependents, and dependencies, and install the packages to the application from the temporary repository combined with the other repositories.
Episerver validates uploaded files and selected add-ons if they are valid NuGet packages marked with proper module tags: EPiServerModulePackage or EPiServerPublicModulePackage.
After installing a package to the repository, you can instantiate it to any number of applications.

Changing the location of the temporary repository

The following list shows the package source repositories:

Episerver central repository
The temporary repository
The site local repository

To resolve dependencies before installation, Episerver uses the temporary repository in conjunction with the virtual packages, representing available assemblies on the site, and the local repository. By default, the operating system designates the location of the temporary repository directory. To change the directory, change the value of the packagesTemporaryFolder attribute in the episerver.packaging element.

<episerver.packaging packagesTemporaryFolder="...">

Changing the location of the local repository

Episerver sets up the site directory, C:\EPiServer\<SiteName>\wwwroot\modules, with correct access rights when you install Episerver Framework from the Episerver Deployment Center. Episerver adds successfully installed packages to the site local repository. To change the directory, change the value of the repositoryPath attribute on the episerver.packaging element:

<episerver.packaging repositoryPath="C:\EPiServer\Sites\MySite\App_Data\Packages">

Note: make sure that the web application has write access rights for the specified directory.

Adding repositories to the configuration

You can add repositories to the configuration, as shown in the following example:

<episerver.packaging>
  <packageRepositories>
     <add name="Gallery" url="\\server\Your\Packages\Folder" />
  </packageRepositories>
</episerver.packaging>

Note: Installed add-ons are registered in the file in the site root. Episerver copies supported files to the corresponding add-on folder in the ~/modules/ directory. See the description for the episerver.packaging element in Configuring episerver.packaging.

Copying add-on assemblies to the probing path directory

Episerver copies add-on assemblies compatible with the current framework version to the probing path directory, which is located at dirmodulesbin under C:\EPiServer\<SiteName>\wwwroot\. The probing path directory must be available at this location, and you define it in the probingPath attribute in the configuration/episerver.framework/scanAssembly element. You should configure the same path in the privatePath attribute of probing element:

EPiServerFramework.config

XML

<episerver.framework>
    <scanAssembly forceBinFolderScan="true" probingPath="modulesbin" />

...

web.config

XML

<runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
       <probing privatePath="modulesbin" />

...

Completing the installation

After you install add-on packages, installation results appear with information about whether you need to restart the site (if ASP.NET does not automatically restart it). Site restart is required to load and scan new assemblies and initialize installed add-ons.

Updating an add-on

The Updates tabs shows available updates for installed add-ons. When you upgrade an add-on, the old version is uninstalled and the new version is installed. The update process also updates related add-ons (dependencies and dependents).

Disabling an add-on

After upgrade, some add-ons may become incompatible, and the site might not start. You can disable installed add-ons from the user interface so they do not block the user interface. Disable an add-on (such as EPiServer.Cms.AddOns.Blocks in the following example) in the site's configuration file:

XML

  <episerver.framework>
    <scanAssembly>
      <add assembly="*" />
      <remove assembly="EPiServer.Cms.AddOns.Blocks" />
    </scanAssembly>
   <!-- other settings -->
  </episerver.framework>

Uninstalling an add-on

The Installed tab shows installed add-ons. From here, you can uninstall add-ons, except for system add-ons (such as the add-on management system, which cannot be uninstalled; only upgraded). During uninstallation, Episerver removes add-on files and the corresponding Shell module folder, and deletes assemblies from the probing path directory. Episerver restarts the site to complete the uninstallation procedure and unload add-on assemblies from the application domain.