Upgrading to Episerver 7.5 Commerce

This document describes the upgrading procedure for updating an existing solution with EPiServer Commerce to version 7.5. The procedure covers the upgrading from EPiServer Commerce version 1 R3, including existing add-ons and other EPiServer products installed on the website. The upgrading is done from the EPiServer Deployment Center, the Add-on Store inside EPiServer, and the NuGet feed if you are using this for your solution.

Note that the procedure below describes the sequence in which the upgrading is done. If you do not have a product or add-on (CMO, Mail, Relate etc) mentioned below installed on your site, skip that step and continue to the next step in the procedure.

Before upgrading

Do the following before you start the upgrade:

As the upgrade cannot be rolled back, it is highly recommended to back up all your databases, websites and settings. Also it is recommended to verify the upgrade in a test environment before applying it in a production environment.
It is recommended (though not required) to run IISRESET before you upgrade to avoid locking issues. If your server is running multiple websites, then you can recycle your website application pools, both for the front-end and Commerce Manager sites.
Ensure that the Tools.zip file exists in the wwwroot/MediachaseECF folder of the front-end site.

General upgrading procedure

Before starting the upgrade to EPiServer 7.5, ensure that any add-ons are upgraded to the latest version, as listed in the Add-ons Store.
Download and extract the EPiServer 7.5 installation package, and run the Setup.exe file.
Open the EPiServer Deployment Center and go to the All Actions tab.
To upgrade CMS, expand the options for EPiServer CMS version 7.5 (latest). Select Upgrade site with SQL database, click Run and let the upgrade finalize.
If you have Live Monitor installed, expand the options for EPiServer CMS version 7.5 (latest), select Modules > Install Live Monitor, click Run and let the upgrade finalize.
If you have CMO installed, expand the options for EPiServer CMS version 7.5 (latest), select Upgrade to EPiServer CMO 7.5, click Run and let the upgrade finalize.
If you have Mail installed, expand the options for EPiServer Mail version 7.5 (latest), select Upgrade to EPiServer Mail 7.5, click Run and let the upgrade finalize.
If you have Community/Relate installed, expand the options for EPiServer Community version 7.5 (latest), select Upgrade to EPiServer Community 7.5, click Run and let the upgrade finalize.
To upgrade Commerce, expand the options for Modules under EPiServer CMS version 7.5 (latest), select Upgrade to EPiServer Commerce 7.5, click Run and let the upgrade finalize.
Before continuing, you need to reload the website to initialize added components. Browse to the website and verify that it is working properly before adding the NuGet updates in the next steps.
If you have been using NuGet for updates in your project, you also need to update your NuGet dependencies. For Commerce it is now possible to install a NuGet package from here as well, to manage future updates.
If you have not been using NuGet, and your project is based on the Alloy templates, install the NuGet packages as follows:
- Make sure you have a saved Visual Studio solution file (this is required to make the NuGet tools available).
- In Solution Explorer > References context menu, select Manage NuGet Packages.
- In the list of available packages, locate the package to install (for instance EPiServer.CMS.Core).
- Click Install and accept the license terms.
- Rebuild the project.
Compile your project and correct any compilation errors listed. Refer to the details in the compilation message and the breaking changes sections in the SDKs for EPiServer Framework and CMS, and Commerce.
When all installed products have been upgraded, select Upgrade/Disable Add-ons after Product Upgrade under EPiServer CMS version 7.5. This will disable any "regular" add-ons such as EPiServer Languages or Google Analytics for EPiServer, and upgrade the system-addons shipped with the upgraded products.
Go to the Add-ons section on your EPiServer website, and click Enable for the installed add-ons that were disabled in the previous step. This will upgrade add-ons to the latest version, or enable add-ons that are already compatible. Refer to Add-ons command line support in the Add-ons section of the Framework SDK if you experience problems with this step.
For Commerce, apply the Asset migration tool to to migrate assets for Commerce sites, in order to use the new asset API in EPiServer 7.5.The procedure is required to be able to use existing assets for instance when editing products in the new Catalog Edit view. Refer to Migrating assets to the media system in the Upgrading section of the EPiServer Commerce SDK.
If your site contains VPP-based files, apply the VPP migration tool to migrate files to use the new asset API in EPiServer 7.5. Refer to Migrating VPP-based files to the new media system in the Upgrading section of the EPiServer CMS SDK.
For Commerce, go to the Add-ons section on your EPiServer website, and click Update for the Commerce Core UI and Commerce Management components. This will update the Commerce add-on components to the latest versions.

Notifications

If you have disabled the EPiServer change log feature, you will need to go to the CMS admin view and disable this again after the upgrade, since this will automatically set the change log state to default "enabled".
If you are using EPiServer Web Services on your site: In EPiServer Deployment Center, expand the Modules options under EPiServer CMS version 7.5 (latest), and select Install EPiServer Web Services. Click Run and let the upgrade finalize in order to add EPiServer Web Services on the upgraded site.

After upgrading

Do the following after the upgrade:

The upgrade does not change your website compilation settings. Ensure that the production website is running with the debugging option turned off. Update the configuration settings as follows:
- For the front-end site, update the web.config: <compilation defaultLanguage="c#" debug="false" optimizeCompilations="true">
- For the back-end Commerce Manager site: <compilation debug="true">

For the front end site modify the web.config to make sure remote events are enabled. Uncomment the lines if they are commented out.

