Key .NET and configuration changes

By Optimizely Education
Published: Mar 3, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Platform shift: Transition from legacy ASP.NET Framework to modern ASP.NET Core
Project structure: SDK-style projects simplify dependencies and file management
Configuration: Move from Web.config to layered appsettings.json and the Options Pattern
Hosting: Kestrel and a minimal Program.cs replace Global.asax and IIS-heavy setups

This module provides an in-depth examination of the fundamental .NET and configuration changes inherent in Optimizely CMS 12 and Commerce 14. Understanding these shifts is essential when transitioning existing solutions or building new ones on the latest Optimizely DXP.

Key .NET Changes

1. Project File Format (.csproj)

Simplified Structure: Automatic file inclusion via globbing.
SDK-Style Projects: Projects reference an SDK such as Microsoft.NET.Sdk.Web.

Example: SDK-style .csproj

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="EPiServer.CMS.AspNetCore" Version="12.x.x" />
    <PackageReference Include="EPiServer.Commerce.AspNetCore" Version="14.x.x" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="8.x.x" />
  </ItemGroup>
</Project>

2. Global Tooling and .NET CLI

Example: Using .NET CLI

# Install Optimizely templates
dotnet new install EPiServer.Net.Templates
dotnet new epi-cms-empty --name MyOptimizelyCmsProject

# Restore packages
dotnet restore

# Build
dotnet build

# Run
dotnet run

3. Runtime Environment and Hosting Model

Example: Minimal Hosting Model (Program.cs)

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCms();
builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
    endpoints.MapContent();
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapRazorPages();
});

app.Run();

Configuration Changes

1. appsettings.json and Layered Configuration

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "Optimizely": {
    "Cms": {
      "SiteUrl": "http://localhost:5000"
    }
  }
}

2. Using the Options Pattern

public class MyCustomSettings
{
    public string Setting1 { get; set; }
    public int Setting2 { get; set; }
}

services.Configure<MyCustomSettings>(
    Configuration.GetSection("MyCustomSection")
);

3. Connection Strings

{
  "ConnectionStrings": {
    "EPiServerDB": "YourConnectionStringHere",
    "EcfSqlConnection": "YourCommerceConnectionStringHere"
  }
}

4. User Secrets

Use dotnet user-secrets during development and secure environment variables or key vaults in production to manage sensitive configuration data without committing it to source control.

Conclusion

Migrating to CMS 12 and Commerce 14 introduces a modernized .NET foundation, improved configuration management, and a streamlined hosting model. Mastering these architectural shifts ensures smoother migration and future-ready Optimizely solutions.