HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubNuGetDev CommunitySubmit a ticketLog In

Deploy to Windows servers

Describes how to deploy Optimizely Content Management System (CMS) sites through Visual Studio.

You can install Optimizely Content Management System (CMS) through XCOPY deployment by copying application files. An XCOPY-style file transfer simplifies the deployment and maintenance of Optimizely sites because no registry entries are created, and no shared components are registered.

The XCOPY architecture in CMS has no machine-specific or site-specific information stored in configuration files so you can use a shared folder for multiple servers. When you develop in a shared environment with source control, you can keep configuration files checked and create a site that you can duplicate in a multi-site deployment.

You can have one single IIS application with multiple sites, or multiple IIS applications pointing to the same physical directory. The machine to which you install additional sites does not need to have Optimizely installed.

To host ASP.NET Core on Windows with IIS, follow the instructions from Microsoft Host ASP.NET Core on Windows with IIS.

Deploy a site

The following procedure shows how to deploy an Optimizely site from development to production. You can automate this using the dotnet command or other tools.

You need three artifacts to bring over to the production server:

  • Site – the Optimizely platform and templates with dependencies and modules. These are normally the root of a Visual Studio project. (Output from dotnet publish on project)
  • SQL Server database – stored content and so on.
  • Application Data – media BLOBs, search index. These are files normally stored in App_Data for a Visual Studio project. (Versions before CMS 7.6 store these files parallel to the Visual Studio project by default.)



The following steps assume you have an existing site and good knowledge of using Visual Studio, Internet Information Services Manager and SQL Server Management Studio.

1. Create the deployment artifacts

Create the deployment artifacts on the development machine to publish a package that can be installed on the target server.

  1. Open a Visual Studio project for the site you are deploying.
  2. Establish NuGet dependencies for the Optimizely products used. (This is done by default for CMS 7.6 and later.)
  3. Include all files in modules, modulesbin and App_Data folders in the project. (You also can copy those folders manually to the output folder.)
  4. Right-click the project in Visual Studio and click Publish or dotnet publish on the project. Specify a publish destination of type FileSystem.
  5. Under Settings, make sure Exclude files from the App_Data folder is not checked to restore those files on the destination.
  6. Publish the project.



If the database files are not stored in App_Data, see Back Up and Restore of SQL Server Databases on MSDN for details about moving databases.

2. Deploy the artifacts on the target server



The following steps are performed on the target server and assumes you have moved the artifacts created in the previous section to the new server. The web server should have IIS and ASP.NET Core installed. You also need SQL Server Management Studio to connect to the database server.

  1. Attach the database. See Attach a database on MSDN.

    To complete this step, move the database files from the App_Data folder to the designated data folder for Microsoft SQL Server.

    You can also use backup or restore to attach a database. See Backup and restore of SQL server databases on MSDN.

  2. Create a new SQL Login:

    1. Right-click on the Security node and select New > SQL Login.
    2. Select SQL Server Authentication.
    3. Unselect User must change password at next login.
    4. Under User Mapping, select the database and make sure the user is a member of the db_owner group.
  3. On the web server, create a new folder for your site (for example c:\inetpub\Site1), and copy the contents of the deployed site.

  4. Set access rights on the App_Data folder so that the group IIS_IUSRS have Change access.

  5. Open Internet Information Services Manager and connect to the web server.

  6. Create a new IIS site:

    1. Right-click the Sites node.
    2. Select Add Website.
    3. Select the wwwroot subfolder as the Physical path for the new site.
  7. Update the EPiServerDB connection string in the configuration file in the site root (such as web.config or connectionStrings.config, depending on setup) with connection details to the database (server, database, SQL login, and password).
    Make sure your db connection string contains MultipleActiveResultsSet=true. It is enabled by default when you install a website from scratch, but not if you generate a connection string from the server explorer in Visual Studio.



For security and performance reasons always move media BLOBs to a folder outside the application root (as described in the next section), either on a fileshare or a local folder. Storing BLOBs in the App_Data folder is only designed for development purposes.

3. Add load-balancing support

This section describes how to enable load-balancing, configure remote events, and external storage of BLOBs (files on a fileshare). The example uses the Azure service bus and the default provider for storage of BLOBs.



Use the dedicated Azure Service Bus provider.

  1. Move the Blob subfolder of the App_Data folder to a shared server, such as the database server, and then share the folder. Give access rights for the share and the folder to the user running the Application Pool for the site in Windows.

  2. Edit appsettings.json and add configuration for the file BLOB providers. Make sure the path attribute is valid:

          "BlobProvidersOptions": {
             "DefaultProvider": "fileShare",
             "Providers": {
               "fileShare": "EPiServer.Framework.Blobs.FileBlobProvider, EPiServer.Framework"
            "Path": "\\dbserver\blobs"
  3. Clear the browser cache and test the setup by browsing the site. Images on the site should work as before but now are delivered from the shared location.

  4. Configure the default provider for remote events by configuring the endpoints.
    The site is ready to be load-balanced.

  5. Copy the site folder to a second server and create a site in IIS with the same settings as the previous server. No configuration changes are required.

  6. Test remote events by logging in to one of the servers and publishing changes to a page. The published changes appear on the other server. Use the search functionality from both servers to verify it was configured correctly.

A hosting provider can help you load-balance incoming traffic between the servers. You also can use other software load-balancers such as HAProxy, Network Load Balancing (NLB), or Application Request Routing (ARR).



The core parts of CMS do not use Session State but some functionality does, such as some of the audience criteria. There are two approaches to enabling session state that depend on the sticky session feature (also known as session affinity) provided by a load-balancer that makes sure a user is reaching the same server combined with the default in-memory session state provider. You also can use an optimized provider for load-balancing, such as the built-in StateServer.

You should enable the ARR Affinity setting for applications in Optimizely Digital Experience Platform (DXP) to ensure proper functioning and saving of contents, with respect to cache invalidation by remote events. In Azure, go to the App Service where you want to make the change, select Configuration > General Settings, and enable ARR Affinity.

You can also set ARR Affinity in web.config as follows:

      <add name="Arr-Disable-Session-Affinity" value="false" />