Install Optimizely apps (add-ons)

Optimizely Content Management System (CMS 13) uses NuGet to handle app packages (sometimes called add-ons) in a standard format. Install apps from Visual Studio or through the add-on UI.

📘
Note
For Azure environments, install app modules only through Visual Studio (not from the add-on UI).

Configure installation options

Control whether you install CMS 13 apps through Visual Studio or the UI. Specify the installation mode in your configuration file.

<episerver.packaging installationMode="MODE">

Set installationMode to Code (Visual Studio) or UI. Use one method consistently for installing, upgrading, and uninstalling add-ons. Mixing methods causes unexpected behavior. For example, an app installed from Visual Studio displays in the add-on UI, but disable and uninstall operations are unavailable.

Install apps from Visual Studio

Prepare your environment for Visual Studio-based app installation.

Set installationMode to Code: <episerver.packaging installationMode="Code">.
Run the Convert-EPiAddons cmdlet in the Package Manager Console if you previously set installationMode to UI. The cmdlet converts UI-installed apps to Visual Studio format.
Add https://nuget.episerver.com/feed/packages.svc/ as a NuGet source.
Install and upgrade apps through Visual Studio.

`Repository.config`

The modules/_protected folder contains a repository.config file created during add-on system initialization. If the server is hardened, IIS lacks write access to the _protected folder. The site fails to launch with an Access denied message. Grant IIS_IUSRS modify rights to the _protected folder to resolve this issue.

Each web server in a load-balanced environment has its own repository.config file with a unique GUID. The app system executes custom code when an app is installed, updated, or uninstalled. The system uses the GUID to verify that custom code runs on all servers. Copy the generated repository.config file for each machine as part of multi-site deployments.

Do not commit repository.config to source control because each server requires a unique GUID.

Install apps from the UI

The add-on UI lets you install apps 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 Optimizely UI.

Set installationMode to UI:

<episerver.packaging installationMode="UI">

Install app packages from the central repository

The central repository provides access to all available apps for CMS 13.

In CMS 13, select Add-ons in the global menu. The installation process works as follows:

Add packages to a temporary repository.
Resolve dependencies and install the packages into the application from the temporary repository, combined with other repositories.
Validate uploaded files and selected add-ons as valid NuGet packages marked with the EPiServerModulePackage or EPiServerPublicModulePackage module tags.
Instantiate the package for any number of applications after installing it in the repository.

Change the location of the temporary repository

The following package source repositories are available:

The central repository
The temporary repository
The site local repository

The temporary repository uses virtual packages to resolve dependencies before installation, 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, update the packagesTemporaryFolder attribute in the episerver.packaging element:

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

Change the location of the local repository

CMS configures the site directory, C:\\EPiServer\<SiteName>\\wwwroot\\modules, with correct access rights when you install Optimizely Framework from Deployment Center. Installed packages are added to the local repository. To change the directory, update the repositoryPath attribute on the episerver.packaging element:

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

📘
Note
Ensure the web application has write access rights for the specified directory.

Add repositories to the configuration

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 apps are registered in the file in the site root. Supported files are copied to the corresponding app folder in the ~/modules/ directory. For the episerver.packaging element description, go to episerver.packaging (Legacy) (CMS 11).

Copy app assemblies to the probing path directory

App assemblies compatible with the current framework version are copied to the probing path directory at dirmodulesbin under C:/EPiServer/<SiteName>/wwwroot/. The probing path directory must be available at this location. Define it in the probingPath attribute in the configuration/episerver.framework/scanAssembly element. Configure the same path in the privatePath attribute of the probing element.

EPiServerFramework.config

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

web.config

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

Complete the installation

After you install app packages, the results display whether you must restart the site (if ASP.NET does not automatically restart it). A site restart is required to load and scan assemblies and initialize installed apps.

Update an app

The Updates tab shows available updates for installed apps. When you upgrade an app, the old version is uninstalled, and the replacement is installed. The update process also updates related apps (dependencies and dependents).

Disable an app

After an upgrade, some apps may become incompatible and prevent the site from starting. Disable incompatible apps to restore access to the UI.

Disable an app (such as EPiServer.Cms.AddOns.Blocks in the following example) in the configuration file:

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

Uninstall an app

The Installed tab shows installed apps. Uninstall apps from this tab, except for system apps (such as the management system app, which supports upgrade only). App files and the corresponding Shell module folder are removed during uninstallation, and assemblies are deleted from the probing path directory. The site restarts to complete the uninstallation and unload app assemblies from the application domain.