<services>
<service name="EPiServer.Events.Remote.EventReplication">
<!-- Uncomment this endpoint and the "RemoteEventServiceClientEndPoint" to enable remote events-->
<endpoint name="RemoteEventServiceEndPoint"
contract="EPiServer.Events.ServiceModel.IEventReplication"
binding="customBinding"
bindingConfiguration="RemoteEventsBinding"
address="soap.udp://239.255.255.19:5000/RemoteEventService" />
<service>
<service name="EPiServer.Business.Commerce.EventService" behaviorConfiguration="EPiServer.Business.Commerce.EventServiceBehavior">
<endpoint address="" binding="webHttpBinding" contract="EPiServer.Business.Commerce.IEventService" behaviorConfiguration="EventServiceEndpointBehavior" />
<endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" />
</service>
</services>
<client>
<!-- Uncomment this endpoint and the "RemoteEventServiceEndPoint" to enable remote events-->
<endpoint name="RemoteEventServiceClientEndPoint"
address="soap.udp://239.255.255.19:5000/RemoteEventService"
binding="customBinding"
bindingConfiguration="RemoteEventsBinding"
contract="EPiServer.Events.ServiceModel.IEventReplication" />
</client>

In the back-end Commerce Manager site, modify the webconfig to have the service.model section as show below:

<system.serviceModel>
    <extensions>
      <bindingElementExtensions>
        <add name="udpTransportCustom" type="Microsoft.ServiceModel.Samples.UdpTransportElement, EPiServer.Events" />
      </bindingElementExtensions>
    </extensions>
    <services>
      <service name="EPiServer.Events.Remote.EventReplication" behaviorConfiguration="DebugServiceBehaviour">
        <!--<endpoint name="RemoteEventServiceEndPoint" contract="EPiServer.Events.ServiceModel.IEventReplication" bindingConfiguration="RemoteEventsBinding" address="net.tcp://localhost:13000/RemoteEventService" binding="netTcpBinding"/>-->
        <endpoint name="RemoteEventServiceEndPoint" contract="EPiServer.Events.ServiceModel.IEventReplication" binding="customBinding" bindingConfiguration="RemoteEventsBinding" address="soap.udp://239.255.255.19:5000/RemoteEventService" />
      </service>
    </services>
    <client>
      <!-- Uncomment this endpoint and the "RemoteEventServiceEndPoint" to enable remote events -->
      <endpoint name="RemoteEventServiceClientEndPoint" address="soap.udp://239.255.255.19:5000/RemoteEventService" binding="customBinding" bindingConfiguration="RemoteEventsBinding" contract="EPiServer.Events.ServiceModel.IEventReplication" />
    </client>
    <behaviors>
      <serviceBehaviors>
        <behavior name="DebugServiceBehaviour">
          <serviceDebug includeExceptionDetailInFaults="true" />
        </behavior>
        <behavior name="EPiServer.Business.Commerce.EventServiceBehavior">
          <serviceMetadata httpGetEnabled="true" />
          <serviceDebug includeExceptionDetailInFaults="false" />
        </behavior>
        <behavior name="CommerceSiteBehavior">
          <serviceMetadata httpGetEnabled="true" />
          <serviceDebug includeExceptionDetailInFaults="true" />
        </behavior>
      </serviceBehaviors>
      <endpointBehaviors>
        <behavior name="EventServiceEndpointBehavior">
          <webHttp />
        </behavior>
      </endpointBehaviors>
    </behaviors>
    <bindings>
      <customBinding>
        <binding name="RemoteEventsBinding">
          <binaryMessageEncoding />
          <udpTransportCustom multicast="True" />
        </binding>
      </customBinding>
    </bindings>
  </system.serviceModel>

After the update, the warehouses will have three settings: pickup location, fulfillment center and delivery location. To be able to add a new line item to an order, you must first update at least one of the warehouses to be a either a pickup location, fulfillment center, delivery location, or all three.
The search index must be rebuilt.
The [Resources] page, as well as the [Commerce] Catalog Page Provider content type are now legacy, and can safely be removed from the Edit and Admin views.

Reworking existing page templates

Since the Page Provider has been removed and replaced with a Content Provider solution, existing templates will need to be reworked to use the new CMS-style routing and rendering.

You will need to register a new partial routing system in the initialization module: CatalogRouteHelper.MapDefaultHierarchialRouter(routes, false);
Ensure that the product detail and product listing pages inherit from ContentPageBase<T>, where T is of type CatalogContentBase.
Create content types corresponding to the meta data classes for CatalogNode(s) and CatalogEntry(s).

For example, a content type for Node with FashionStoreSubLandingNode metadata class can be defined as below:

[CatalogContentType(GUID = "4AAA80AB-393F-4A15-A787-03454EDE6E5E", MetaClassName = "FashionStoreSubLandingNode")]
[AvailableContentTypes(Include = new Type[] { typeof(FashionProductContent), typeof(FashionItemContent), typeof(NodeContent), typeof(BundleContent), typeof(PackageContent)})]
public class FashionStoreSubLandingNodeContent : SiteSubCategoryContent
{
}

A content type for Entry with a WineSKU metadata class can be defined:

[CatalogContentType(GUID = "B96A3924-D07D-4ECA-BFA3-C0C3138CD138", MetaClassName = "WineSKU")]
public class WineSKUContent : VariationContent, IFasetBrand, IInfoModelNumber
{
public virtual string Info_ModelNumber { get; set; }

public virtual string Facet_Brand { get; set; }
}

Refer to the EPiServer Commerce sample site templates for more examples of how to use the CMS-style and rendering for Commerce content.

Try our conversational search powered by Generative AI!