Migrate to the New Version

After downloading and installing a new version of DevExtreme libraries, update your projects. This article will guide you through the upgrade process. If you experience any problems while upgrading your projects, please refer to our Support Center.

NOTE: Avoid installing different DevExtreme versions concurrently. If you install an older version, you need to uninstall the current one beforehand.

General Instructions for Major and Minor Versions

Whether you upgrade your projects from another major version or from a previous minor version to a 14.2.X DevExtreme version, follow the following general instructions.

Upgrade VS DevExtreme Applications

Use the Project Converter tool for the Visual Studio projects that were created using DevExtreme Project Templates.

There are two ways of accessing the Project Converter.

  • Open your solution/project in Visual Studio. Right click the solution/project to display the context menu and choose Upgrade DevExtreme Solution to the Latest Version... (or equivalently /Upgrade DevExtreme Project to the Latest Version...).

    Invoke Project Converter

  • Run the ProjectConverter.exe program from the folder where DevExtreme is installed. By default, it is located in the "...\Program Files (x86)\DevExpress 14.2\DevExtreme\Tools\" folder.

Specify the path to the project(s) to be upgraded in the Project folder text box.

Project Converter

Review the advanced options. Check Process Subdirectories if you also want to upgrade files in any subdirectories. Check Create Backup Files to create copies of the original files that are about to be upgraded (Project Converter will add a .bak extension to the file names of the copies), so that you can recreate the original project should you encounter any problems.

NOTE: We recommend that you check Create Backup Files if you have customized layouts or stylesheets in your projects. By doing so, you will be able to extract your customized layouts or stylesheets from those file copies to merge with the new versions.

Finally, click Upgrade and the Project Converter will upgrade your project(s) to the new version.

Upgrade Apps with DevExreme Scripts

Follow the steps below to manually upgrade your applications that use DevExtreme libraries.

  • Update Scripts
    Copy the new JavaScript files from the [Sources]/Lib/js DevExtreme folder to the equivalent folder in your applications.

  • Update Stylesheets
    Copy the new CSS files from the [Sources]/Lib/css DevExtreme folder to the equivalent folder in your applications.

  • Update Layouts
    Copy the new layout files from the [Sources]/Lib/layouts DevExtreme folder to the equivalent folder in your applications.

  • Updated the Export Folder
    If you are also using the Export feature, copy the new files from the [Sources]/Exporter folder to the same folder in your apps.

You can find all these resources within your DevExtreme package.

NOTE: If you customized layouts or stylesheets in your apps, do not replace them, but rather merge them with the ones supplied by the new DevExtreme version.

Upgrade Custom Themes

If you built your custom themes based on the DevExtreme predefined themes in a Theme Builder, update them each time a new product version (a minor or a major one) is released. This is needed to apply the changes that may possibly be performed in the predefined themes that you used as a base.

When you built your custom theme in a Theme Builder, you saved the differences from the base theme by using the Export feature to a file (there are instructions in the Save the Changes topic). Follow the steps below to apply these differences to the corresponding newly released base theme.

  • Open the Theme Builder.

  • Press Import. Paste the differences that you saved in the JSON format (using the Export feature) to the invoked window. Click Apply.

  • Check that all your differences are applied and perform customizations if required.

Deprecated API and Breaking Changes

We always do our best to minimize the impact each new version may have on your projects. Occasionally, however, it is necessary to change the behavior of our tools and/or make certain members deprecated. We do this to improve the quality of our products. Take a look at the deprecated API and the list of breaking changes that accompany each release.

  • Deprecated API
    Run an application updated to the newest DevExtreme version. The browser console will contain information about the deprecated API used in this application and the new members to be used instead. Although the application keeps working with the deprecated API, we still recommend that you use the new API in it. In DevExtreme, deprecated API will remain functional for two more versions of our tools, at which time it will be removed with an announcement about the possible occurrence of breaking changes.

  • Breaking Changes
    Take into account the breaking changes in each release and upgrade your apps according to the instructions given for each breaking change.

14.2 Version Specifics

When upgrading from a previous major version to version 14.2.X, take into account the following changes.

New Knockout Version

The js folder with scripts now contains the Knockout library version 3.2.0. If you manually update your applications/sites, then you must add a link to the Knockout library version 3.2.0 or keep the Knockout library version 3.1.0 within your js folder with scripts.

New Event Subscription Mechanism

Beginning with this release, the API for handling events will be consistent for all DevExtreme products. From this point forward, all events will be listed in the Events section of each DevExtreme library in the Reference documentation. To attach/detach event handlers, use the on(eventName, eventHandler)/off(eventName, eventHandler) method. When utilizing the MVVM approach, use configuration options with the on prefix to specify event handlers.

Take a look at the following articles on this subject.

NOTE: The previous approaches to subscribing to events (options with and without the Action postfix, as well as jQuery.Callbacks type events) are supported, but the corresponding options are marked as deprecated. Thus, updating your application and utilizing the new options/methods is highly recommended. To do this, take a look at the browser console of the application that runs on new DevExtreme scripts. There, you will find information on the deprecated members used in your application.

Visual Studio Application Templates

When updating your DevExtreme applications created using VS DevExtreme application templates, consider the following changes in the index.js file.

  • Previously, the hardwareBackButton event fired in application project templates integrated in Visual Studio. Now, the processHardwareBackButton() method should be called to process the hardware back button click.

  • Previously, the "devextremeaddon" plugin was run automatically when an application would start. Now, there is no capability to run it automatically. So you must run it in your code.

Thus, change this code ...

JavaScript
$(function() {
    //...
    document.addEventListener("deviceready", onDeviceReady, false);
    function onDeviceReady() {
        //...
        document.addEventListener("backbutton", onBackButton, false);
    }
    function onBackButton() {
        DevExpress.hardwareBackButton.fire();
    }
    //...
});

to the following:

JavaScript
$(function() {
    //...
    document.addEventListener("deviceready", onDeviceReady, false);
    function onDeviceReady() {
        //...
        if (window.devextremeaddon != null) {
            window.devextremeaddon.setup();
        }
        document.addEventListener("backbutton", onBackButton, false);
    }
    function onBackButton() {
        DevExpress.processHardwareButton();
    }   
    //...   
}

Rest Store

The RestStore data store that was deprecated two releases ago has been removed from the DevExtreme Data Library. Use the CustomStore store instead.

TypeScript Definition Files

In the previous DevExtreme version, TypeScript definitions were shipped in separate files: dx.phonejs.d.ts, dx.webappjs.d.ts and dx.chartjs.d.ts. In addition, the DevExtreme Complete package supplied the dx.all.d.ts file containing all the DevExtreme definitions. Now, only the dx.all.d.ts file ships with DevExtreme. If you used library-specific TypeScripts files, replace them with a single dx.all.d.ts file in your applications. In the DevExtreme Complete package, you will find the dx.all.d.ts file in the Sources/Lib/ts folder. If you have the DevExtreme Web or DevExtreme Mobile package, download this file from GitHub.

14.2.6 Version Specifics

When upgrading from a previous version to version 14.2.6, take into account the following changes.

New Knockout Version

The js folder with scripts now contains the Knockout library version 3.3.0. If you manually update your applications/sites, then you must add a link to the Knockout library version 3.3.0 or keep the Knockout library version 3.2.0 (3.1.0) within your js folder with scripts.