Version Specific Upgrade Notes
Get an overview of the things changes and fixed in each version of Umbraco Forms.
This page covers specific upgrade documentation for specific versions.
If you are upgrading to a new minor or patch version, you can find information about the breaking changes in the Release Notes article.
Version 12 of Umbraco Forms has a minimum dependency on Umbraco CMS core of
12.0.0
. It runs on .NET 7.Breaking changes
Version 12 contains a number of breaking changes. If you do run into any, they should be straightforward to adjust and recompile.
For reference, the full details are listed here:
Behavior
- The default value for configuration of request IP tracking has been changed to
None
fromRemoteIpAddress
. - The session variable
ContourMemberKey
is no longer set. - Exception handling in the Forms API has been aligned with the CMS Delivery API. This leads to subtle differences in the population of the
ProblemDetails
exposed. - Use of the Forms API has to be enabled in configuration, via setting the
Umbraco:Forms:Options:EnableFormsApi
key totrue
. - The Swagger document for the Forms API has been removed and is now combined with that for the CMS Delivery API, at
umbraco/swagger/index.html
. - The Forms API paths have had the
/v1.0/
segment renamed to/v1/
, to align with the CMS Delivery API.
Dependencies
- Umbraco CMS dependency was updated to
12.0.0
. - The dependency on
Hellang.Middleware.ProblemDetails
was removed. - The dependency on
NSwag.AspNetCore
was removed and replaced withSwashbuckle.AspNetCore
.
Code
The following updates describe the more significant changes to the codebase and public API:
- The interfaces that previously defined entity model classes have been removed. These were
IFormEntity
,IFolderEntity
,IWorkflowEntity
,IDataSourceEntity
andIPrevalueSourceEntity
. All code now refers to the concrete classes. - The interfaces that previously defined application model classes have been removed. These were
IFieldPreValueSource
,IFormDataSource
,IFormDataSourceField
,IWorkflow
,IRecordField
andIRecord
. - These changes affect service, repository and other interfaces and classes that previously used these interfaces. All methods have been updated to use the concrete classes as parameters and return values.
- The now unused class
InterfaceJsonConverter
was removed.
These updates are more minor. We don't expect many projects to be affected by them as they are in areas that are not typical extension points:
- The obsolete constant
FormsConfigPath
was removed. - Obsolete constructor was removed on
DictionaryHelper
. - Obsolete overloads of
StringExtensions.ParsePlaceHolders
was removed. - Unused parameter in the constructors of
DatabaseIntegrityHealthCheck
andMsSqlAnalyzer
were removed. - Default interface implementations were removed from the
MessageOnSubmitIsHtml
,DisplayDefaultFields
andSelectedDisplayFields
properties defined onIFormEntity
. - The
SearchForms
method, previously defined in the implementation ofIFormService
, has been added to the interface. - An obsolete method on
IPlaceholderParsingService
were removed. - An obsolete method on
IWorkflowService
were removed. - Obsolete methods on
UmbracoBuilderExtensions
were removed. - The obsolete constructors on
BaseEmailWorkflowType
,SendEmail
,SendRazorEmail
andSendXsltEmail
workflows were removed. - The obsolete constructors on
FormsApiControllerBase
,DefinitionsController
andEntriesController
API controllers were removed. - The obsolete constructors on
UmbracoFormsController
were removed. - The obsolete constructors on
FieldController
andRecordController
were removed. - The obsolete overload on the
ViewHelper.RenderPartialViewToString
method was removed and theFakeController
class used in this method was made private. - The obsolete
Build
method overload was removed inFormViewModel
. - The obsolete constructor on
FormRenderingService
was removed. - The Forms API model classes and serialization customizations were moved from
Umbraco.Forms.Web
intoUmbraco.Forms.Core
. - The
ISupportFileUploads
interface was moved toUmbraco.Forms.Core.Interfaces
. - Additional parameters were added to the constructors of
FormPickerPropertyValueConverter
andFormDtoFactory
. - The setting properties available on all field, workflow and other provider types have been made virtual.
Version 11 of Umbraco Forms has a minimum dependency on Umbraco CMS core of
11.0.0
. It runs on .NET 7.Breaking changes
Version 11 contains a number of breaking changes. We don't expect many projects to be affected by them as they are in areas that are not typical extension points. For reference though, the full details are listed here:
Presentation
- A CSS class for each field is rendered out matching the caption of the form field. This has been changed to use the alias of the form field, as this is considered less likely to change and potentially break custom styles.
Code
- The int
DeleteFormRecords(Form form, FormState formState, DateTime deleteRecordsCreatedEarlierThan)
method was added toIRecordStorage
. - Name of
FormsUmbracoBuiderExtensions
was corrected toFormsUmbracoBuilderExtensions
. - The method
RegenerateFormStructureIds
on Form was amended to return a response. - The method void
ExecuteWorkflows(List<IWorkflow> workflows, Record record, Form form, FormState state)
was added toIWorkflowExecutionService
. - Obsolete constructor on
PlaceholderParsingService
removed. - Obsolete constructor on
ServerVariablesParsingHandler
removed. IsMandatory
andCondition
properties were added to theIWorkflow
andIWorkflowEntity
interface.DaysToRetainSubmittedRecordsFor
andDaysToRetainApprovedRecordsForproperties
were added to theIFormEntity
interface.- Obsolete constructor on the export type
ExportToExcel
removed. - Obsolete constructor on the workflow type
SendRazorEmail
removed. - Obsolete constructor on the controllers
UmbracoFormsController
,ExportController
,FieldController
,FormController
,RecordController
, andEmailTemplateTreeController
removed. - Duplicate method
GetAllDocumentTypesWithAlias
inPickerController
was removed. - Obsolete overloads to the
Build
method onFormViewModel
were removed. - Obsolete constructor on
FormRenderingService
was removed. - Legacy storage of prevalues with captions using a single string with a separator was updated to store them as an object with a value and caption.
- A
JsonConverter
was added toFormsJsonSerializerSettings
that will convert forms saved in older versions with the string storage into the new structure. - The public field
Field.PrevalueCaptionSeparator
was removed. Field.Prevalues
now returnsIEnumerable<FieldPrevalue>
instead ofIEnumerable<string>
, and the propertyField.ParsedPreValues
was removed.
- The obsolete overload of the methods
Test
andTestRule
inFieldConditionEvaluation
was removed and the existing method made private. - The obsolete overload of the method
IsVisible
inFieldConditionEvaluation
was removed. - The property
ConditionCheckFunctions
was added to theIFieldType
interface. - The property
Alias
was added to the interfaces for all provider types inheriting fromProviderBase
. - The additional method
GetRecordsFromFormForMember
was added to the interfaceIRecordReaderService
.
Breaking changes
- The default theme has been updated to render captions for field types that support prevalues. If you have created any custom themes, please review the default theme and ensure you make similar changes to make use of the new feature.
- The method
PreValues
on theFieldViewModel
type has been changed from a collection of strings to a collection of aPrevalueViewModel
object that has a Value and Caption property. - In order to fix an issue with display and editing of values, we've found a need to ensure the property representing the fields a record entry used in the backoffice is changed from a list of values to a structure containing the field Ids and values. Specifically,
EntrySearchResult.Fields
has changed typeIEnumerable<object?>
toIEnumerable<EntrySearchResult.FieldData>
. The only scenarios affected by this would be anyone handling theEntrySearchResultFetchingNotification
notification or developing custom export types.
Version 10 of Umbraco Forms has a minimum dependency on Umbraco CMS core of
10.0.0
. It runs on .NET 6.To migrate to version 10, you should first update to the latest minor release of version 9. If you are upgrading from Umbraco 8, update Forms to the latest minor version of Forms 8. Ensure you have the configuration in place for storing form definitions in the database. For more information, see the Umbraco Forms in the Database (legacy) article.
Either way will ensure you have all the database schema changes in place.
Views and client-side files
Umbraco 10 distributes the views and client-side files as part of a Razor class library, distributed in the Umbraco.Forms.StaticAssets package. This means these assets are no longer individual files available on disk. The advantage of this approach is that that avoids changes made to them by solution developers being inadvertently lost when the project is rebuilt.
When upgrading from Forms 9, you should either first run a
dotnet clean
, or, after installing Forms 10, delete the App_Plugins/UmbracoForms
folder. This will ensure there aren't two copies of the package.manifest
file, which would cause issues by registering duplicate property editors.For views you should also remove the following folders and files (again, either via a
dotnet clean
before upgrading, or manually afterward):/Views/MacroPartials/InsertUmbracoFormWithTheme.cshtml
/Views/MacroPartials/RenderUmbracoFormScripts.cshtml
/Views/Partials/Forms/
If you have custom themes or other changes to the files in the
Views/Partials/Forms
folder, you should ensure those files remain.For example, with a custom email template, remove the file
Example-Template.cshtml
from the /Views/Forms/Emails
folder but keep any custom templates.Similarly, if you have a custom theme, remove the
default
and bootstrap3-horizontal
folders from the /Views/Partials/Forms/Themes/
folder but keep any custom theme folders.Breaking changes
Version 10 contains a number of breaking changes. We do not expect many projects to be affected by them as they are in areas that are not typical extension points. For reference though, the full details are listed here.
Configuration
- Renamed the configuration option to allow editable form submissions on the front-end to
AllowEditableFormSubmissions
(fixing the typo in the previous value ofAllowEditableFormSubmissions
).
Code
DatabaseIntegrityHealthCheck
has an altered constructor taking an additional parameter.- The
EventExtensions
class is no longer used since V9 and has been removed. - Static events from
BaseFileStorage
removed and replaced with notifications. IFormTemplateStorage
along with its implementation inFormTemplateStorage
and base classes have been simplified, as templates are the only file based storage now in use, and there are no methods necessary for this other than reading.- The method
GetScaffold
has been removed fromFormController
, as it's not called from the UI. - The following classes have altered constructors taking additional parameters, with obsolete versions removed.
RecordController
FormSecurityController
FormSecurityTreeController
PostToUrl
WorkflowEmailService
- The public fields on the
Setting
class have been converted to properties. - The methods
GetMemberCacheKey
andGetMemberValuesCacheKey
onCacheKeys
taking an integer parameter have been removed. - The method
GetUserSecurity
onIUserSecurityStorage
has been amended to take an integer parameter rather than an object. - The method
StringExtensions.DetectIsJson
has been removed (the equivalent exists in CMS). - Obsoleted methods in
FieldConditionEvaluation
have been removed. - The following unused classes have been removed:
FormEventArgs
FolderEventArgs
FieldPreValueSourceEventArgs
FormDataSourceEventArgs
WorkflowEventArgs
BaseStorageEventArgs
Additional methods have been added to the following interfaces:IRecordStorage
IRecordFieldValueStorage
IUserSecurityStorage
IUserFormSecurityStorage
IFormsSecurity
- Additional properties of
SupportsMandatory
andEditType
have been added to theIFieldType
interface. - The obsoleted method
RegenerateFieldSetAndFieldIds
onForm
has been removed. - The constructor of
FolderNotificationHandler
had an unused parameter removed. - The obsolete and unused methods
CanCurrentUserEdit
,CanCurrentUserAddInEditor
,CanCurrentUserManageWorkflows
,EnsureUserExist
s andCanCurrentUserExport
were removed from theIFormSecurity
interface. - The type parameter
TEventArgs
defined onIBaseService
(and derived interfaces) has been removed. - Database migration classes inheriting from
FormsMigrationBase
now use the non-obsolete base constructor defined onPackageMigrationBase
. - The methods on
IPlaceholderParsingService
have been combined into a single one with optional parameters. - The method
PostSave
onFormSecurityController
has been renamed toPostSaveForUser
. - The backoffice model class
FormSecurity
has been renamed toFormSecurityForUser
. - The unused class
NonSerialiazableTypeSurrogateSelector
was removed. - The unused method
ImportXmlNodeFromText
onXmlHelper
was removed. IFormService.FormExist
was renamed toIFormService.FormExists
.EntrySearchResultCollection.schema
was capitalized.- Base class
ExportType
has a constructor takingIHostEnvironment
instead ofIHostingEnvironment
. - Typo was fixed in the class name of
TempDataDictionraryExtensions
. - The
SetFormThemeCssFile
extension method had an unused variable removed. - Some method signatures have had appropriate modifications for nullable reference type support.
- Removed
BaseFileStorage
,BaseFileSystemStorage
andFormsFileSystemForPackageData
as they are no longer needed following changes to support distribution of assets in a razor class library.
Version 8 of Umbraco Forms has a minimum dependency on Umbraco CMS core of
8.0.0
and runs on .NET Framework 7.2.In order to upgrade from Umbraco Forms 7 to Umbraco Forms 8, you can use any of these options:
In order to upgrade you will want to download the version of Forms you wish to upgrade to. Instead of downloading the actual package, however, you want to download the
Umbraco.Forms.Files.x.y.z.zip
file (where x.y.z) is the version.The filename ends with
.Files.x.y.z.zip
and contains only the files that get installed when you install Umbraco Forms.The easiest way to proceed is to unzip the file you downloaded and copy and overwrite (almost) everything into your website. Almost, because you might not want to overwrite
~/App_Plugins/UmbracoForms/UmbracoForms.config
because you might have updated it in the past. Make sure to compare your current version to the version in the zip file you downloaded. If there's any new configuration options in there then copy those into your website's UmbracoForms.config
file.You can upgrade to the latest version of Umbraco Forms through:
Forms allows you to stay in sync with the latest releases, so you can take advantage of the new features and bug fixes.
Checking for updates
You won't have to check for updates manually. Umbraco Forms will inform you when a new update is available. Navigate to the Forms dashboard and if you see the following then a new version is already available.

