Version specific upgrade notes
This page covers specific upgrade documentation for specific versions.
- 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
FieldViewModeltype has been changed from a collection of strings to a collection of a
PrevalueViewModelobject 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.Fieldshas changed type
IEnumerable<EntrySearchResult.FieldData>. The only scenarios affected by this would be anyone handling the
EntrySearchResultFetchingNotificationnotification 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 and ensure you have the configuration in place for storing form definitions in the database. For more information, see the Umbraco Forms in the Database 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, assuming you are using the default theme and templates, you should also remove the following folders and files (again, either via a
dotnet clean before upgrading, or manually afterward):
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
bootstrap3-horizontal folders from the
/Views/Partials/Forms/Themes/ folder but keep any custom theme folders.
Version 10 contains a number of breaking changes but we won'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.
- Renamed the configuration option to allow editable form submissions on the front-end to
AllowEditableFormSubmisisons(fixing the typo in the previous value of
DatabaseIntegrityHealthCheckhas an altered constructor taking an additional parameter.
EventExtensionsclass is no longer used since V9 and has been removed.
- Static events from
BaseFileStorageremoved and replaced with notifications.
IFormTemplateStoragealong with its implementation in
FormTemplateStorageand 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
GetScaffoldhas been removed from
FormController, as it's not called from the UI.
- The following classes have altered constructors taking additional parameters, with obsolete versions removed.
- The public fields on the
Settingclass have been converted to properties.
- The methods
CacheKeystaking an integer parameter have been removed.
- The method
IUserSecurityStoragehas been amended to take an integer parameter rather than an object.
- The method
StringExtensions.DetectIsJsonhas been removed (the equivalent exists in CMS).
- Obsoleted methods in
FieldConditionEvaluationhave been removed.
- The following unused classes have been removed:
BaseStorageEventArgsAdditional methods have been added to the following interfaces:
- Additional properties of
EditTypehave been added to the
- The obsoleted method
Formhas been removed,
- The constructor of
FolderNotificationHandlerhad an unused parameter removed.
- The obsolete and unused methods
CanCurrentUserExportwere removed from the
- The type parameter
IBaseService(and derived interfaces) has been removed.
- Database migration classes inheriting from
FormsMigrationBasenow use the non-obsolete base constructor defined on
- The methods on
IPlaceholderParsingServicehave been combined into a single one with optional parameters.
- The method
FormSecurityControllerhas been renamed to
- The backoffice model class
FormSecurityhas been renamed to
- The unused class
- The unused method
IFormService.FormExistwas renamed to
- Base class
ExportTypehas a constructor taking
- Typo was fixed in the class name of
SetFormThemeCssFileextension method had an unused variable removed.
- Various method signatures have had appropriate modifications for nullable reference type support.
FormsFileSystemForPackageDataas they are no longer needed following changes to support distribution of assets in a razor class library.
Version 9 of Umbraco Forms has a minimum dependency on Umbraco CMS core of
9.0.1 and runs on .NET 5.
See notes under 10.1.
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 make sure you read the Manual Upgrade instructions.
See notes under 10.1.
Version 4 to Version 6
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
- Umbraco Forms can be downloaded directly from our.umbraco.com
- 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 Upgrade of Umbraco Forms to the next major version, you will run into a problem where the legacy MacroPartial view file will be 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.
For new & clean installs done with NuGet this will not be a problem for you, as only the new Macro & its associated MacroPartial view file is part of the new NuGet version.
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_Data/UmbracoForms/Databy 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
We highly recommend you make the switch away from the legacy macro and swap over to the newer macro that supports the new 6.0.0 feature of themes. The legacy macro is there to ease the transition over and to avoid entire sites forms to stop working.