---
title: Forms 3 - Breaking changes
slug: cms-12/docs/forms-3-breaking-changes
docTags: 
createdAt: 2026-08-10T15:55:57.000Z
---

:::hint{type="info"}
**Note**
[Optimizely Forms](docId:3SbSlJZIS_3iFmghfQA3J) is supported by MVC-based websites only.
:::

Changes to Forms include separating the Forms add-on into three smaller packages that follow the CMS code structure: `EPiServer.Forms.Core` (referred to as *Core*), `EPiServer.Forms.UI` (referred to as *UI*), and `EPiServer.Forms` (referred to as *Forms*).

- The Core package exposes all back-end code composed of the core interfaces and classes, which third parties can override and extend.
- The UI package contains the classes and typical resources for a web project, such as modules-content, config, or an installation script. This package is used to render the edit mode.
- The Forms package, which depends on the others, comprises the resources needed to render the ViewMode.

This separation lets third-party developers simplify and shorten the installation process of the NuGet packages and remove unused components for their purposes. For example, suppose you want to customize form elements, install the Core and UI package so that the web-related Forms components are not included in a project. In that case, this shortens installation time and makes the code structure simpler and smaller. The following breaking changes are described in this topic in greater detail.

- The utility functions of add-ons development were moved to a project named `EPiServer.AddOns.Helpers` (referred to as *Helpers*). There are two main purposes for doing this.
  - The Helpers is beneficial to the add-on development.
  - The separation helps to avoid the breaking changes in the Forms add-on and other ones in case major changes for utility functions are required to fit requirements.
- Episerver changed the signature of important methods in interfaces or classes to make them simpler and more generic. Episerver added more functions to interfaces or base classes to satisfy extension requirements proposed by clients who had used previous versions of the Forms add-on. Episerver changed portions of the `FormsExtension` class. The extension methods of generic class types (such as `Object`) now become the static methods of the class, while the ones for specific class types are mostly kept the same.

## EPiServer.Form.Core

### Main components:

The Core package now is a standalone NuGet package (DLL library and configuration only) and contains the following interfaces and base classes.

- Events
- Data
- FormRepository
- Abstraction of Configuration
  - Settings in DDS
- Internal
  - Feed API
  - Autofill API (BETA)
  - ExternalSystem API (BETA)
  - VisitorIdentity API (BETA)
  - PlaceholderService
- Models
- Autofill
- External System (Field mapping)
- Event (server-side events, Form Structure event, and Form Structure Handler)
- Validation
- `VisitorData` and `VisitorDataService`
- Actor
  - `ActorsExecutingService`
  - `IPostSubmissionActor` and `IPostSubmissionActorModel`
- Constants

### API changes regarding the Core package.

- `EPiServer.Forms`. Describes classes moved to the UI project under this namespace.
  - `Constants`. The class defines the constants for the project
- `EPiServer.Forms.Core`. Describes classes moved to the UI project under this namespace.
  - `IUIEntityInEditView`. Defines UI entity of forms.
  - `IExcludeInSubmission`. Used to exclude the data submission.
  - `DependCondition`. Represents a dependent condition type.
- `EPiServer.Forms.Core.Validation`. Describes those classes moved to the UI project under this namespace or the one nested within it.
  - `IElementValidatable`. Defines properties and methods for the self-validation of form elements. Its new namespace is `EPiServer.Forms.Core.Validation`.
  - `ValidatorInfo` and `ValidationDescriptor `classes are used to represent the validator information of a form element. Their new namespace is `EPiServer.Forms.Core.Validation.Internal`.
  - `RegularExpressionValidationModel` and `RegularExpressionValidatorBase `classes: they define the base validation model for form elements. Their new namespace is `EPiServer.Forms.Core.Validation.Internal`.
  - `IValidationService `interface defines functions required for the data validation service.
  - `IElementValidator` interface and the class `ElementValidatorBase` respectively define and implement the function to build the validation model for form elements.
- `EPiServer.Forms.Core.Internal`. Describes those classes moved to the UI project under this namespace.
  - The class `JsonObjectConverter`. Defines the methods for reading and writing JSON data.
  - The class `DataSubmissionService`. Performs data submissions from users on the client side.
  - The class `FormBusinessService`. Calculates the next step to be displayed. You extract the function `GetAllDependee` from the class `FormsExtension` and add it to this class.
  - The class `ProgressiveSubmitInfoService`. Stores and retrieves the progressive submitted information. By default, the information is stored in browsers’ cookies.
  - `PlaceHolder`. An internal DTO object for replacing text holder with actual value.
  - `PlaceholderService`. Replaces placeholders such as `#summary#` with real values.
