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.
General Instructions for Major and Minor Versions
Whether you upgrade your projects from another major version or from a previous minor version to a 16.1.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...).
Run the ProjectConverter.exe program from the folder where DevExtreme is installed. By default, it is located in the "...\Program Files (x86)\DevExpress 16.1\DevExtreme\Tools\" folder.
Specify the path to the project(s) to be upgraded in the Project folder text box.
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.
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.
Copy the new CSS files from the [Sources]/Lib/css DevExtreme folder to the equivalent folder in your applications.NOTEThe css folder must include the icons folder with font icons.
Copy the new layout files from the [Sources]/Lib/layouts DevExtreme folder to the equivalent folder in your applications.
You can find all these resources within your DevExtreme package.
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.
Learn What is New
New Major Features
Get introduced with the key features that have been implemented in DevExtreme major version 16.1: What's New.
Learn More Details
Learn detailed information on new features and resolved issues in major version 16.1, and all the successive minor versions: What's New in 16.1.
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.
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.
Take into account the breaking changes in each release and upgrade your apps according to the instructions given for each breaking change.
16.1 Version Specifics
When upgrading from a previous major version to version 16.1.X, take into account the following changes.
Angular 2 Support (CTP)
DevExtreme provides the Angular 2 Integration module (CTP), which enables you to use UI widgets as Angular 2 components.
Globalize 1.x uses the CLDR library, which is based on the LDML standard. This standard has too many differences with the standard used in Globalize 0.x. The structure and the API of Globalize 1.x is absolutely new, so we have to remove Globalize 0.x integration to support Globalize 1.x. However, if you want to postpone migration to Globalize 1.X, you can use the Globalize 0.1 Integration module.
Starting with the 16.1 release, DevExtreme applications do not require Globalize. You need to reference Globalize only if your application should support the following functionality.
- Non-English locales
- Custom message dictionaries
- Non-USD currency formatting
- Custom date and number formatting
The most valuable changed points are these.
New method for localization scripts and data including.
DevExtreme requires the core globalize script and 4 globalize modules (message, number, date, currency). Also, Globalize requires some cldrjs scripts. Here is a list of the required Globalize scripts.HTML
<script src="js/cldr.min.js"></script> <script src="js/cldr/event.min.js"></script> <script src="js/cldr/supplemental.min.js"></script> <script src="js/globalize.min.js"></script> <script src="js/globalize/message.min.js"></script> <script src="js/globalize/number.min.js"></script> <script src="js/globalize/currency.min.js"></script> <script src="js/globalize/date.min.js"></script>
New acceptable values for the format option.
- Used in Globalize 0.x, number shortcuts (like "n0", "c2") and date shortcuts (like "d", "T") are not supported anymore. Use a format object instead.
- Date patterns are using LDML format instead of Microsoft standard.
- Custom quarters formats ('q', 'qq', 'Q', 'QQ') are removed. Now quarters can be formatted in CLDR formats only.
Currencies are no longer defined by the current locale.
Use the DevExpress.config(config) method to set the defaultCurrency or the format.currency widget's option to define currency.
The modules shipped within the DevExtreme package (located in the "js\modules" folder) are not available anymore. Starting with version 16.1, DevExtreme provides a variety of smaller modules shipped as NPM packages. This can help you to significantly reduce the amount of memory allocated by your application (because only the required functionality is loaded), and speed up application loading, due to the smaller size of the loaded code and the capability to load modules at runtime by demand. For more information on using modules, refer to the Modularity guide.
Starting with version 16.1, DevExtreme provides the following bundles.
|16.1 Bundle||15.2 Bundles||15.2 Modules|