Upgrade Guide: Commerce 14 to Commerce 15 preview
This document provides step-by-step instructions to upgrade a Commerce site from Commerce 14/CMS 12 to Commerce 15/CMS 13 preview.
Overview
This upgrade includes:
-
Commerce: 14.15.3 → 15.0.0-preview1
-
CMS: 12.31.2 → 13.0.0-preview4
-
.NET: 8.0 → 10.0
Prerequisites
-
Visual Studio 2022 with .NET 10.0 SDK
-
SQL Server (LocalDB or full instance)
-
Basic understanding of Optimizely Commerce and CMS
Step 1: Create a new Commerce 14 empty site from template
To create a baseline Commerce 14 site from template:
- Run the template command:
dotnet new epi-commerce-empty --name CoCo14 --force- Open the project, restore packages, and build it
-
Press F5 and create a user by accessing: https://localhost:5000/util/register
-
Log in at: https://localhost:5000/util/login
-
Migrate Commerce data: https://localhost:5000/episerver/commerce/migrate
-
Verify the CMS/Commerce Admin UI: https://localhost:5000/episerver/cms
Verification: Ensure the site is running without errors before proceeding.
Step 2: Update Project Configuration
File Modified: [CoCo14.csproj]
Target Framework
<TargetFramework>net10.0</TargetFramework> <!-- was net8.0 -->Package References
Before (Simple metapackage approach):
<PackageReference Include="EPiServer.CMS" Version="12.31.2" />
<PackageReference Include="EPiServer.Commerce" Version="14.15.3" /> After (Explicit package references):
Commerce packages:
<PackageReference Include="EPiServer.Commerce" Version="15.0.0-preview1" />CMS packages (all version 13.0.0-preview4):
<PackageReference Include="EPiServer.OptimizelyIdentity" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0-preview4" />
<PackageReference Include="Optimizely.Graph.Cms" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.UI.ContentManager" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Hosting" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.UI.VisitorGroups" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.Shell.UI" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.UI" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Events.ChangeNotification" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.AspNetCore.TagHelpers" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.AspNetCore.HtmlHelpers" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.TinyMce" Version="13.0.0-preview4" />
Step 3: Update Startup Configuration
File Modified: [Startup.cs]
Update Service Registration
Before (Commerce 14 - Simple metapackage registration):
services
.AddCmsAspNetIdentity<ApplicationUser>()
.AddCommerce()
.AddAdminUserRegistration()
.AddEmbeddedLocalization<Startup>();
After (Commerce 15 - Explicit service registration):
services
.AddCmsHost()
.AddCmsCore()
.AddCmsAspNetIdentity<ApplicationUser>()
.AddCmsHtmlHelpers()
.AddCmsTagHelpers()
.AddCmsUI()
.AddAdmin()
.AddCmsImageSharpImageLibrary()
.AddTinyMce()
.AddContentGraph()
.AddContentManager()
.AddCommerce()
.AddVisitorGroupsMvc()
.AddVisitorGroupsUI()
.AddAdminUserRegistration()
.AddEmbeddedLocalization<Startup>();
services.Configure<DataAccessOptions>(options =>
{
options.UpdateDatabaseCompatibilityLevel = true;
});
Step 4: Update Application Settings
File Modified: [appsettings.json]
Add the following Optimizely configuration section for Content Graph
"Optimizely": {
"ContentGraph": {
"GatewayAddress": "https://cg.optimizely.com",
"AppKey": "<app-key>",
"Secret": "<secret>",
"SingleKey": "<single-key>",
"AllowSendingLog": "true"
}
}
Important: Replace the placeholder values (<app-key>, <secret>, <single-key>, <instance-id>) with your actual credentials from the Optimizely portal.
Step 5: Restore, Build, and Run Migration
After making all the changes:
-
Restore packages:
dotnet restore-
Build the project:
dotnet build-
Run the application:
-
-
Press F5 in Visual Studio, or
-
-
-
Run dotnet run from the command line
-
-
Run Commerce migration:
-
-
Navigate to: https://localhost:5000/Optimizely/commerce/migrate
-
-
-
This will update the database schema and migrate data to Commerce 15 format
-
Step 6: Verify the Upgrade
-
Access the Commerce Admin UI: Navigate to https://localhost:5000/Optimizely/Commerce/
Code Compatibility
-
Depending on your Commerce solution, you may need to update source code due to API changes in CMS 13 and Commerce 15. See the CMS 13 Pre-Release overview for details.
-
Commerce 15-compatible versions for popular Commerce add-ons will be released later
Preview Versions
-
Commerce 15.0.0-preview1 and CMS 13.0.0-preview4 are pre-release versions
-
Not recommended for production use
-
Use for evaluation and testing purposes only
Additional Resources
Hi there,
I'm following these instructions however the dotnet restore is failing on my build, specifically due to the error
C:\projects\commerce-15\commerce-15.csproj : error NU1102:
Unable to find package EPiServer.Commerce.ODP with version (= 15.0.0-preview1)
- Found 52 version(s) in optimizely [ Nearest version: 14.45.3 ]
- Found 0 version(s) in nuget.org
It would appear no pre-release version of the Commerce.ODP package has been published and the preview version depends on this.
Am I doing something wrong?
Thanks,
James
Hi James,
EPiServer.Commerce.ODP is not included in the preview1 release, it will be added to the final version
Thanks Viet Anh,
I have managed to get a commerce 15 site running locally now.
If others are running into the same issue I was, my resolution was to go to the installed package for the preview version in
.nuget\packages\episerver.commerce\15.0.0-preview1and updateepiserver.commerce.nuspecto modify the dependency forEPiServer.Commerce.ODPto be<dependency id="EPiServer.Commerce.ODP" version="[14.0.0, 15.0.0-preview1]" />.Thanks James,
Yes, ODP and other addons (like Service API) packages will be published soon after the Commerce Core packages.