- `EPiServer.Forms.Core.Data`. Describes those classes moved to the UI project under this namespace.
- `IFormDataRepository`.
  Two data storage-related features let administrators set up read-only mode and let users choose whether the form data submission is stored through the **Allow to store data submission** property. Episerver added methods to the interface that let you return the right type of data storage services to clients in different contexts.
  The code also lets clients pass a submission storage for data operations, facilitating the need for form customization from clients.
- `EPiServer.Forms.Helpers.Internal`. Describes those classes moved to the UI project under this namespace.
  - `FormsExtensions` class. Contains the extension methods to retrieve and process data of forms and elements. Some methods of this class are moved to another one.
    - `GetCommonMessages` and `GetFormExternalResources` are moved to `FormContainerBlockController`.
    - `GetFieldsExcludedInSubmissionSummary`, `RenderTextWithEmptyPlaceHolders`, and `RenderTextWithPlaceHolders` are moved to the class `FormParagraphTextService`.
    - `HasAccessRightToReadFormData` is moved to `Addon.Helper`.
    - `GetSubmittableStatus` is changed to `GetFormSubmittableStatus` and moved to `SubmitButtonElementBlock`.
  - `CaptchaGenerator`. Generates images containing random text strings.
  - `ModuleHelper`. Provides the functions for mapping paths and the host environment.
  - `EPiServer.Forms.Configuration`. Describes those classes moved to the UI project under this namespace.
    - `Settings` class. Contains the global settings of `EpiForms`. The property `VisitorGroupProperties` is removed from the class `Settings`. That property of the class `BuiltinVisitorDataSourceConfig` should be enough.

## Forms.UI

### Main components

The UI package provides widgets, REST stores and services for Forms add-on in EditView; it contains the following main components.

- ShellModule
  - Dojo client resources for EditView widget
- Annotation
- EditView
  - Classes just for EditView and for serving Dojo widgets
  - Part of UI for manipulating forms in EditView.
  - Store
  - FormModuleModel
  - EditorDescriptors
  - CustomProperties
  - SelectionFactory
- Important base classes
  - BlockBase
  - ElementBlockBase
- ViewEngine
  - Razor
  - WebForms
- Actors implementation and its custom properties
  - WebhookActor
  - SendEmailActor

### API changes.

- `EPiServer.Forms.EditView`. Describes those classes moved to UI project under this namespace.
  - `IFeedConfig`. Exposes properties for the configuration of external feeds.
  - `IEPiServerFormsUIConfig`. Exposes properties for the configuration of Forms UI.
  - `FormsWebFormViewEngine`. Its namespace is changed to `EPiServer.Forms.EditView`.
  - `FormsRazorViewEngine`. Its namespace is changed to `EPiServer.Forms.EditView`.
  - `ConstantsFormsUI`. Contains constant values of the UI project.
  - `PropertyGenericList` class. Displays the user interfaces for configuring complex form elements such as `ImageChoice`, `Validator`, and so on. in EditView.
  - `ICustomViewLocation` interface and `CustomViewLocationBase` class. Sets up the default view location of Forms and Forms.Samples add-on.
  - `IElementHasFeedItems` interface. Defines the information required for a form element to have data as a feed of items.
- `EPiServer.Forms.EditView.Internal`. Describes those classes moved to the UI project under this namespace.
  - `ValidationService` class. Implements functions used for the form elements validation. Within this class, we add two more functions to extract the validator information of a form element.
    - `GetValidatorTypesIncludedForAnElementType`. Returns a list of validators used for a form element.
    - `GetValidatorTypesExcludedForAnElementType`. Returns a list of validators not used for a form element.
  - `ExternalFieldMappingService` class. Retrieves the information about external fields mapping to Forms and Form elements.
  - `DefaultFeedProvider` class. Provides the default type of an XML Feed and loads feeds from the configuration.
  - `FeedService` class. Accesses the Feeds and pre-configures the feed of items. Its new namespace is `EPiServer.Forms.EditView.Internal`.
  - `OAuthXmlFeed` class. Takes items from an XML string, enables the authentication fulfilling by OAuth, and fetches data from a remote URL.
  - `XmlFeed` class. Takes items from a `XmlString` and fetch data from the remote URL.
  - `FormStructureHandler`. Exposes API to handle changes regarding the Form structure.
- `EPiServer.Forms.EditView.Controllers`. Describes the controllers moved to the UI project under this namespace. Those only are used in EditMode, so they should be placed within the UI project.
  - `FormControllerBase` class. The base class for MVC controllers using the forms add-on.
  - `DataExportingController` class. Exports data and related functions.
  - `FormDataStore` class. Retrieves the information and data of forms and form elements.
  - `ExternalFeedStore` class. Retrieves the information from external data sources. Its new namespace is `EPiServer.Forms.EditView.Controllers`.
  - `FormsElementStore` class. Retrieves the form element information and is moved to the UI project.
  - `VisitorDataSourceStore` class. Retrieves visitor data.
