Framework and platform breaking changes

This article covers framework and platform-level breaking changes in CMS 13, including runtime requirements, NuGet packaging, dependency injection, serialization, and foundational API changes.

.NET 10 requirement

CMS 13 requires .NET 10.0. You must update your project target framework from net8.0 to net10.0 in your .csproj file. This also affects Docker base images and CI/CD pipeline configurations.

NuGet packaging

• NuGet packages were updated to represent single assemblies.
• The EPiServer.CMS.Core package works as an umbrella package with dependencies on packages whose assemblies were previously included in the package.
• The EPiServer.Framework package contains only the EPiServer.Framework assembly. Add a dependency to the individual assembly that you require.
• The EPiServer.Cms.HealthCheck package was removed, and the SQL health check consolidated into EPiServer.Data.
• The EPiServer.Data.Cache library has been integrated into the main EPiServer.Data assembly and removed as a separate package. Cache services are now registered in the main AddCmsData method.

Cross-cutting changes

• Service registration methods were moved from the namespace Microsoft.Extensions.DependencyInjection to EPiServer.DependencyInjection.
• Serialization constructors were made obsolete in .NET 8 and removed: protected SomeClass(SerializationInfo info, StreamingContext context).
• Argument validation for strings follows the .NET convention and throws an ArgumentException if empty rather than an ArgumentNullException.
• Argument validation for properties of argument objects follows the .NET convention and throws an ArgumentException if null rather than an ArgumentNullException.
• Argument validation for ContentReference arguments follows the .NET convention and throws an ArgumentException if empty rather than an ArgumentNullException.
• CMS no longer has a dependency on Castle.Windsor. Any use of it requires an explicit dependency on that package.
• Parameter names have been adjusted in places where the previous name was inconsistent with the overridden declaration or with other method overloads. Such changes have not been noted individually.

Newtonsoft.Json replaced with System.Text.Json

CMS 13 migrated from Newtonsoft.Json to System.Text.Json throughout the framework. If your project has code that depends on Newtonsoft.Json (especially after removing packages like Episerver.Find), you must add an explicit package reference.

• EPiServer.Framework.Serialization.Json.Internal.JsonObjectSerializer was removed. Use SystemTextJsonObjectSerializer instead.
• EPiServer.Framework.Serialization.Json.NotANumberConverter rewritten to use System.Text.Json.JsonSerializer.
• EPiServer.Framework.Serialization.Json.NameValueCollectionConverter rewritten to use System.Text.Json.JsonSerializer.
• EPiServer.Framework.Serialization.Json.DateTimeConverter rewritten to use System.Text.Json.JsonSerializer.
• EPiServer.Shell.Json – Classes JsonIdentityConverter, TypeArrayConverter, and TypeConverter were removed.

Removed Newtonsoft formatters

• NewtonsoftJsonSerializerSettingsOptions removed.
• Extension method UseNewtonsoftJson removed.
• FormatterType enum removed.
• ExtendedNewtonsoftJsonOutputFormatter removed.
• NewtonsoftFormatterExtensions extensions removed.

Nullable reference type annotations

Some libraries enable nullable reference type annotations. This may produce compile-time nullability warnings in consuming code. Affected libraries/namespaces:

• EPiServer.ImageLibrary
• EPiServer.Data.Cache
• EPiServer.Hosting
• EPiServer.Logging
• EPiServer.Personalization
• EPiServer.HtmlParsing
• EPiServer.Events

To suppress these warnings, add #nullable enable to affected files, or enable nullable reference types project-wide and address the warnings.

Spelling corrections in public API

The following spelling errors are corrected in the public API. These are binary breaking changes that may require code updates if you reference the old names:

EPiServer.Framework

• EPiServer.Framework.FrameworkInitialization – No longer implements IConfigurableModule. Services are now registered using the AddCmsFramework() service registration method.

• EPiServer.Framework.EnvironmentOptions – Obsolete property BasePath was removed.

• EPiServer.Framework.Initialization.AssemblyList – Obsolete class AssemblyList was removed.

• EPiServer.Framework.Initialization.HostType – LegacyMirroringAppDomain was removed because mirroring is no longer supported.

• EPiServer.Framework.Initialization.IInitializationEngine – This interface was removed as it was not used in practice.

• EPiServer.Framework.Initialization.InitializationEngine –

  • The Assemblies property was removed. Use AppDomain.CurrentDomain.GetAssemblies() instead, and filter out dynamic assemblies.
  • Set method was removed from Modules property.
  • Set method was removed from Locate property. Use context.Services instead.
  • The ScanAssemblies method was removed.
  • The BuildTypeScanner method was removed.
  • The GetDependencySortedModules method was removed.
  • The ConfigureModules method was removed. Call Configure(complete: false) instead.
  • Calling Configure() or Configure(complete: true) multiple times now throws an InvalidOperationException. Call Configure(complete: false) instead if you do not intend to transition the initialization state.

• EPiServer.Framework.Blobs – The generic Blob functionality has been moved to a separate EPiServer.Blobs package. Reference package and add services using the AddCmsBlobs() service registration method if needed.

• EPiServer.Framework.Blobs.FileBlobProvider – Default constructor and constructors with internal IPhysicalPathResolver parameter were removed. The Initialize(string, NameValueCollection) method was also removed. Use the constructor with FileBlobProviderOptions parameter instead.

• EPiServer.Framework.Blobs.Blob – The class is now abstract. The following methods changed from virtual (throwing NotImplementedException) to abstract: OpenRead(), OpenWrite(), Write(Stream), AsFileInfoAsync(). New abstract methods added: Exists(), ExistsAsync(), OpenReadAsync(), OpenWriteAsync(), WriteAsync().

