Breaking changes in Optimizely Forms 6.0.0

When you upgrade to Optimizely Forms 6.0.0 (EPiServer.Forms 6.0.0), breaking changes can disrupt or alter your existing code, integrations, or customizations. Address each breaking change to ensure a smooth transition and continued Forms operation.

🚧

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 may need updates.
• Subclasses of DecryptedCSVDataExporter or AzureKeyVaultCryptoEngine should verify constructor compatibility.
• Optimizely Forms 6.0.0 is not designed to work with Experience.

Breaking changes

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. If your code uses helper methods that are not part of the public API (such as ContentExtensions.GetPropertyValueAsString or UriExtensions.IsValidUri), reimplement the required behavior using supported public APIs. For content property value retrieval, use standard CMS APIs or create custom helper methods built on those APIs. For URI validation, use System.Uri.TryCreate() or similar .NET APIs.

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 legacy 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 depending on ConfigureContainer being called will break.
• Migration – Call services.AddForms(), services.AddFormsUI(), or services.AddFormsCore() in Program.cs.

Required explicit DI registration

• Type – Breaking (DI configuration).
• Details – Services are no longer auto-registered with [ServiceConfiguration]. The following new 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 is 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 may 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.

Enhancements

• IFormEventsRaiser and DefaultFormEventsRaiser – Added a new IFormEventsRaiser interface in EPiServer.Forms.Core.Events, which adds OnFormSubmittedEvent and OnFormSubmittingEvent. OnFormSubmittingEvent returns the new 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 new TinyMCE plugin for ParagraphTextElementBlock, which lets you insert form field placeholders in Visual Builder mode rich-text editing.
• FormsSmtpClient – Added new internal FormsSmtpClient, which uses MailKit and adds ReplyTo field support for email actors.
• Visual Builder mode improvements – Improved and corrected the functionality of 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.

Non-breaking changes

• 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).

API changes summary

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

• Serialization format – PropertyGenericList<T> now uses System.Text.Json with camelCase. Data stored with Newtonsoft.Json may not deserialize 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.