Installing update
To upgrade your installation hit the upgrade now button.

Umbraco will now fetch and install the upgrade.

Once it's completed the upgrade notification should be gone and you can continue using a newly updated Umbraco Forms.
In order to upgrade you will want to download the version of Forms you wish to upgrade to. Instead of downloading the actual package, however, you want to download the
UmbracoForms.Files.x.y.z.zip
file (where x.y.z) is the version.The filename ends with
.Files.x.y.z.zip
and contains only the files that get installed when you install Umbraco Forms.Copy
Unzip the file you downloaded and copy and overwrite (almost) everything into your website. Almost, because you might not want to overwrite
~/App_Plugins/UmbracoForms/UmbracoForms.config
because you might have updated it in the past. Make sure to compare your current version to the version in the zip file you downloaded. If there's any new configuration options in there then copy those into your website's UmbracoForms.config
file.Upgrade marker
Finally, you'll need to tell Umbraco Forms to update itself when you start the website next. In order to do that you need to have a
formsupdate
file (an empty text file without extension) in ~/App_Data/TEMP/
. The easiest way to create this file is by going into the root folder of your website and start a command line there. You can then type the following command: echo > /App_Data/TEMP/formsupdate
.This command creates the file and you should see it disappear the next time the website recycles. You may want to recycle the website manually after creating this file. If the file isn't automatically removed, it is safe to remove it manually.
That's it! You're all set.
Upgrading to Version 6 of Umbraco Forms, has a higher minimum dependency on Umbraco CMS core of
7.6.0
& higher. The reasoning behind this is due to some underlying changes to ensure Forms works with Umbraco Cloud & Deploy.With Umbraco you have many options to upgrade Umbraco Forms.
- You can install the Forms package via the community package search from within the Developer Tab in the CMS.
- You can download a
.zip
file containing the updated files which you can unzip & apply over the top of your existing install. - You can upgrade Forms using NuGet. Doing this will require a few more steps, which you can find in the next section.
Upgrading with NuGet
Using NuGet to perform an the Forms major upgrade, you will see that the legacy MacroPartial view is removed from the site. This causes any existing Umbraco Forms rendered on the site to stop functioning.
Before running the site after the NuGet upgrade again; consider this may need to be done on each environment depending on your deployment process/setup. You will need to copy/restore the following file
Views/MacroPartials/InsertUmbracoForm.cshtml
from your source control solution.The file needs to be here before the site is restarted - due to the migration/upgrade tasks listed below.
Upgrade tasks
The following outlines for
version 6.0.0
what upgrade/migration tasks that are being performed:- Rename legacy macro to make it easier to identify in the backoffice.
- Adds new form macro to insert a form with a theme.
- Moves JSON Form Storage files from
App_Plugins/UmbracoForms/Data
toApp_Data/UmbracoForms/Data
by default unless a custom Forms IFileSystem is configured such as Azure blob storage. - Moves any Form PreValue sources that uses text files that were uploaded to the media section & now stores in the Umbraco Forms IFileSystem.
Recommendation
We recommend you make the switch away from the legacy macro and swap over to the newer macro that supports Themes. The legacy macro is there to ease the transition over and to avoid entire sites forms to stop working.
Last modified 2mo ago