DevExpress Project Converter: Update References in Your Project
- 5 minutes to read
Overview
The Project Converter allows you to update your .NET Framework/.NET projects after you installed a new version of DevExpress components. You can run the Project Converter as a dialog window or as a console application. Read the following help topic for additional information:
The Project Converter replaces references to outdated DevExpress assemblies (or NuGet packages) with references to the most recent libraries. The Project Converter can also convert DevExpress assembly references to corresponding NuGet packages (optionally).
The Project Converter updates the following files:
project files (.csproj and .vbproj);
resource files (.resx) for forms that were localized in the Visual Studio Form Designer;
web application files (Web.config, .aspx, .ascx, .asax, and .master);
other files (.cs, .vb, .xaml, .skin, .config, .config.xml, .licx, .svc, .refresh, .uitest, and .lsml).
Target DevExpress-based Projects to .NET 8 and .NET Framework 4.6.2
Important
.NET 8, .NET Framework 4.6.2, Visual Studio 2019 are minimally supported versions for DevExpress libraries in v24.2. Refer to the following breaking change article for additional information: .NET 8 and .NET Framework 4.6.2 are minimally supported Target Frameworks for DevExpress libraries in v24.2.
When you update the DevExpress-powered project that targets .NET Framework 4.5.2 / .NET 6 (or earlier), the Project Converter displays the following window. This window informs you that the Project Converter will re-target DevExpress-based projects to .NET 8 and .NET Framework 4.6.2 and update 3rd party NuGet packages to the latest compatible versions.
Re-target DevExpress-based Projects to .NET 8 and .NET Framework 4.6.2
Note
The Project Converter does not update the TargetFramework and NuGet packages in non-DevExpress projects (without DevExpress NuGet packages).
The Project Converter automatically updates TargetFrameworkVersion, TargetFramework, and TargetFrameworks settings (from .NET Framework 4.5.2 / .NET 6 and earlier) in csproj/vbproj and *.config files.
Uncheck the Update Target Framework option if you want to update the target framework in your DevExpress projects manually.
Automatically Update 3rd Party NuGet Packages to the Latest Compatible Versions
Important
If your team already uses props files and Central Package Management (CPM) or does NOT wish to automate the conversion process, you can update everything manually. Within the converter, simply uncheck Update Target Framework and Update 3rd-party Packages* options and proceed with a standard version upgrade. These two options are enabled by default, but the Project Convert always makes backup files (*.bak) should you accidentally leave these options checked.
The Project Converter automatically updates 3rd-party NuGet packages for projects with DevExpress dependencies based on the latest version compatible with the target framework (over 200 known dependencies in our Directory.Packages.props file at “c:\Program Files\DevExpress 24.2\Components\Sources\Win\Directory.Packages.props” such as System.Text.Json, Microsoft.AspNetCore.*, etc).
The Project Converter updates the source Directory.Packages.props file based on known security advisories from https://github.com/advisories.
Uncheck the Update 3rd-party Dependencies option to update DevExpress projects manually.
Important Notes
- Before you start upgrading a project, refer to the Upgrade Your Application to a New DevExpress Version section and to the Breaking Changes page.
- The Project Converter does not modify names of classes and API members.
- You can use the Project Converter to update package versions in the PackageReferences format in your project. Project Converter does not support the old packages.config format.
- The Project Converter does not upgrade DevExpress / DevExtreme npm packages version listed in the package.json file. You should update the version manually.
- The Project Converter does not substitute assemblies that are placed in a project’s bin folder. To upgrade the bin folder content, select Build > Clean Solution in Visual Studio’s main menu and rebuild the project.
- Use the Localization Service to download the latest version of localization resources. The service allows you to copy your existing translations to a different DevExpress assembly version.
Troubleshoot File Encoding Issues
When you convert a project, the following error message can appear: “File encoding not specified and contains non-ASCII characters”. Some files are not converted in this case.
The error appears because the problematic file contains non-ASCII symbols and does not contain information about their encoding. Project Convertor cannot convert the file because there is no way to determine the encoding used to write a file and it is impossible to parse such files correctly. In this situation, the conversion can lead to corruption.
Solution
Perform the following actions to resolve this error:
- Open the file in the Visual Studio.
- Select the File > Save As… menu command.
- Click the down arrow next to the Save button in the Save File As dialog and select Save with Encoding….
- Select Unicode (UTF-8 with signature) - Codepage 65001.
- Process your project file with the Project Converter.
For additional information, review the following article: How to Manage Files By Using Encoding
Troubleshoot ASP.NET Web Forms Updates
- Resolve common issues after updating DevExpress controls
- How to update custom themes after upgrading a project to a new version
- General questions about themes, arising after an upgrade