HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback


Optimizely uses [NuGet](🔗) for handling applications (apps, sometimes known as add-ons) in a standard package format. You can install apps directly from Visual Studio or via the app user interface.

Note

For Azure environments, install app modules only through Visual Studio (and not from the Optimizely apps interface).

## Configure 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 apps from either Visual Studio or the user interface but not both, because an app may not work as expected. For example, if you install an app from Visual Studio, it appears in the app user interface, but operations (like disable and uninstall) may be unavailable.

## Before installing apps 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. This converts existing apps installed via the user interface to Visual Studio format.

  3. Add <https://nuget.episerver.com/feed/packages.svc/> as a NuGet source.

  4. Install and upgrade apps as normal via Visual Studio.

### Repository.config

The _modules/\_protected_ folder contains a _repository.config_ file, which is created during app 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 app system allows for the execution of custom code when an app is installed, updated or about to be uninstalled. The app 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 apps from the UI

You can install apps from the apps user interface without access to Visual Studio. To install app packages, you must be a member of the **PackagingAdmins** user group and have access to the Optimizely user interface.

  • Set **installationMode** to **UI**:



## Install app packages from the Optimizely central repository

In Optimizely, select **Add-ons** (apps) in the global menu. From here, you can install any available app. Optimizely does the following:

  1. Optimizely adds packages to a temporary repository.

  2. Optimizely tries to resolve dependents, and dependencies, and install the packages to the application from the temporary repository combined with the other repositories.

  3. Optimizely validates uploaded files and selected apps 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.

### Change the location of the temporary repository

The following list shows the package source repositories:

  • Optimizely **central** repository

  • The **temporary** repository

  • The site **local** repository

To resolve dependencies before installation, Optimizely 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.



### Change the location of the local repository

Optimizely sets up the site directory, _C:\\EPiServer\&lt;SiteName>\\wwwroot\\modules_, with correct access rights when you install Optimizely Framework from the Optimizely Deployment Center. Optimizely 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.

### Add repositories to the configuration

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



Note

Installed apps are registered in the file in the site root. Optimizely copies supported files to the corresponding app folder in the _~/modules/_ directory. See the description for the `episerver.packaging` element in [episerver.packaging (Legacy)](🔗).

### Copy app assemblies to the probing path directory

Optimizely copies app assemblies compatible with the current framework version to the probing path directory, which is located at _dirmodulesbin_ under _C:\\EPiServer\&lt;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**



**web.config**



### Complete the installation

After you install app 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 apps.

## Update an app

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

## Disable an app

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



## Uninstall an app

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