Breaking Change T923722
Visible to All Users

Core - FrameworkSettings.DefaultSettingsCompatibilityMode sets default XAF configuration options and feature toggles

What Changed

We implemented the DevExpress.ExpressApp.FrameworkSettings.DefaultSettingsCompatibilityMode property that enables configuration options and feature toggles specific to the version of your application. You can set this property to the DevExpress.ExpressApp.FrameworkSettingsCompatibilityMode enumeration value in the Program.cs(.vb) or Global.asax file of your application. This enumeration includes the following values:

  • v20_1
    When this value is selected, this property does not affect your application (does not change configuration options and feature toggles).
  • v20_2
    With this value, the following configuration options and feature toggles are set:
    • DevExpress.Persistent.Base.PasswordCryptographer.EnableRfc2898 = true
    • DevExpress.Persistent.Base.PasswordCryptographer.SupportLegacySha512 = false
    • DevExpress.ExpressApp.XafApplication.LinkNewObjectToParentImmediately = false
    • DevExpress.ExpressApp.XafApplication.OptimizedControllersCreation = true
    • DevExpress.ExpressApp.DetailView.UseAsyncLoading = true
    • DevExpress.ExpressApp.BaseObjectSpace.ThrowExceptionForNotRegisteredEntityType = true
    • DevExpress.ExpressApp.Utils.ImageLoader.Instance.UseSvgImages = true
    • DevExpress.ExpressApp.Win.WinApplication.UseLightStyle = true
    • DevExpress.ExpressApp.Win.WinApplication.UseOldTemplates = false
    • DevExpress.ExpressApp.Win.WinApplication.ExecuteStartupLogicBeforeClosingLogonWindow = true
    • DevExpress.ExpressApp.Web.WebApplication.EnableMultipleBrowserTabsSupport = true
    • DevExpress.ExpressApp.Web.Editors.ASPx.ASPxGridListEditor.AllowFilterControlHierarchy = true
    • DevExpress.ExpressApp.Web.Editors.ASPx.ASPxGridListEditor.MaxFilterControlHierarchyDepth = 3
    • DevExpress.ExpressApp.Web.Editors.ASPx.ASPxCriteriaPropertyEditor.AllowFilterControlHierarchyDefault = true
    • DevExpress.ExpressApp.Web.Editors.ASPx.ASPxCriteriaPropertyEditor.MaxHierarchyDepthDefault = 3
    • DevExpress.Persistent.BaseImpl.BaseObject.OidInitializationMode = OidInitializationMode.AfterConstruction
    • DevExpress.ExpressApp.Xpo.XPObjectSpace.TrackPropertyModifications = true
  • vXY_Z - for future product versions
  • Latest
    This value is equal to the latest version in the FrameworkSettingsCompatibilityMode enumeration and will be updated with each release. In v20.2 this value is equal to v20_2, in v21.1 this value is equal to v21_1 and so on.

Reasons for Change

We add feature toggles each time we implement a new feature that may cause a breaking change in your application. We specify these toggles in new applications created via the Solution Wizard, and you can also specify them in an existing application after its update via the Project Converter. When you specify them manually, you must also check if these options are compatible with each other. Currently, we have a bunch of feature toggles and it gets difficult to efficiently manage them all. The new DefaultSettingsCompatibilityMode property allows setting up all options actual for a specified version in just one line. This does not deny you can change any option at your discretion - options specified directly in your code have higher priority than DefaultSettingsCompatibilityMode.

Impact on Existing Apps and How to Revert to Previous Behavior

We set the DefaultSettingsCompatibilityMode property to Latest in all new XAF applications created via the Solution Wizard, and to v20_1 in existing XAF applications updated to v20.2 via the Project Converter. If you want to change this behavior, specify the DefaultSettingsCompatibilityMode property in the YourSolutionName.Win\Program.cs(.vb) or YourSolutionName.Web\Global.asax file before the application initialization as shown below.

NOTE: If you want to change the value of any feature toggle or configuration option (for instance, DevExpress.Persistent.Base.PasswordCryptographer.SupportLegacySha512 = true), do it after the XAF application initialization.

WinForms

C#
// YourSolutionName.Win/Program.cs using DevExpress.ExpressApp; // ... public class Program { static void Main(string[] arguments) { FrameworkSettings.DefaultSettingsCompatibilityMode = FrameworkSettingsCompatibilityMode.v20_1; // ... YourSolutionWinApplication winApplication = new YourSolutionWinApplication(); // change a feature toggle value here // ... } // ... }

ASP.NET WebForms

C#
// YourSolutionName.Web/Global.asax.cs using DevExpress.ExpressApp; // ... public class Global : HttpApplication { protected void Application_Start(object sender, EventArgs e) { FrameworkSettings.DefaultSettingsCompatibilityMode = FrameworkSettingsCompatibilityMode.v20_1; // change a feature toggle value here // ... } // ... }

Blazor

C#
// YourSolutionName.Blazor.Server/Program.cs using DevExpress.ExpressApp; // ... FrameworkSettings.DefaultSettingsCompatibilityMode = FrameworkSettingsCompatibilityMode.v20_1; IHost host = CreateHostBuilder(args).Build(); // change a feature toggle value here // ... } // ... }

Non-XAF Apps

You can either set required feature toggles manually (for instance, DevExpress.Persistent.Base.PasswordCryptographer.SupportLegacySha512 = true) or set a required FrameworkSettings.DefaultSettingsCompatibilityMode property value explicitly in v20.2. Project Converter does not apply the latter setting automatically if you non-XAF projects do not reference the DevExpress.ExpressApp assembly.

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.