--- title: Breaking changes in Optimizely Forms 6.0.0 slug: cms-13/docs/forms-6.0.0-changes docTags: createdAt: 2026-07-30T20:22:03.194Z --- Optimizely Forms 6.0.0 (EPiServer.Forms 6.0.0) introduces breaking changes that affect existing code, integrations, and customizations. Address each change before upgrading to avoid build failures and runtime errors. :::hint{type="warning"} - **Important** Optimizely Forms 6.0.0 targets CMS 13. Many breaking API changes result from CMS 13 in addition to Forms-specific changes. - The `PropertyGenericList` serialization format change is high risk. Test existing form data before upgrading. - Subclasses that accessed `Injected<>` fields directly on `FormBusinessService`, `FormContainerBlockController`, and similar classes require updates. - Subclasses of `DecryptedCSVDataExporter` or `AzureKeyVaultCryptoEngine` require constructor compatibility verification. - Optimizely Forms 6.0.0 does not work with Experience. ::: ## Breaking changes Each entry describes what changed, the impact on existing code, and the required migration step. ### Removed `EPiServer.AddOns.Helpers` NuGet package - **Type** – Removed. - **Details** – Deleted the `EPiServer.AddOns.Helpers` project. Its helper types (`ContentExtensions`, `UriExtensions`) were moved into core Forms assemblies. - **Impact** – Code referencing `EPiServer.AddOns.Helpers` as a NuGet dependency will fail to build. - **Migration** – Remove the package reference. Replace non-public helper methods such as `ContentExtensions.GetPropertyValueAsString` and `UriExtensions.IsValidUri` with supported alternatives. Use standard CMS APIs for content property retrieval and `System.Uri.TryCreate()` for URI validation. ### Removed `IEPiServerFormsCoreConfig` interface - **Type** – Removed. - **Details** – Deleted `EPiServer.Forms.Core.IEPiServerFormsCoreConfig` and `EPiServerFormsCoreConfig`. - **Impact** – Code injecting or implementing `IEPiServerFormsCoreConfig` will fail to compile. - **Migration** – Use `FormsConfigOptions` (options class, configurable in `appsettings.json` under the `Forms` key). ### Removed `EPiServerFormsUIConfig` class - **Type** – Removed. - **Details** – Deleted `EPiServer.Forms.UI.EPiServerFormsUIConfig`. - **Impact** – Code injecting `IEPiServerFormsUIConfig` will fail to compile. - **Migration** – Use `FormsConfigOptions`. ### Removed XML configuration - **Type** – Removed. - **Details** – Removed the entire `EPiServer.Forms.Configuration` namespace, `Forms.config`, and all `Transform/` classes. - **Impact** – `Forms.config` settings are ignored. Code using the `EPiServer.Forms.Configuration` namespace fails to compile. - **Migration** – Move all settings to `appsettings.json` under the `Forms` key. See `FormsConfigOptions` for all available properties. ### Changed `InitializationModule` to no longer implement `IConfigurableModule` - **Type** – Changed. - **Details** – Changed `EPiServer.Forms.EditView.InitializationModule` from `IConfigurableModule` to `IInitializableModule`. Removed `ConfigureContainer()`. Deleted `EPiServer.Forms.InitializationModule`. - **Impact** – Code that depends on `ConfigureContainer` breaks at runtime. - **Migration** – Call `services.AddForms()`, `services.AddFormsUI()`, or `services.AddFormsCore()` in `Program.cs`. ### Required explicit DI registration - **Type** – Breaking (DI configuration). - **Details** – Forms no longer auto-registers services with `[ServiceConfiguration]`. The following extension methods are required: - `services.AddFormsCore()` — Core services. - `services.AddFormsUI()` — UI services (calls `AddFormsCore`). - `services.AddForms()` — Full stack (calls `AddFormsUI`). - `services.AddFormsCryptoAzureKeyVault()` — Azure Key Vault crypto. - **Impact** – Missing registration causes a runtime `InvalidOperationException` with an *"Unable to resolve service..."* message. - **Migration** – Call `services.AddForms()` in `Program.cs` or `Startup.cs`. ### Removed `IPostSubmissionActor.ActiveExternalFieldMappingTable` - **Type** – Removed. - **Details** – Removed `IDictionary` `ActiveExternalFieldMappingTable` from `IPostSubmissionActor` and its base class (previously marked `[Obsolete]`). - **Impact** – Custom actors reading this property fail to compile. - **Migration** – Inject `IExternalFieldMappingService` and call `GetActiveFieldMappingTable(FormIdentity)` directly. ### Removed `IExternalFieldMappingService.GetAllExternalSystems()` - **Type** – Removed. - **Details** – Removed the method (previously marked `[Obsolete]`). - **Impact** – Callers fail to compile. - **Migration** – Use `ExternalSystemService.GetAllExternalSystems()`. ### Removed `[ServiceConfiguration]` from `FormsEvents` and `CryptoEngineFactory` - **Type** – Changed. - **Details** – Both classes no longer carry `[ServiceConfiguration]` attributes. They are registered through `AddFormsCore()`. - **Impact** – If `AddFormsCore()` is not called, these services are not registered. - **Migration** – Call `services.AddFormsCore()`. ### Removed obsolete methods from `FormBusinessService` - **Type** – Removed. - **Details** – Removed the following methods (all previously marked `[Obsolete]`): - `ReCalculateStepIndexIfNeeded(FormIdentity, FormContainerBlock, Submission, int, Guid, bool)` - `IsMatchDependCondition(IElementDependant, IDictionary)` - `ReCalculateStepIndex(FormContainerBlock, int, IDictionary, bool)` - `BuildStepsAndElements(FormContainerBlock, bool)` (legacy overload) - `ToHtmlStringWithFriendlyUrls(XhtmlString)` - `ReplaceFragmentWithFriendlyUrls(IStringFragment)` - `GetFriendlyUrl(IStringFragment)` (protected virtual) - **Impact** – Callers fail to compile. - **Migration** – Use the replacement methods documented in the original `[Obsolete]` messages. ### Removed `DataSubmissionHelper.ValidateFormSubmittableStatus` four-parameter overload - **Type** – Removed. - **Details** – Removed `ValidateFormSubmittableStatus(FormContainerBlock, string, HttpContext, out string)` (previously marked `[Obsolete]`). - **Impact** – Callers fail to compile. - **Migration** – Use the five-parameter overload and add the `string submissionGuid` parameter. ### Removed `FormsExtensionsUI.RenderWebFormViewToString` - **Type** – Removed. - **Details** – Removed `RenderWebFormViewToString(ControllerContext, string, TModel, IDictionary)`. - **Impact** – Callers fail to compile. - **Migration** – Use standard ASP.NET Core view rendering. ### Removed `FormsExtensionsUI.RenderFormElements` - **Type** – Removed. - **Details** – Removed `RenderFormElements(IHtmlHelper, int, IEnumerable)`. - **Impact** – Callers fail to compile. - **Migration** – Use `EPiServer.Forms.Helpers.Internal.HtmlExtensions.RenderFormElements()`. ### Removed `IExcludeValidatorTypes` interface - **Type** – Removed. - **Details** – Removed `EPiServer.Forms.EditView.IExcludeValidatorTypes` and `ValidatorTypesToBeExcluded` (previously marked `[Obsolete]` since Forms 3.0). Also removed support logic in `ValidationService`. - **Impact** – Element blocks implementing `IExcludeValidatorTypes` fail to compile. - **Migration** – Use `IAvailableValidatorTypesAttribute` instead. ### Removed `ExternalSystemEditorDescriptors.GetSelectedFieldsName(FormIdentity, string)` - **Type** – Removed. - **Details** – Removed the protected `GetSelectedFieldsName(FormIdentity, string)` overload (previously marked `[Obsolete]`). - **Impact** – Subclasses calling this overload fail to compile. - **Migration** – Use `GetSelectedFieldsName(FormContainerBlock, ElementBlockBase, string)`. ### Removed protected virtual event handlers from `InitializationModule` - **Type** – Removed. - **Details** – Removed `Instance_DeletedContent` and `Instance_PublishedContent` (previously marked `[Obsolete]`). - **Impact** – Subclasses overriding these methods fail to compile. - **Migration** – Override methods in `_cmsEventsHandler` or subscribe to CMS events directly. ### Removed `FormsExtensions.HasAnyExternalSystem()` - **Type** – Removed. - **Details** – Removed `FormsExtensions.HasAnyExternalSystem()`. - **Impact** – Callers fail to compile. - **Migration** – Use `ExternalSystemService.HasExternalSystem()`. ### Removed `FormsExtensions.GetContent(ContentReference, string)` overload - **Type** – Removed. - **Details** – Removed `FormsExtensions.GetContent(ContentReference, string)` overload. - **Impact** – Callers fail to compile. - **Migration** – Use `GetContent(ContentReference, bool shouldFallbackWithMaster, string language)`. ### Removed `FormsExtensions.SplitBySeparator` - **Type** – Removed. - **Details** – Removed `FormsExtensions.SplitBySeparator`. - **Impact** – Callers fail to compile. - **Migration** – Use `SplitBySeparators(this string, string[])`. ### Removed `PropertyBag Data` from `IForm.Data` and `Form.Data` - **Type** – Removed. - **Details** – Removed `PropertyBag Data` from `IForm` and `Form` (previously marked `[Obsolete]` since Forms 5.0). - **Impact** – Callers fail to compile. - **Migration** – Use `Submission.Data` (`IDictionary`). ### Changed `[ScheduledPlugIn]` to `[ScheduledJob]` - **Type** – Changed. - **Details** – `ExpiredFormSubmissionRemoveJob`, `UpdateMissingValueOfRetentionPolicyJob`, and `UpdateUploadFolderACLJob` now use `[ScheduledJob]` (CMS 13) and are internal. - **Impact** – External code referencing these types fails to compile. - **Migration** – Do not reference these types directly. Use `IScheduledJobRepository` or the CMS UI. ### Changed `[PropertyDefinitionTypePlugIn]` to `[PropertyDefinitionType]` on all specialized properties - **Type** – Changed. - **Details** – Changed all `SpecializedProperties` classes from `[PropertyDefinitionTypePlugIn]` to `[PropertyDefinitionType]`. Removed spaces from display names (for example, *Message Template* became *MessageTemplate*). - **Impact** – Database property definition mismatches on upgrade from CMS 12. - **Migration** – Verify property definitions in the CMS database after upgrading. ### Changed `PropertyGenericList.SaveData()` signature - **Type** – Changed. - **Details** – Changed `SaveData(PropertyDataCollection)` to the parameterless `SaveData()` in the CMS 13 API. - **Impact** – Subclasses overriding `SaveData(PropertyDataCollection)` fail to compile. - **Migration** – Override the parameterless `SaveData()`. ### Changed `FreeGeolocationProvider` to no longer inherit `GeolocationProviderBase` - **Type** – Changed. - **Details** – `FreeGeolocationProvider` now implements `ICustomGeolocationProvider` and `IGeolocationProvider` directly. Removed `Initialize(string, NameValueCollection)`. Configure `geoApiUrl` with options or dependency injection (DI). - **Impact** – XML-based geo provider configuration stops working without error. - **Migration** – Configure the geo API URL in `appsettings.json`. ### Replaced `IPageRouteHelper` with `IContentRouteHelper` - **Type** – Changed. - **Details** – `FormsExtensions.GetCurrentPageLink()` now uses `IContentRouteHelper` (CMS 13). - **Impact** – Potential behavioral difference in edge cases with non-page content. - **Migration** – No code change required unless you overrode this method. ### Removed `SaveDataToStorageActor` parameterless constructor - **Type** – Removed. - **Details** – Removed `SaveDataToStorageActor` parameterless constructor. - **Impact** – `new SaveDataToStorageActor()` fails to compile. - **Migration** – Let the DI container resolve `SaveDataToStorageActor`. ### Replaced `Newtonsoft.Json` dependency with `System.Text.Json` - **Type** – Removed and changed. - **Details** – Replaced all `Newtonsoft.Json` with `System.Text.Json`. `PropertyGenericList` now uses `System.Text.Json`. `[JsonIgnore]` is now `System.Text.Json.Serialization.JsonIgnore`. - **Impact** – Custom model types in `PropertyGenericList` that relied on `Newtonsoft.Json` conventions serialize or deserialize differently. - **Migration** – Review custom types for `System.Text.Json` compatibility, including differences in attributes, constructor requirements, and so on. ### Removed obsolete methods from `SendEmailAfterSubmissionActor` - **Type** – Removed. - **Details** – Removed `GetFriendlySummaryText` and `GetPredefinedPlaceHolders` (previously marked `[Obsolete]` since Forms 4.4). - **Impact** – Subclasses overriding these methods fail to compile. - **Migration** – This logic now lives in `DefaultPlaceHolderProvider`. Remove the overrides. ## Non-breaking changes These changes improve internal implementation and platform alignment without requiring code updates. - Updated `AesCrypto` to use `Aes.Create()` instead of the obsolete `AesManaged`. - Added non-generic `Encrypt(SymmetricAlgorithm, byte[])` and `Decrypt(SymmetricAlgorithm, byte[])` overloads to `SymmetricCryptoBase`. - Converted `FormCryptoEngineBase`, `FormRepository`, `FormDataRepository`, `DataSubmissionHelper`, `DataSubmissionService`, and `FormContainerBlockController` from `Injected<>` to constructor injection. - Updated `FormsExtensions.Reflection.cs` to scan `AppDomain.CurrentDomain.GetAssemblies()` and filter out Castle DynamicProxy proxy classes. - Updated `FreeGeolocationProvider` to use `System.Text.Json.JsonDocument` for geo API response parsing. - Improved styles for Visual Builder mode. - Replaced `IPlugInDescriptorRepository` with `IScheduledJobRepository` (CMS 13 API). - Replaced `context.Locate.Advanced` with `context.Services` (CMS 13 API). ## Enhancements Forms 6.0.0 adds APIs, serialization converters, and Visual Builder mode improvements that extend the platform without breaking existing functionality. - `IFormEventsRaiser` and `DefaultFormEventsRaiser` – Added `IFormEventsRaiser` interface in `EPiServer.Forms.Core.Events`, which adds `OnFormSubmittedEvent` and `OnFormSubmittingEvent`. `OnFormSubmittingEvent` returns the record type `FormSubmittingResult`. - `ContentReferenceJsonConverter` – Added `EPiServer.Forms.Core.Serialization.ContentReferenceJsonConverter` in the public API, which lets you enable `System.Text.Json` serialization of `ContentReference` inside `PropertyGenericList`. - `XhtmlStringJsonConverter` – Added `EPiServer.Forms.UI.Internal.XhtmlStringJsonConverter`, which supports `XhtmlString` serialization inside `PropertyGenericList`. - **TinyMCE placeholder plugin** – Registered the TinyMCE plugin for `ParagraphTextElementBlock`, which lets you insert form field placeholders in Visual Builder mode rich-text editing. - `FormsSmtpClient` – Added internal `FormsSmtpClient`, which uses MailKit and adds `ReplyTo` field support for email actors. - **Visual Builder mode improvements** – Fixed the dependency field dialog, field selector, validators editor, default view for form elements, and sticky view preferences in Visual Builder mode. - `AddFormsCryptoAzureKeyVault` – Added `AzureKeyVaultServiceCollectionExtensions.AddFormsCryptoAzureKeyVault(IServiceCollection)` extension method, which provides explicit Azure Key Vault DI registration. ## API changes summary Review the complete list of API additions, removals, and modifications in Forms 6.0.0. ### Added - `EPiServer.DependencyInjection.ServiceCollectionExtensions.AddFormsCore(IServiceCollection)` - `EPiServer.DependencyInjection.ServiceCollectionExtensions.AddFormsUI(IServiceCollection)` - `EPiServer.DependencyInjection.ServiceCollectionExtensions.AddForms(IServiceCollection)` - `EPiServer.DependencyInjection.AzureKeyVaultServiceCollectionExtensions.AddFormsCryptoAzureKeyVault(IServiceCollection)` - `EPiServer.Forms.Core.Events.IFormEventsRaiser` (interface) - `EPiServer.Forms.Core.Events.FormSubmittingResult` (record) - `EPiServer.Forms.Core.Serialization.ContentReferenceJsonConverter` ### Internal implementation changes (non-public or unsupported) - `EPiServer.Forms.UI.Internal.XhtmlStringJsonConverter` - `EPiServer.Forms.UI.Internal.FormsSmtpClient` ### Removed - `EPiServer.AddOns.Helpers` assembly - `IEPiServerFormsCoreConfig` and `EPiServerFormsCoreConfig` - `EPiServer.Forms.Configuration.*` namespace - `EPiServer.Forms.Transform.*` namespace - `EPiServer.Forms.EditView.IExcludeValidatorTypes` - `IPostSubmissionActor.ActiveExternalFieldMappingTable` - `IExternalFieldMappingService.GetAllExternalSystems()` - Multiple obsolete [FormBusinessService methods](docId\:LdMgdviP4KqcB6DFNCu2C) - `DataSubmissionHelper.ValidateFormSubmittableStatus` (four-parameter) - `FormsExtensionsUI.RenderWebFormViewToString`, `RenderFormElements` - `FormsExtensions.HasAnyExternalSystem()`, `GetContent` (two-parameter), `SplitBySeparator` - `IForm.Data` and `Form.Data` (PropertyBag) - `InitializationModule.ConfigureContainer`, `Instance_DeletedContent`, `Instance_PublishedContent` - `EPiServer.Forms.InitializationModule` class - `SaveDataToStorageActor()` parameterless constructor - `ExternalSystemEditorDescriptors.GetSelectedFieldsName(FormIdentity, string)` - `EPiServerFormsUIConfig` class - `SendEmailAfterSubmissionActor.GetFriendlySummaryText`, `GetPredefinedPlaceHolders` ### Modified - `PropertyGenericList.SaveData()` — Now parameterless. - `FreeGeolocationProvider` — No longer extends `GeolocationProviderBase`. - `FormsEvents` and `CryptoEngineFactory` — `[ServiceConfiguration]` removed. - **All scheduled jobs** — `[ScheduledPlugIn]` changed to `[ScheduledJob]`, `public` changed to `internal`. - `SpecializedProperties` — `[PropertyDefinitionTypePlugIn]` changed to `[PropertyDefinitionType]`. - `FormContainerBlockController` — Constructor injection. - `FormCryptoEngineBase` — Constructor injection. - `SendEmailAfterSubmissionActor._smtpClient` — `ISmtpClient` changed to `FormsSmtpClient`. *** ## Behavioral changes These runtime behavior differences affect how Forms operates after upgrading, even without API changes to your code. - **Serialization format** – `PropertyGenericList` now uses `System.Text.Json` with camelCase. Verify that data stored with `Newtonsoft.Json` deserializes correctly. - **Assembly scanning** – `AppDomain.CurrentDomain.GetAssemblies()` replaces `AssemblyScanner.GetScannableAssemblies()`. Proxy classes are filtered out. - **Geo provider registration** – Now uses `AddSingleton` (previously `TryAddSingleton`), overwriting any existing registration. - **Email sending** – MailKit (using the internal `FormsSmtpClient`) replaces `EPiServer.Notification.Internal.ISmtpClient` (available in the CMS 12 package). - **Default form element view** – Now `visualbuilderview` instead of `AllPropertiesView`.