Breaking changes in Optimizely Forms 6.0.0
21 min
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.
- 🚧 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<T> 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<string, RemoteFieldInfo> 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<string, object>)
- ReCalculateStepIndex(FormContainerBlock, int, IDictionary<string, object>, 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<TModel>(ControllerContext, string, TModel, IDictionary<string, object>).
- Impact – Callers fail to compile.
- Migration – Use standard ASP.NET Core view rendering.
Removed FormsExtensionsUI.RenderFormElements
- Type – Removed.
- Details – Removed RenderFormElements(IHtmlHelper, int, IEnumerable<IFormElement>).
- 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<string, object>).
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<T> now uses System.Text.Json. [JsonIgnore] is now System.Text.Json.Serialization.JsonIgnore.
- Impact – Custom model types in PropertyGenericList<T> 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<T>.
- XhtmlStringJsonConverter – Added EPiServer.Forms.UI.Internal.XhtmlStringJsonConverter, which supports XhtmlString serialization inside PropertyGenericList<T>.
- 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
- 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<T>.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<T> 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.