• EPiServer.Framework.Blobs.BlobNotFoundException – New exception type. Thrown by Blob.OpenRead() and Blob.OpenReadAsync() when the blob does not exist.

• EPiServer.Framework.Cache – Cache abstractions and memory implementations moved to a separate EPiServer.Cache package. Reference and add services using AddCmsCache().

• EPiServer.Framework.Cache.ISynchronizedObjectInstanceCache – SynchronizationFailedStrategy setting is no longer applied to the cache.

• EPiServer.Framework.Timers.ITimer – The ITimer abstraction is no longer used by CMS and is obsolete. No implementation is registered by the Framework.

• EPiServer.Framework.ProviderActivationException – No longer thrown when provider activation fails. As providers now require service registration, an InvalidOperationException is thrown instead.

• EPiServer.Framework.Security.ISiteSecretManager – Made obsolete. You can still read existing secrets but not create new secrets. This API supported the event system.

EPiServer.ServiceLocation

• The following obsolete classes were removed:

  • IInterceptorRegister
  • IRegisteredService
  • IServiceConfigurationProvider
  • IServiceLocator
  • ServiceDesriptor
  • ServiceLocationHelper
  • ServiceLocatorExtensions
  • ServiceLocatorImplBase

• EPiServer.ServiceLocation.AutoDiscovery – Obsolete classes removed: IServiceLocatorFactory, ServiceLocatorFactoryAttribute.

• EPiServer.ServiceLocation.ServiceCollectionExtensions – IServiceCollection extension methods with an equivalent method in Microsoft.Extensions.DependencyInjection were removed.

Package namespace moves

Several namespaces have been extracted into separate packages. If you use functionality from these namespaces, add an explicit package reference:

EPiServer.Framework.AspNetCore

• EPiServer.Framework.FileSystem – Obsolete classes IDirectory, IFile, IFileSystemWatcher, PhysicalDirectory, and PhysicalFile were removed.

• EPiServer.Framework.Web.Resources.ClientResources – Obsolete methods Render and RenderRequiredResources were removed.

• EPiServer.Framework.Security.ValidateAntiForgeryReleaseToken – Removed internal attribute. Replace with Microsoft.AspNetCore.Mvc.ValidateAntiForgeryTokenAttribute.

• AspNetAntiforgery and AspNetAntiforgeryOptions were removed.

EPiServer.Web hosting

• EPiServer.Web.IWebHostingEnvironment – Obsolete. WebRootPath can be retrieved from Microsoft.AspNetCore.Hosting.IWebHostEnvironment. WebRootVirtualPath is no longer needed because support for virtual application paths was dropped with CMS 12.

• EPiServer.Web.WebHostingEnvironment – Obsolete.

• EPiServer.Web.VirtualPathResolver – Obsolete.

EPiServer.Data

• EPiServer.Data.DataInitialization – No longer implements IConfigurableModule. Services are registered using the AddCmsData() service collection extension method.

• EPiServer.Data.Dynamic.EPiServerDataStoreAttribute – The SeamlessUpgrade property has a default value of true. Dynamic Data Stores defined using EPiServerDataStoreAttribute have seamless upgrade mode by default.

• EPiServer.Data.Dynamic.Providers.DataMove – The FromProperty and ToProperty fields were changed to properties.

• EPiServer.Data.IDatabaseExecutorExtensions – Extension methods GetParameterValue and SetParameterValue were moved to EPiServer.Data.DbCommandExtensions.

• EPiServer.Data.Cache.CacheChangedEventHandler – Delegate was not used and was removed.

• EPiServer.Data.Cache.DefaultCacheProvider – Made internal.

EPiServer.DataAccessBase

The helper base class is obsolete and is no longer supported. Use IDatabaseExecutor/IAsyncDatabaseExecutor directly instead.

EPiServer.HtmlParsing

• EPiServer.HtmlParsing.StringSource – Pushback method throws InvalidOperationException instead of IndexOutOfRangeException if currently reading on the first position.

EPiServer.Licensing

• EPiServer.Licensing.LicenseCheck – The protected SyncLock field was removed.

Validation

• EPiServer.Validation.IValidate – Services implementing IValidate or derived interfaces are no longer automatically registered as validators. Validation services must now be explicitly registered using the AddCmsValidator<T>() service collection extension method.

• EPiServer.Validation.DataAnnotationsValidator – The default constructor was obsoleted and throws an exception if used. Use the constructor that provides required service dependencies.

• EPiServer.Security.SecurityEntityProvider – Obsolete methods GetRolesForUser, FindUsersInRole, and Search were removed. The extension methods in SecurityEntityProviderExtensions (SearchRoles, SearchUsersByName, SearchUsersByEmail, GetUsersInRole, FindUsersInRole) were also removed. Use their async equivalents (SearchRolesAsync, SearchUsersByNameAsync, SearchUsersByEmailAsync, GetUsersInRoleAsync, FindUsersInRoleAsync).

• EPiServer.Framework.InitializableModuleAttribute – Property UninitializeOnShutdown removed. Uninitialize is always called on shutdown.

• EPiServer.Framework.SmtpOptions – Properties SenderEmailAddress and SenderDisplayName removed. These settings were never used; see NotificationOptions for notification sender configuration.

• EPiServer.ServiceLocation.ServiceCollectionExtensions – Non-generic AddServiceAccessor method removed. Use AddServiceAccessor<T>() instead.