Installing add-ons

Introduction

EPiServer uses Nuget to handle add-ons in a standard package format. You can install add-ons directly from Visual Studio or via the Add-on user interface. Configure your approach via this configuration file property:

<episerver.packaging installationMode="CODE">

Possible installationMode values are Code and UI. The recommendation is to manage add-ons from either Visual Studio or the UI. A hybrid scenario, where you install some add-ons from the UI and others from Visual Studio, may not work as expected.

When you install an add-on from Visual Studio, it appears in the add-on UI, but all operations (such as disable and uninstall) are unavailable. You should perform upgrades/installs/uninstalls of add-ons through Visual Studio.

Installing add-ons from Visual Studio

In Visual Studio, you manage add-ons in the same way you manage other Nuget packages. Complete these steps to install add-ons from Visual Studio.

1. Set installationMode to Code:
   

   <episerver.packaging installationMode="Code">

2. If you are upgrading from a site installed by EPiServer Deployment Center, make sure protected modules have been moved into the "modules/_protected"-folder. You can run the cmdlet  'Move-EPiServerProtectedModules' in the Package Manager Console to verify this.
3. Make sure nuget.episerver.com is added as a Nuget source.

If the three above conditions are met, you should be able to install add-ons via Visual Studio.

Note: If add-ons are already installed via the user interface, the recommendation is to uninstall the add-ons first, since the directory structure is not identical. For example, when installing from the user interface, assemblies are placed in modulesbin rather than bin. Also, add-ons installed via Visual Studio may use zip files to package UI resources. Be aware that some add-ons may remove stored settings when uninstalling. If you need to keep these settings, manually remove the add-on folder from disk and from the modulesbin folder before installing via Visual Studio.

Installing add-ons from the user interface

This section describes managing Add-ons from the UI. Make sure installationMode is set to UI:

<episerver.packaging installationMode="UI">

To install add-ons via the Add-ons user interface, you must be a member of the PackagingAdmins user group and have access to the EPiServer UI.

Installing packages from the EPiServer central repository

1. In the EPiServer UI, go to the global menu and select Add-ons.
2. Select an add-on.
3. The system validates the package, tries to resolve package dependents and dependencies, and installs the add-on if possible.

Installing uploaded packages

The installation completes these steps:

1. Packages are added to a temporary repository, where no validation of dependencies is performed.
2. An attempt to resolve dependents and dependencies then install these packages is performed from the temporary repository combined with the other repositories.

After being installed to the repository, a package can be instantiated to any number of applications.

Validation of packages

Uploaded files and selected add-ons are validated, verifying that they are valid Nuget packages marked with proper module tags, EPiServerModulePackage or EPiServerPublicModulePackage.

Adding an uploaded package to a temporary repository

Uploaded packages are added to a temporary repository, by default, the temporary directory designated by the operating system. To use a different directory, change the value of the packagesTemporaryFolder attribute in the episerver.packaging element:

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

The temporary repository is used with the virtual packages, representing assemblies available on the site and the local repository, in an attempot to resolve all dependencies before installation. If they can be resolved, packages are installed to the current site.

The package source repositories are:

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

Creating additional repositories

You can add repositories in the configuration file. See the following example:

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

All installed add-ons are registered in the file within the site root. The system copies all supported files to the corresponding add-on folder in the ~/modules/ directory. Refer to 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's local repository, by default C:\EPiServer\<SiteName>\wwwroot\modules. This directory is set up with correct access rights when EPiServer Framework is installed via EPiServer Deployment Center. If you want a site to use a repository at another location, change the repositoryPath attribute value on the episerver.packaging element:

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

Verify that the web application has write permission for 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 default probing path is C:\EPiServer\<SiteName>\wwwroot\dirmodulesbin. 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. The same path should be configured in the privatePath attribute of probing element as well:

<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, installation results are displayed, along with an indication if a site restart is needed (if ASP.NET did not automatically restart it). A site restart is required to load and scan new assemblies and initialize installed add-ons.

Updating add-ons

To see if updates are available for installed add-ons, look under the Updates tab. From here, you can update installed add-ons. When updating an add-on, the old version is uninstalled, and the new version is installed. Any related add-ons (dependencies as well as dependents) are upgraded as needed. The process of updating add-ons is similar to installation and uninstallation. Refer to these sections for information.

Uninstalling add-ons

Installed add-ons appear under the Installed tab. From here, you can uninstall them. 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 the site to complete the uninstallation and unload add-on assemblies from the application domain.

System add-ons (for example, the add-on management system) are an exception: they cannot be uninstalled, only upgraded.

Related information

Last updated: Nov 28, 2014