Skip to main content
BuyLog In
WPF Controls
Search in…
Docs > WPF Controls > .NET/.NET Core Support > Migrate WPF Applications to .NET 5
A newer version of this page is available. .
All docs
V21.1
WPF Controls
Prerequisites
What's Installed
.NET/.NET Core Support
Getting Started
Migrate WPF Applications to .NET 5
Deploy .NET 5 Applications
Common Concepts
MVVM Support
MVVM Framework
Controls and Libraries
Scaffolding Wizard
Localization
Redistribution and Deployment
Get More Help
API Reference
Download CHM

Migrate WPF Applications to .NET

  • 6 minutes to read

This topic describes how to upgrade a WPF application that uses DevExpress controls to .NET. Once you switch the target platform, you can leverage the new framework’s advanced capabilities.

Before You Start

Prerequisites

Consider Portability Limitations

.NET misses a part of APIs that are present in the .NET Framework. Use the .NET Portability Analyzer tool to determine whether your application uses such APIs.

Try to refactor your code to reduce the number of calls to missing APIs. Look for an alternative API with the required functionality.

Useful resource: .NET Framework technologies unavailable on .NET.

Update NuGet Packages

Check whether the NuGet packages used within your project are compatible with .NET and whether newer compatible versions are available.

Update your project to reference the latest package versions, if necessary.

Tip

Perform this step even if Visual Studio does not show any compile-time errors. You may experience runtime exceptions if you build the application with packages that were not tested against .NET runtime.

Migrate an Application

Migration Overview

To migrate a WPF application from the .NET Framework to .NET, follow the steps below:

  1. Convert the application’s project file (*.csproj or *.vbproj) to an SDK-style format (or create a new SDK-style project file).
  2. Upgrade the application’s dependencies (NuGet packages) to the latest versions that support .NET.
  3. Change the target framework to .NET.
  4. Reference DevExpress controls using NuGet feeds instead of the Global Assembly Cache (GAC).
  5. Review and fix errors and exceptions that appear at both compile and run time.

Tip

Backup your project before migration.

Create a New Project File

.NET works with the new SDK-style project file format only.

There are two ways to create such a project file:

  • Convert your existing project file to the new format

    This method is best suited for small applications with only a few dependencies.

  • Create a project file manually

    This manual option gives you greater control over the migration process.

Convert Your Existing Project File to the New Format

Use the .NET Upgrade Assistant third-party tool to convert your project file to SDK-style format and change the target framework to .NET.

Select View -> Terminal in the Visual Studio’s main menu to open the integrated terminal. Run the following command to install the .NET Upgrade Assistant.

 dotnet tool install -g upgrade-assistant

Once you have installed the .NET Upgrade Assistant, you can update it with the following command:

 dotnet tool update -g upgrade-assistant

To upgrade your solution to .NET 5, run the following command. Specify the name of the project you want to convert:

 upgrade-assistant upgrade .\ProjectName.csproj

The tool displays a list of migration steps. You can skip certain steps if necessary. Once the project has been upgraded, reload the solution.

Refer to the Upgrade a WPF App to .NET 5 with the .NET Upgrade Assistant topic on MSDN for more details.

Create a Project File Manually

Use the code sample below as a template to create a new *.csproj (*.vbproj) file. Modify the file according to the instructions.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
      <!-- The TargetFramework value may differ -->
    <TargetFramework>net472</TargetFramework>
    <UseWPF>true</UseWPF>
    <!-- The `UseWindowsForms` option is required -->
    <UseWindowsForms>true</UseWindowsForms>
    <!-- AssemblyInfo.cs is generated automatically by default.
         Disable auto-generation or remove the file. -->
      <GenerateAssemblyInfo>false</GenerateAssemblyInfo>

      <!-- Copy and paste from the old project file -->
      <AssemblyName>MyCoreApp</AssemblyName>
      <!-- Copy and paste from the old project file -->
    <RootNamespace>MyWPF</RootNamespace>
      <!-- Useful for conditional compilation, see
         https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-if  -->
      <DefineConstants>NETCORE</DefineConstants>
      <!-- Your application icon -->
      <ApplicationIcon>MyAppIcon.ico</ApplicationIcon>
  </PropertyGroup>

  <!-- ApplicationDefinition, all the C# files, XAML pages, EmbeddedResources,
       and App.config are included by default,
       so you do not need to include them manually -->

  <ItemGroup>
    <!-- EmbeddedResources are included by default,
         but regular resources are not included by default,
             so you need to include them to your new project file -->
    <Resource Include="MyAppIcon.ico" />
      <Resource Include="\Images\MyAppImage1.png" />
      <Resource Include="\Images\MyAppImage2.png" />
      <!-- You need to include the Content sections from the old project file -->
  </ItemGroup>

  <!--
    If your project depends on NuGet packages, the solution contains
  the `packages.config` file.
    In the old project, convert packages.config to Package Reference format:
    right click the package.config file in the solution explorer ->
  "Migrate packages.config to PackageReference..."

    Your NuGet packages go here, copy them from the old project file -->
  <ItemGroup>
    <!-- These package references are added here for demonstration purposes.
         Add the packages your applcation actually uses. -->
    <PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
      <PackageReference Include="EntityFramework" Version="6.3.0-preview9-19423-04" />
      <PackageReference Include="Microsoft.Data.SQLite" Version="3.0.0-preview9.19423.6" />
  </ItemGroup>
</Project>

After this step, your project still targets .NET Framework, and has an SDK-style project file. Check that the project builds and runs successfully.

Change the TargetFramework option to net5.0-windows and the project’s Sdk to Microsoft.NET.Sdk:

<!-- Change the Sdk -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <!-- Change the TargetFramework -->
    <TargetFramework>net5.0-windows</TargetFramework>
    <UseWPF>true</UseWPF>
      <UseWindowsForms>true</UseWindowsForms>
...

Switch DevExpress References From GAC to NuGet

Add the DevExpress WPF NuGet packages:

  1. Register a local or online DevExpress NuGet feed.

  2. Find and install the DevExpress.Wpf and DevExpress.Wpf.Themes.All packages.

Once you have added the package to your project, Visual Studio loads and displays DevExpress WPF controls in the Toolbox.

Your project now targets .NET.

Fix Build Issues

If Visual Studio shows build errors, follow the output to refactor your code until you can successfully compile it.

Tip

  1. Use the Microsoft.Windows.Compatibility package to access Windows-specific APIs: Registry, WCF Client, ACL, etc.

  2. Use conditional compilation to write small parts of code that are different for the .NET and .NET Framework.

Test Your App

Run and test the upgraded app. Remember that runtime exceptions are possible even if the application was built without compile-time errors.

Target Both .NET and .NET Framework Platforms

To add references to projects that target both .NET and .NET Framework platforms, modify the *.csproj (*.vbproj) file in the following manner:

<!-- Use the Condition attribute to check the current platform -->
<ItemGroup Condition="'$(TargetFramework)' == 'net5.0-windows'">  
  <!-- Reference the .NET package -->
  <PackageReference Include="devexpress.wpf.charts">  
    <Version>21.1.4</Version>  
  </PackageReference>  
</ItemGroup>  
<ItemGroup Condition="'$(TargetFramework)' == 'net472'">
  <!-- Reference the .NET Framework package -->  
  <PackageReference Include="devexpress.wpf.charts">  
    <Version>21.1.4</Version>  
  </PackageReference>  
  ...  
</ItemGroup>

Useful Resources