- `EPiServer.Forms.EditView.DataTransfer`. Describes those classes moved to the UI project under this namespace.
  - `DataExporterBase` class. The base class for all data exporters. It defines the signature for the functions to export data in different formats.
  - `CSVDataExporter`. Exports data and CDV format. (Default)
  - `JSONDataExporter`. Exports data in JSON format.
  - `XMLDataExporter`. Exports data in XML format.
- `EPiServer.Forms.EditView.Models.Internal`. Describes those classes moved to the UI project under this namespace.
  - `IOptionItem` interface and `OptionItem` class. Represents an item of a selection element.
  - `StepDescriptor` class. Serializes the step information.
  - `ChartPeriodicity` class. Draws the chart only in EditView.
- `EPiServer.Forms.EditView.DataAnnotations`. Describes those classes moved to the UI project under this namespace.
  - `AvailableValidatorTypesAttribute` class. Defines validators for a specific form element to add to the project.
  - `LocalizedDisplayNameAttribute` class. Localizes the display name of a specific property.
- `EPiServer.Forms.Implementation`. Describes those classes moved to the UI project under this namespace or the one nested within it. Although the following classes belong to the UI project, the namespace `EPiServer.Forms.Implementation` remains to prevent so many changes in code for Episerver clients.
  - `FormStepBlock` class. Defines the main properties of a step.
  - Built-in WebHook: Changes the format of JSON data sent by this built-in to make `CallWebHookAfterSubmissionActor` more compatible with other systems in data transferring.
    - The JSON data now is a single JSON object, not a JSON array anymore.
      Example:

```javascript
  Version 2 format: [{"Key":"keyname","Value":"objectvalue"},{"Key2"...]
  Version 3 format: {"keyname":"objectvalue","keyname2"...}
```

## Forms

### Main components

This should be the default working web solution. With this package installed, an Editor can create a form immediately without requiring software development. The forms package depends on Core and UI using NuGet dependency. For this package, you still keep its name as `EPiServer.Forms`. People who install `EPiServer.Forms` will have the same result as Forms 2.0; an all-in-one working solution for Editor and Administrator of their sites. The main components of this package are listed below.

- Implementation of Configuration (in file) and Settings
- Fundamental ElementBlocks (Text, TextArea, SubmitButton, captcha, and so on.)
- ASCX View
- CAPTCHA Generator
- Validators
- Actors executing mechanism
- Data repositories
- Data exporters (XML, JSON, CSV)
- ClientResourceRegister
- Built-in VisitorDataSource (to silently collect data from visitors)
- Geo
- Profile
- UserAgent
- VisitorGroup
- Built-in CoreController and the custom route to this built-in controller

### API changes.

- Changed the module using geo-location data providers to extract the user information and save into the database.
- The current default geographical database, *Freegeo*, is replaced by *Maxmind Geo-ip*, which is bundled with `EpiServer.Personalization dll`. Episerver clients still can use the *FreeGeo* datasource as their default data provider by adding the following lines to the geo-location section of `web.config` and set `freegeo` as `defaultProvider`.

```xml
<geolocation defaultProvider="freegeo">
   <providers>
      <add name="freegeo" type="EPiServer.Forms.Internal.GeoData.FreeGeolocationProvider,       EPiServer.Forms" geoApiUrl="http://freegeoip.net/json/{0}" />
   </providers>
</geolocation>
```

- New exposed API lets you choose different geo-location data providers for his site.
- Create a geo-location provider class that inherits `EPiServer.Personalization.GeolocationProviderBase` and `EPiServer.Forms.Implementation.Providers.GeolocationProviders.ICustomGeolocationProvider`.
- Create a `GeoDataProcessService` that inherits `EPiServer.Forms.Internal.GeoDataProcessService.IGeoDataProcessService`.
- Configure the provider in `web.config` by adding the following line to geo-location section and `set defaultProvider=”ProviderName”` and then, add the following line:

```xml
<add name="[ProviderName]" type="[fully_qualified_class_name, AssemblyName]"/>
```

- Added a `FormParagraphTextService` class that replaces a placeholder with `FormElement`'s value.
- Added a `GetFormSubmittableStatus` method to the `SubmitButtonElementBlock` class. This method checks whether its form container can be submitted for a given form element.
- `PlaceHolderManager` is marked as Obsolete.
- `SubmissionSummaryElementBlockBase` is marked as Obsolete. (`IExcludeInSubmission` should be enough.)
- The namespace of `IViewModeExternalResources` is changed to `EPiServer.Forms.Implementation`.
- The namespace of `FormStep` and `FormContainerBlock` is still kept as `EPiServer.Forms.Implementation.Elements.`