Breaking Change T1262237
Visible to All Users

The mechanism of adding DevExtreme into Blazor applications has changed

What Changed

Some DevExpress Blazor Components execute API members from our DevExtreme library.

In v24.1, these components use different versions of the DevExtreme script. These versions also differs from the script that DevExtreme components use. As a result, an application page can load multiple different instances of the DevExtreme script.

In v24.2, all DevExpress Blazor and DevExtreme components now use the same version of the DevExtreme script. Each page includes only one DevExtreme script.

Reasons for Change

This change reduces the size of loaded scripts and help avoid resource-related issues. Depending on the number of components, your application will download up to 11 MB of JavaScript files on the initial load.

Impact on Existing Apps

This change affects Blazor applications that explicitly reference DevExtreme. These applications load two instances of the DevExtreme script. As a result, the following DevExpress components will stop working in such projects:

  • Blazor Bar Gauge
  • Blazor Charts
  • Blazor Dashboard
  • Blazor HTML Editor
  • Blazor Map
  • Blazor PDF Viewer
  • Blazor Reporting
  • Blazor Rich Text Editor
  • DevExtreme components

How to Update Existing Apps

Non-Modular DevExtreme Inclusion

If you load DevExtreme in a non-modular way, unload DevExtremeJS, QuillJS, KnockoutJS, and JQueryJS scripts from the Resource Manager and add them in the following order:

Razor
@* Uncomment the following lines if your application uses the Dashboard or JS-based Reports *@ @* <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/knockout/3.5.0/knockout-min.js"></script> <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-3.4.1.min.js"></script> *@ <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/devextreme-quill/1.6.3/dx-quill.min.js"></script> <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/23.2.3/js/dx.all.js"></script> @DxResourceManager.RegisterScripts((config) => { config.Unregister(CommonResources.DevExtremeJS); config.Unregister(BlazorResources.QuillJS); @* Uncomment the following lines if your application uses the Dashboard or JS-based Reports *@ @* config.Unregister(CommonResources.KnockoutJS); config.Unregister(CommonResources.JQueryJS); *@ })

Modular DevExtreme Inclusion

If you load a DevExtreme script as a module, remove the code that loads DevExtreme. Call the LoadDxResources method before you use a DevExtreme API member for the first time. This method forces the Resource Manager to load client resources:

Razor
@code { [Inject] IJSRuntime js; protected override async Task OnAfterRenderAsync(bool firstRender) { if(firstRender) { await js.LoadDxResources(); await js.InvokeAsync("somemethod"); } await base.OnAfterRenderAsync(firstRender); } }

XAF Blazor Application

In v24.1 and earlier, you could use the workaround described in the Dashboards Module Troubleshooting Guide to add both Dashboards and DevExtreme widgets to your XAF Blazor application. After upgrading the application to v24.2, the following error can occur when you open a dashboard:

The DevExtreme library is included before the Knockout library. Check the order in which the scripts appear on the page.

To fix this error, follow instructions described in the following help topic: The "The DevExtreme library is included before the Knockout library. Check the order in which the scripts appear on the page" error message in v24.2+.

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.