Migrate WPF Applications to .NET Core 3
- 5 minutes to read
This topic describes how to upgrade a WPF application that uses DevExpress controls to .NET Core 3. Once you switch the target platform, you can leverage the new framework’s advanced capabilities.
Before You Start
Prerequisites
- .NET Core 3
- Visual Studio 2019 version 16.3 with .NET desktop development workload installed
Consider Portability Limitations
.NET Core 3 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 Core.
Update NuGet Packages
Check whether the NuGet packages used within your project are compatible with .NET Core 3 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 Core 3 runtime.
Migrate an Application
Migration Overview
To migrate a WPF application from the .NET Framework to .NET Core, follow the steps below:
- Convert the application’s project file (*.csproj or *.vbproj) to an SDK-style format (or create a new SDK-style project file).
- Upgrade the application’s dependencies (NuGet packages) to the latest versions that support .NET Core.
- Change the target framework to .NET Core 3.
- Reference DevExpress controls using NuGet feeds instead of the Global Assembly Cache (GAC).
- 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 Core 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 CsprojtoVS2017 third-party tool to convert your project file to SDK-style format.
Review the converted file and delete the following unnecessary references, if present:
<Reference Include="System.Data.DataSetExtensions" />
<Reference Include="Microsoft.CSharp" />
<Reference Include="System.Net.Http" />
Check that the project builds and runs successfully.
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 Target Framework
Change the TargetFramework
option to netcoreapp3.0
and the project’s Sdk
to Microsoft.NET.Sdk.WindowsDesktop
:
<!-- Change the Sdk -->
<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<!-- Change the TargetFramework -->
<TargetFramework>netcoreapp3.0</TargetFramework>
<UseWPF>true</UseWPF>
<UseWindowsForms>true</UseWindowsForms>
...
Switch DevExpress References From GAC to NuGet
Add the DevExpress WPF NuGet packages:
Register a local or online DevExpress NuGet feed.
Find and install the
DevExpress.WindowsDesktop.Wpf
andDevExpress.WindowsDesktop.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 Core 3.
Fix Build Issues
If Visual Studio shows build errors, follow the output to refactor your code until you can successfully compile it.
Tip
Use the Microsoft.Windows.Compatibility package to access Windows-specific APIs: Registry, WCF Client, ACL, etc.
Use conditional compilation to write small parts of code that are different for the .NET Core 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.
Useful Resources
Video: Migrating a WPF App to .NET Core 3
A detailed walkthrough that covers WPF application migration.
Documentation: Port your code from .NET Framework to .NET Core
Microsoft’s Documentation section that overviews manual techniques and automated tools that you may find helpful when porting your code to .NET Core.
Blog: How to port desktop applications to .NET Core 3.0
A blog post that describes how to port both WPF and WindowsForms apps to .NET Core 3.