This article describes how to upgrade a Windows Presentation Foundation (WPF) desktop app to .NET 8. Even though WPF runs on .NET, a cross-platform technology, WPF is still a Windows-only framework. The following WPF-related project types can be upgraded with the .NET Upgrade Assistant:

• WPF project
• Control library
• .NET library

If you're upgrading from .NET Framework to .NET, consider reviewing theDifferences with WPF .NET article and thePorting from .NET Framework to .NET guide.

Prerequisites

• Windows operating system
• Visual Studio 2022 version 17.7 or later to target .NET 8
• Visual Studio 2022 version 17.1 or later to target .NET 7
• .NET Upgrade Assistant extension for Visual Studio

Demo app

This article was written in the context of upgrading theWeb Favorites Sample project, which you can download from the.NET Samples GitHub repository.

Initiate the upgrade

If you're upgrading multiple projects, start with projects that have no dependencies. In the Web Favorites sample, theWebSiteRatings project depends on theStarVoteControl library, soStarVoteControl should be upgraded first.

Use the following steps to upgrade a project in Visual Studio:

1. Right-click on theStarVoteControl project in theSolution Explorer window and selectUpgrade:

   

   A new tab is opened that prompts you to choose how you want the upgrade to be performed.

2. SelectIn-place project upgrade.

3. Next, select the target framework. Based on the type of project you're upgrading, different options are presented..NET Standard 2.0 is a good choice if the library doesn't rely on a desktop technology like WPF and can be used by both .NET Framework projects and .NET projects. However, the latest .NET releases provide many language and compiler improvements over .NET Standard.

   Select.NET 8.0 and then selectNext.

4. A tree is shown with all of the artifacts related to the project, such as code files and libraries. You can upgrade individual artifacts or the entire project, which is the default. SelectUpgrade selection to start the upgrade.

   When the upgrade is finished, the results are displayed:

   

   Artifacts with a solid green circle were upgraded while empty green circles were skipped. Skipped artifacts mean that the upgrade assistant didn't find anything to upgrade.

Now that the app's supporting library is upgraded, upgrade the main app.

Upgrade the app

Once all of the supporting libraries are upgraded, the main app project can be upgraded. Perform the following steps:

1. Right-click on theWebSiteRatings project in theSolution Explorer window and selectUpgrade:
2. SelectIn-place project upgrade as the upgrade mode.
3. Select.NET 8.0 for the target framework and selectNext.
4. Leave all of the artifacts selected and selectUpgrade selection.

After the upgrade is complete, the results are shown. If an item has a warning symbol, it means that there's a note for you to read, which you can do by expanding the item.

Generate a clean build

After your project is upgraded, clean and compile it.

1. Right-click on theWebSiteRatings project in theSolution Explorer window and selectClean.
2. Right-click on theWebSiteRatings project in theSolution Explorer window and selectBuild.

If your application encountered any errors, you can find them in theError List window with a recommendation how to fix them.

Post-upgrade steps

If your project is being upgraded from .NET Framework to .NET, review the information in theModernize after upgrading to .NET from .NET Framework article.

After upgrading, you'll want to:

• Check your NuGet packages.

  The .NET Upgrade Assistant upgraded some packages to new versions. With the sample app provided in this article, theMicrosoft.Data.Sqlite NuGet package was upgraded from1.0.0 to8.0.x. However,1.0.0 depends on theSQLite NuGet package, but8.0.x removes that dependency. TheSQLite NuGet package is still referenced by the project, although it's no longer required.Both theSQLite andSQLite.Native NuGet packages can be removed from the project.

• Clean up the old NuGet packages.

  Thepackages.config file is no longer required and can be deleted from your project, as the NuGet package references are now declared in the project file. Additionally, the local NuGet package cache folder, namedPackages, is in either the folder or the parent folder of the project. This local cache folder can be deleted. The new NuGet package references use a global cache folder for packages, available in the user's profile directory, named.nuget\packages.

• Remove theSystem.Configuration library.

  Most .NET Framework apps reference theSystem.Configuration library. After upgrading, it's possible that this library is still directly referenced.

  TheSystem.Configuration library uses theapp.config file to provide run-time configuration options to your app. For .NET, this library was replaced by theSystem.Configuration.ConfigurationManager NuGet package. Remove reference to the library and add the NuGet package to your project.

• Check for places to modernize your app.

  APIs and libraries have changed quite a bit since .NET was released. And in most cases, .NET Framework doesn't have access to these improvements. By upgrading to .NET, your now has access to more modern libraries.

  The next sections describe areas you modernize the sample app used by this article.

Modernize: Web browser control

