Installing add-ons

EPiServer uses NuGet for installing add-ons in a standard package format. You can install add-ons from Visual Studio or the Add-on user interface. Configure your approach in the configuration file.

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

<episerver.packaging installationMode="CODE">

Values for installationMode are Code and UI. You should install, upgrade, manage, and uninstall add-ons from either Visual Studio or the UI but not from 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 some operations (like disable and uninstall) may be unavailable.

Before installing add-ons from Visual Studio

1. Set installationMode to Code:
   

   <episerver.packaging installationMode="Code">

2. If  installationMode was set to UI, run the cmdlet Convert-EPiAddons in the Package Manager Console, which converts existing add-ons installed via UI to Visual Studio format.
3. Add http://nuget.episerver.com as a NuGet source.
4. 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.

Important! 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 UI.

• Set installationMode to UI:

  <episerver.packaging installationMode="UI">

Installing 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:

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

Adding an uploaded package to a temporary repository

EPiServer adds uploaded packages to a temporary repository, located in the temporary directory designated by the operating system. To change the directory, change the value of the packagesTemporaryFolder attribute in the episerver.packaging element:

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

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. The package source repositories are the following:

• The temporary repository
• The site local repository
• EPiServer central repository

Creating additional repositories

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

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

Installed add-ons are registered in the file in the site root. The system 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.

Adding packages to the local repository

Successfully installed packages are added to the site local repository. By default, the repository is located in the site directory C:\EPiServer\<SiteName>\wwwroot\modules. This directory is set up with the correct access rights when the EPiServer Framework is installed via EPiServer Deployment Center.

To configure a site to use a repository at another location, change the value of the repositoryPath attribute on the episerver.packaging element:

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

Make sure that the web application has write access to that directory.

Copying add-on assemblies to the probing path

Add-on assemblies compatible with the current framework version are copied to the probing path directory. The probing path, by default, is the dirmodulesbin directory under C:\EPiServer\<SiteName>\wwwroot\.

The probing path directory must be available at this location and can be defined in the probingPath attribute in the configuration/episerver.framework/scanAssembly element. You should configure the same path in the privatePath attribute of probing element.

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

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

Completing the installation

After you install add-on packages, the results of each package's installation are displayed, together with information on whether a restart of the site is needed (if ASP.NET did not automatically restart it). Site restart is required to load and scan new assemblies and initialize installed add-ons.

Updating add-ons

If updates are available for installed add-ons, the Updates tab informs you about this. From here, you can update installed add-ons. When upgrading an add-on, the old version is uninstalled and the new version is installed. Any related add-ons (dependencies as well as dependents) that need upgrading are upgraded.

The process for updating installed add-ons is similar to regular installation and uninstallation. Refer to these sections for detailed information.

Disabling add-ons

If a site has been upgraded and incompatible add-ons are installed, the site might not start, blocking the possibility to upgrade or uninstall the add-on. You can disable add-ons installed via the User Interface to make sure they do not block the user interface. In the site's configuration file, disable the add-on causing the error message. For example, this section disables EPiServer.Cms.AddOns.Blocks:

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

Uninstalling add-ons

You can view installed add-ons under the Installed tab. From here, you can uninstall them. Exception: System addons (for example, the add-on management system) cannot be uninstalled, only upgraded.

During uninstallation, add-on files and the corresponding Shell module folder are removed, and assemblies are deleted from the probing path directory. You must restart your site to complete the uninstallation procedure and unload add-on assemblies from the application domain.

Related topics

Last updated: Feb 23, 2015