---
title: Framework and platform breaking changes
slug: cms-13/docs/framework-and-platform-breaking-changes
docTags: 
createdAt: 2026-07-30T20:22:10.345Z
---

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 is integrated into the main `EPiServer.Data` assembly and removed as a separate package. Cache services are 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 are adjusted in places where the previous name was inconsistent with the overridden declaration or with other method overloads. Such changes are not 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:

| Type/Member                                            | Old Name                                | New Name                              |
| ------------------------------------------------------ | --------------------------------------- | ------------------------------------- |
| `IContentLanguageSettingsHandler.GetFallbackLanguages` | `conentLink`                            | `contentLink`                         |
| `IContentRepository.GetReferencesToContent`            | `includeDecendents`                     | `includeDescendants`                  |
| `ContentProvider.GetReferencesToLocalContent`          | `includeDecendents`                     | `includeDescendants`                  |
| `IPropertyDefinitionRepository.List`                   | `pageTypeID`                            | `contentTypeID`                       |
| `PropertyDefinitionRepository.List`                    | `pageTypeID`                            | `contentTypeID`                       |
| `PlugInSummaryAttribute` constructor                   | `moreInfourl`                           | `moreInfoUrl`                         |
| `SearchWordCriterionOptions.SearchStringRegexpression` | `SearchStringRegexpression`             | `SearchStringRegex`                   |
| `LanguageBranch.ValidateLanguageEdititingAccessRights` | `ValidateLanguageEdititingAccessRights` | `ValidateLanguageEditingAccessRights` |
| `VisitorGroupOptions.StatisticsPersistanceInterval`    | `StatisticsPersistanceInterval`         | `StatisticsPersistenceInterval`       |
| `VirutalPathResolverExtensions`                        | `VirutalPathResolverExtensions`         | `VirtualPathResolverExtensions`       |
| `ContentScannerExtension.AssignAvailableTypes`         | `contentypeModel`                       | `contentTypeModel`                    |
| `IFileTransferObject.CheckIn`                          | `commment`                              | `comment`                             |
| `PropertyLinkCollection.PrincipalAcccessor`            | `PrincipalAcccessor`                    | `PrincipalAccessor`                   |
| `DefaultContentTypeAvailablilityService`               | `Availablility`                         | `Availability`                        |

## 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:

| Namespace                                 | New Package                           | Registration Method          |
| ----------------------------------------- | ------------------------------------- | ---------------------------- |
| `EPiServer.Logging`                       | `EPiServer.Logging`                   | N/A                          |
| `EPiServer.HtmlParsing`                   | `EPiServer.HtmlParsing`               | N/A                          |
| `EPiServer.Personalization` (Geolocation) | `EPiServer.Geolocation`               | `AddCmsGeolocation()`        |
| `EPiServer.Events.ChangeNotification`     | `EPiServer.Events.ChangeNotification` | `AddCmsChangeNotification()` |
| `EPiServer.Framework.Blobs`               | `EPiServer.Blobs`                     | `AddCmsBlobs()`              |
| `EPiServer.Framework.Cache`               | `EPiServer.Cache`                     | `AddCmsCache()`              |

## 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.