TheWebBrowser control referenced by the WPF sample app is based on Internet Explorer, which is out-of-date. WPF for .NET can use theWebView2 control based on Microsoft Edge. Complete the following steps to upgrade to the newWebView2 web browser control:

1. Add theMicrosoft.Web.WebView2 NuGet package.

2. In theMainWindow.xaml file:

   1. Import the control to thewpfControls namespace in the root element:

      <mah:MetroWindow x:Class="WebSiteRatings.MainWindow"        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"        xmlns:mah="clr-namespace:MahApps.Metro.Controls;assembly=MahApps.Metro"        xmlns:local="clr-namespace:WebSiteRatings"        xmlns:vm="clr-namespace:WebSiteRatings.ViewModels"        xmlns:VoteControl="clr-namespace:StarVoteControl;assembly=StarVoteControl"        xmlns:wpfControls="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"        Loaded="MetroWindow_Loaded"        mc:Ignorable="d"        Title="My Sites" Height="650" Width="1000">

   2. Down where the<Border> element is declared, remove theWebBrowser control and replace it with thewpfControls:WebView2 control:

      <Border Grid.Row="2" Grid.Column="1" Grid.ColumnSpan="2" BorderThickness="1" BorderBrush="Black" Margin="5">    <wpfControls:WebView2 x:Name="browser" ScrollViewer.CanContentScroll="True" /></Border>

3. Edit theMainWindow.xaml.cs code behind file. Update theListBox_SelectionChanged method to set thebrowser.Source property to a validUri. This code previously passed in the website URL as a string, but theWebView2 control requires aUri.

   private void ListBox_SelectionChanged(object sender, SelectionChangedEventArgs e){    var siteCollection = (ViewModels.SiteCollection)DataContext;    if (siteCollection.SelectedSite != null)        browser.Source = new Uri(siteCollection.SelectedSite.Url);    else        browser.NavigateToString("<body></body>");}

Depending on which version of Windows a user of your app is running, they may need to install the WebView2 runtime. For more information, seeGet started with WebView2 in WPF apps.

Modernize: appsettings.json

.NET Framework uses theApp.config file to load settings for your app, such as connection strings and logging providers. .NET now uses theappsettings.json file for app settings.App.config files are supported in .NET through theSystem.Configuration.ConfigurationManager NuGet package, and support forappsettings.json is provided by theMicrosoft.Extensions.Configuration NuGet package.

As other libraries upgrade to .NET, they modernize by supportingappsettings.json instead ofApp.config. For example, logging providers in .NET Framework that have been upgraded for .NET 6+ no longer useApp.config for settings. It's good to follow their direction and also move away from usingApp.config where you can.

Use appsettings.json with the WPF sample app

As an example, after upgrading the WPF sample app, useappsettings.json for the connection string to the local database.

1. Remove theSystem.Configuration.ConfigurationManager NuGet package.

2. Add theMicrosoft.Extensions.Configuration.Json NuGet package.

3. Add a file to the project namedappsettings.json.

4. Set theappsettings.json file to copy to the output directory.

   Set thecopy to output setting through Visual Studio using theProperties window after selecting the file in theSolution Explorer. Alternatively you can edit the project directly and add the followingItemGroup:

     <ItemGroup>    <Content Include="appsettings.json">      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>    </Content>  </ItemGroup>

5. Migrate the settings in theApp.config file to a newappsettings.json file.

   In the WPF sample app,app.config only contained a single connection string. Edit theappsettings.json file to define the connection string:

   {  "ConnectionStrings": {    "database": "DataSource=sqlite.db;"  }}

6. Edit theApp.xaml.cs file, instancing a configuration object that loads theappsettings.json file, the added lines are highlighted:

   using System.Windows;using Microsoft.Extensions.Configuration;namespace WebSiteRatings{    /// <summary>    /// Interaction logic for App.xaml    /// </summary>    public partial class App : Application    {        public static IConfiguration Config { get; private set; }        public App()        {            Config = new ConfigurationBuilder()                .AddJsonFile("appsettings.json")                .Build();        }    }}

7. In the.\Models\Database.cs file, change theOpenConnection method to use the newApp.Config property. This requires importing theMicrosoft.Extensions.Configuration namespace:

   using Microsoft.Data.Sqlite;using System.Collections.Generic;using Microsoft.Extensions.Configuration;namespace WebSiteRatings.Models{    internal class Database    {        public static SqliteConnection OpenConnection() =>            new SqliteConnection(App.Config.GetConnectionString("database"));        public static IEnumerable<Site> ReadSites()

   GetConnectionString is an extension method provided by theMicrosoft.Extensions.Configuration namespace.