Blog posts by Julian2025-05-27T22:16:32.0000000Zhttps://world.optimizely.com/blogs/julian/Optimizely WorldGetting Started with CMS 12 and Commerce 14: A Beginner’s Guide to Creating CMS and Commerce Projects<p>Getting started with Optimizely can sometimes be confusing. I realized that a clear, step-by-step guide to creating a solution with separate CMS 12 and Commerce 14 projects is hard to find. So, here’s a detailed walkthrough to help you implement it smoothly.</p>
<p>Get your Visual Studio 2022, SQL Server Management Studio, and a PowerShell terminal ready and let’s get started!</p>
<h2><strong>1. Install all the Optimizely necessary tools first</strong></h2>
<p>First of all, as usual, you need to install all the required tools as described <a href="https://docs.developers.optimizely.com/content-management-system/docs/installing-optimizely-net-5#install-a-cms-sample-site-with-alloy-templates">here</a> and <a title="here" href="https://docs.developers.optimizely.com/content-management-system/docs/installing-add-ons#before-you-install-apps-from-visual-studio">here</a> , if you are all set up ignore this step</p>
<ul>
<li>Install templates => <code>dotnet new -i EPiServer.Templates</code> </li>
<li>Install CLI => <code>dotnet tool install EPiServer.Net.Cli --global --add-source <a href="https://nuget.optimizely.com/feed/packages.svc">https://nuget.optimizely.com/feed/packages.svc</a></code></li>
<li>Add Nuget source "https://api.nuget.optimizely.com/v3/index.json" in Visual Studio > Tools > Options > NuGet Package Manager > Package Sources. Note: For some reason, Optimizely’s documentation doesn’t clearly state that this step is necessary (at least at the time of writing). However, if you skip it, you won’t be able to manage NuGet packages correctly. The only place that mentions it still refers to the old source "https://nuget.episerver.com/feed/packages.svc/", both sources work</li>
</ul>
<p><img src="/link/eb27adc7f42f46ada124e2c23c6ff1ca.aspx" width="518" height="359" /></p>
<p> </p>
<h2><strong>2. Create the Solution and Projects</strong></h2>
<p>Navigate to the folder where you want to create the entire project. From there, we’ll run the necessary commands to create the solution, a project for Commerce, and another for the CMS.</p>
<ul>
<li>Create the solution => <code>dotnet new sln -n MyEcommerce -o MyEcommerce</code></li>
<li>Move into the created folder => <code>cd MyEcommerce</code></li>
<li>Create the CMS project => <code>dotnet new epi-cms-empty -n MyEcommerce.Web -o MyEcommerce.Web</code></li>
<li>Create the commerce project => <code>dotnet new razorclasslib -n MyEcommerce.Commerce -o MyEcommerce.Commerce</code>, there is a template for empty commerce project but sometimes the commerce project must be installed after the CMS project so I want to show this way as well</li>
<li>Add the CMS project to the solution => <code>dotnet sln add .\MyEcommerce.Web\</code></li>
<li>Add the Commerce project to the solution => <code>dotnet sln add .\MyEcommerce.Commerce\</code></li>
</ul>
<p><strong>-n</strong> Project name</p>
<p><strong>-o</strong> Output directory</p>
<p>Now you can open the solution in visual studio 2022, right click on MyEcommerce.Web and set it as startup project</p>
<p><img src="/link/518149e8eb05478e828704a17dea4253.aspx" /></p>
<p>Then right click on the solution and select "Manage Nuget packages for Solution" and ensure Package source is "All" in the top right corner</p>
<p><img src="/link/8a7ab254758e402b9abf7a6e731700d3.aspx" width="247" height="70" /></p>
<p>Check that both project "MyEcommerce.Commerce" have the same .Net version as "MyEcommerce.Web", For example, in the image bellow I have to change the target framework from net9.0 to net8.0 and update Microsoft.AspNetCore.Components.Web package from 9.0.3 to 8.0.16 </p>
<p><img src="/link/cc242e3691d2404aaad5a14ef1cbaeee.aspx" /></p>
<p>Right click on MyEcommerce.Web.csproj / Dependencies then select "Add project reference" and choose "MyEcommerce.Commerce" to add it as a reference</p>
<p> </p>
<h2><strong>3. Configure the projects to use Optimizely Commerce</strong></h2>
<p>First, Check if "EPiServer.CMS" is installed in "MyEcommerce.Web" using Nuget Manager, if it's not the latest version then update it. Then search "EPiServer.Commerce" in the nuget package manager and install the latest version in both projects </p>
<p><img src="/link/2c0be042d5e14e989cffd010bc3f0565.aspx" width="661" height="256" /></p>
<p>Go to "MyEcommerce.Web" project and open Startup.cs, replace the call to ".AddCms()" with ".AddCommerce()" (this method internally implements AddCms())</p>
<p><img src="/link/9defe486056b40cbaeee2d3598ffa690.aspx" /></p>
<p>Update appsettings.Development.json to include commerce virtual roles in MappedRoles:</p>
<pre class="language-javascript"><code>"MappedRoles": {
"Items": {
"CmsEditors": {
"MappedRoles": [ "WebEditors", "WebAdmins" ]
},
"CmsAdmins": {
"MappedRoles": [ "WebAdmins" ]
},
"Administrators": {
"MappedRoles": [ "WebAdmins", "Admins" ]
},
"CommerceAdmins": {
"MappedRoles": [ "WebAdmins" ]
},
"CatalogManagers": {
"MappedRoles": [ "WebAdmins" ]
},
"CustomerServiceRepresentatives": {
"MappedRoles": [ "WebAdmins" ]
},
"MarketingManagers": {
"MappedRoles": [ "WebAdmins" ]
},
"OrderManagers": {
"MappedRoles": [ "WebAdmins" ]
},
"ReportManagers": {
"MappedRoles": [ "WebAdmins" ]
}
}
}
</code></pre>
<p> </p>
<h2><strong>4. Configure the databases</strong></h2>
<p>When Optimizely creates a project using the CLI or the graphical interface, it creates the database in MyEcommerce.Web/App_Data folder as .mdf files, but that's not going to work properly when creating a project for development, so we will switch that to use Sql Server</p>
<p>Go to MyEcommerce.Web/App_Data folder and delete any files created there, then open appsettings.Development.json and remove the ConnectionStrings section</p>
<p>Open powershell and navigate to the MyEcommerce.Web project <code>cd .\MyEcommerce.Web\</code> Now create the cms database using the CLI, so first copy the server name from Sql Server Management Studio and replace it in next command, this will create the database and the connection string in appsettings.json</p>
<p><code>dotnet-episerver create-cms-database MyEcommerce.Web.csproj -S <ReplaceWithServer> -E -dn MyEcommerceCMS</code></p>
<p><strong>-S</strong> Server name</p>
<p><strong>-E</strong> Create the connection string as integrated security </p>
<p><strong>-dn</strong> Database name</p>
<p>Now we can run the project and it will ask you to create the Admin user, if for some reason it doesn't ask you to create it then use this command to create the admin user replacing the username, email and password</p>
<p><code>dotnet-episerver add-admin-user MyEcommerce.Web.csproj -u MyUSer -e myuser@email.com -p MyUser123* -c EPiServerDB</code></p>
<p><strong>-u</strong> User</p>
<p><strong>-e</strong> Email</p>
<p><strong>-p</strong> password</p>
<p><strong>-c</strong> Connection string</p>
<p>Test that you can now run the project and login in the backoffice in <a href="https://localhost:5000/episerver/cms">https://localhost:5000/episerver/cms</a> or whaterver is your localhost</p>
<p>Now let's create commerce database</p>
<p><code> dotnet-episerver create-commerce-database MyEcommerce.Web.csproj -S <ReplaceWithServer> -E -dn MyEcommerceCommerce</code></p>
<h2><strong>5. Add Cms Content types</strong></h2>
<p>Here I will add only the basic Page and block content types, note that several content types are missing here, add each one of them in a class on its own in MyEcommerce.Web > Models</p>
<pre class="language-csharp"><code> [ContentType(
DisplayName = "Block Base",
GUID = "{E81F6E18-B49D-472D-9504-6FBE4DF8C631}"
)]
public class BlockBase: BlockData
{
}
[ContentType(
DisplayName = "Page Base",
GUID = "{8C654336-F62A-46A4-9E62-F7456DD4D32E}"
)]
public class PageBase: PageData
{
[Display(
Name = "Heading",
Description = "The main heading of the page."
)]
public virtual string Heading { get; set; }
}</code></pre>
<p> </p>
<h2><strong>6. Add basic Commerce Content Types</strong></h2>
<p>Add these classes in MyEcommerce.Commerce > Models, each in its own class file, note that I have included only one property per class as an example, you should customize it as per your specific requirements </p>
<p> </p>
<pre class="language-csharp"><code>CatalogContentType(
DisplayName = "Bundle Base",
GUID = "{CCF26036-A7EF-40F2-8E69-AFB57BE00902}"
)]
public class BundleBase: BundleContent
{
[Display(
Name = "Bundle description"
)]
[UIHint(UIHint.Textarea)]
public virtual string Description { get; set; }
}
[CatalogContentType(
DisplayName = "Catalog Base",
GUID = "{31B74E5C-7B0C-4538-A311-B30325AF27B2}"
)]
public class CatalogBase: CatalogContent
{
[Display(
Name = "Catalog Description"
)]
[UIHint(UIHint.Textarea)]
public virtual string Description { get; set; }
}
[CatalogContentType(
DisplayName = "Category Base",
GUID = "{C310EC9C-F987-48ED-931F-285229743089}"
)]
public class CategoryBase: NodeContent
{
[Display(
Name = "Category description"
)]
[UIHint(UIHint.Textarea)]
public virtual string Description { get; set; }
}
[CatalogContentType(
DisplayName = "Package Base",
GUID = "{8CFE8AAC-F359-4B8C-8D9E-98BCA64F166D}"
)]
public class PackageBase: PackageContent
{
[Display(
Name = "Package description"
)]
[UIHint(UIHint.Textarea)]
public virtual string Description { get; set; }
}
[CatalogContentType(
DisplayName = "Product Base",
GUID = "{085AFC91-E49A-42E8-A146-4E8F7FBBD43A}"
)]
public class ProductBase: ProductContent
{
[Display(
Name = "Product description"
)]
[UIHint(UIHint.Textarea)]
public virtual string Description { get; set; }
}
[CatalogContentType(
DisplayName = "Variant Base",
GUID = "{BEB277AE-D586-4CC1-ACCF-0A47855FCFC6}"
)]
public class VariantBase: VariationContent
{
[Display(
Name = "Variant description"
)]
[UIHint(UIHint.Textarea)]
public virtual string Description { get; set; }
}</code></pre>
<p> </p>
<h2><strong>7. Do the Migration</strong></h2>
<p>If you navigate now to the Commerce edit mode at <a href="https://localhost:5000/EPiServer/Commerce/catalog">https://localhost:5000/EPiServer/Commerce/catalog</a> you may see this error:</p>
<p>"Failed loading content with the url/uri: epi.cms.contentdata:///-1073741823__CatalogContent"</p>
<p>This happens because migration step which creates the catalog root is still missing</p>
<p><img class="img-thumbnail clickable zoomable" title="Click image to zoom" src="/link/e78877ee9a1a42cd9374522cb37b3ded.aspx" width="323" height="151" /></p>
<p>It's possible that when you started the project you were redirected to a url like <a href="https://localhost:5000/EPiServer/Commerce/EPiServer/Commerce/Migrate?autoMigrate=true">https://localhost:5000/EPiServer/Commerce/EPiServer/Commerce/Migrate?autoMigrate=true</a>,</p>
<p>However, for some reason Optimizely is redirecting to the wrong url, so if you take a look in detail you will see that EPiServer/Commerce is twice, to fix this change the url to <a href="https://localhost:5000/EPiServer/Commerce/Migrate?autoMigrate=true">https://localhost:5000/EPiServer/Commerce/Migrate?autoMigrate=true</a> , you should then see this migration page:</p>
<p> </p>
<p><img src="/link/e574d8b4d62c4014b7a5ee62da0a7e25.aspx" width="741" height="280" /></p>
<p>If you see migration completed then this step is finished</p>
<h2><strong>8. Create Commerce content</strong></h2>
<p>And voilà! The setup is complete, you can go now to edit mode at <a href="https://localhost:5000/EPiServer/Commerce/catalog">https://localhost:5000/EPiServer/Commerce/catalog</a> to Create new Catalogs, inside each catalog you can create Products with variants, bundles, packages, categories</p>
<p>Now you a have a project to handle CMS "MyEcommerce.Web" and another to handle Commerce "MyEcommerce.Commerce" both in the same solution.</p>
<p><img src="/link/69727d5c6e8f46968ac86c0d0dcea406.aspx" width="816" height="405" /></p>
<p> </p>
<p> </p>
<p> </p>2025-05-27T22:16:32.0000000ZBlog post