Installing Optimizely updates (Legacy)

Note: This topic is only applicable to versions prior to CMS 12/Commerce 14, as these were based on ASP.NET Framework. For versions CMS 12 and Commerce 14 and higher, based on ASP.NET Core, see Installing Optimizely.

Optimizely continuously releases updates with new features and bug fixes using client-side NuGet packages. This topic describes how to update an Optimizely solution through NuGet packages from the Optimizely NuGet feed.

About the updates

Continuous release updates are cumulative to include previous updates. Optimizely supports all platform updates and strongly recommends that you keep ongoing projects up-to-date. 

Note: A product release may contain multiple NuGet packages with inter-dependencies. When a release is built, other dependent packages may also be bumped to new versions, although they contain no publicly visible changes. This is done to avoid dependency errors. When you upgrade, NuGet alerts you to upgrade related packages to the required versions. For Commerce, it is important to ensure that you are running the same version of CMS and Commerce, both in the front-end and back-end applications.

Release information

Details about released items can be found in the release notes. See also weekly updates for a summary of released features and fixes for the Optimizely platform.

Upgrading steps

  1. Add the Optimizely NuGet feed to the NuGet package manager in Visual Studio (if not done).
  2. Select and apply packages to install. Upgrades are cumulative: the latest includes previous updates.
  3. Update configuration and database schemas. If upgrading to a new major version, see breaking changes information for related fixes. 
  4. Deploy the updates to your different environments. 

Adding the Optimizely NuGet feed

Do the following to add the Optimizely NuGet feed to Visual Studio, if you do not already have this:

  1. In Visual Studio, select Tools > NuGet Package Manager > Package Manager Settings.
  2. Select Package Manager > Package Sources.
  3. Click the green + sign to add a new package source.
  4. Add Episerver as Name, and the package Source

  5. Click OK.

Note: NuGet package manager has to be version 2.8.50126.477 or higher to install Optimizely packages.

Selecting and applying packages

Select packages to update to

If you have no Optimizely NuGet packages installed, you can install the EPiServer.CMS package to get the latest version of all packages for Optimizely CMS. Similar packages are available for other parts of the Optimizely platform. Carefully read the package descriptions to ensure a smooth upgrade procedure. 

Note: See Commerce-specific updating steps before installing Commerce packages.

Note: If you are using the Alloy sample site in CMS 7 or have a project deriving from that, see Updating a CMS project based on the Alloy sample site before continuing; if you are running 7.5 or later, you can skip this step.

Applying an update

  1. Open the solution file in Visual Studio and make sure the solution file is saved (required to make the NuGet tools available).
  2. In the Solution Explorer, right-click on References for the project, and select Manage NuGet Packages.

  3. Select Updates for the Optimizely package source to locate available updates for your solution, and click Update for the desired packages.

  4. When the installation/update is completed, rebuild the solution.
  5. See product-specific updating steps for steps required to finalize the update.

Installing a specific version 

To install a specific version, go to the Package Manager Console in Visual Studio and make sure it points to the Optimizely NuGet feed. Install or update the packages of your solution as shown in the following examples:

Install-package EPiServer.CMS -Version 9.0.0


Update-Package EPiServer.CMS -Version 9.0.0

Updating configuration and database schemas

Note: The database user connecting to SQL Server must be granted access to perform schema changes on the database. Members of the db_owner fixed database role can perform all configuration and maintenance activities on the database, including schema changes.

  • From version 8.7: By default, the cmdlet Update-EPiDatabase is used to manually update the database schema. From version 8.7 you can configure the site to automatically apply updates to the SQL schema during site initialization.
  • From version 7.6: When Optimizely makes changes to the configuration schema or the database schema, those changes are incorporated into the NuGet package as transformation files. See Updating configuration and database schemas for information about manually deploying changes to configuration and database transforms when needed.

Product-specific updating steps

If you are using Commerce, specific versions of CMS, and Live Monitor, there are additional product-specific updating steps needed to complete the updating. Depending on which version you currently are on, there may be minor differences in the update procedure.

Issues with NuGet

In some upgrade scenarios, you might experience problems with the dependency chains, due to issues in NuGet. This mostly affects Commerce and Search & Navigation, but might also occur when updating CMS. The workaround is usually to update the packages one-by-one. See Issues with NuGet package updates.

Beta features

To get an early start and access new features that are being developed, you can join a Beta program and be part of a CTP (Community Test Preview), see Optimizely service and product lifecycles.

Last updated: Sep 28, 2021