如何將 WPF 傳統型應用程式升級至 .NET 8

發行項
02/08/2024

本文說明如何將 Windows Presentation Foundation （WPF）傳統型應用程式升級至 .NET 8。雖然 WPF 是在 .NET 上執行，但跨平台技術 WPF 仍然是僅限 Windows 的架構。您可以使用 .NET Upgrade Assistant 來升級下列 WPF 相關項目類型：

WPF 專案
控件連結庫
.NET 連結庫

如果您要從 .NET Framework 升級至 .NET，請考慮檢閱 WPF .NET 的差異一文，以及從 .NET Framework 移植到 .NET 指南。

必要條件

示範應用程式

本文是以升級 Web 我的最愛範例項目的內容撰寫，您可以從 .NET 範例 GitHub 存放庫下載。

起始升級

如果您要升級多個專案，請從沒有相依性的項目開始。在 Web 我的最愛範例中 ，WebSiteRatings 項目取決於 StarVoteControl 連結庫，因此 應該先升級 StarVoteControl 。

提示

請務必備份您的程序代碼，例如在原始檔控制或複本中。

使用下列步驟升級 Visual Studio 中的專案：

以滑鼠右鍵按兩下 [方案總管] 視窗中的 StarVoteControl 專案，然後選取 [升級]：

隨即開啟新的索引標籤，提示您選擇要執行升級的方式。
選取 [就地項目升級]。
接下來，選取目標架構。根據您要升級的項目類型，會顯示不同的選項。 如果連結庫不依賴 WPF 之類的桌面技術，而且可以同時供 .NET Framework 專案和 .NET 專案使用，則 .NET Standard 2.0 是不錯的選擇。不過，最新的 .NET 版本透過 .NET Standard 提供許多語言和編譯程式改善。

選取 [.NET 8.0 ]，然後選取 [ 下一步]。
樹狀結構會顯示與項目相關的所有成品，例如程式代碼檔案和連結庫。您可以升級個別成品或整個專案，這是預設值。選取 [ 升級] 選取項目 以開始升級。

升級完成時，會顯示結果：

已升級具有實心綠色圓圈的成品，同時略過空的綠色圓圈。略過的成品表示升級小幫手找不到任何升級專案。

現在已升級應用程式的支持連結庫，請升級主要應用程式。

升級應用程式

升級所有支持的連結庫之後，即可升級主要應用程式專案。執行下列步驟：

以滑鼠右鍵按兩下 [方案總管] 視窗中的 [WebSiteRatings] 專案，然後選取 [升級]：
選取 [就地項目升級 ] 作為升級模式。
選取 目標 Framework 的 .NET 8.0 ，然後選取 [ 下一步]。
保留選取的所有成品，然後選取 [ 升級] 選取專案。

升級完成後，會顯示結果。如果專案有警告符號，表示有一個記事可供您讀取，您可以藉由展開項目來執行此動作。

產生全新組建

升級項目之後，請清除並加以編譯。

以滑鼠右鍵按兩下 [方案總管] 視窗中的 [WebSiteRatings] 項目，然後選取 [清除]。
以滑鼠右鍵按兩下 [方案總管] 視窗中的 [WebSiteRatings] 項目，然後選取 [建置]。

如果您的應用程式發生任何錯誤，您可以在 [錯誤清單] 視窗中找到錯誤，並建議如何修正錯誤。

升級後步驟

如果您的專案從 .NET Framework 升級至 .NET，請檢閱從 .NET Framework 升級至 .NET 之後現代化中的資訊一文。

升級之後，您會想要：

檢查您的 NuGet 套件。

.NET 升級小幫手已將一些套件升級至新版本。使用本文提供的範例應用程式， Microsoft.Data.Sqlite NuGet 套件已從 1.0.0 升級至 8.0.x。不過， 1.0.0 取決於 SQLite NuGet 套件，但 8.0.x 會移除該相依性。 SQLite專案仍會參考 NuGet 套件，不過它已不再需要。 SQLite和 SQLite.Native NuGet 套件都可以從專案中移除。
清除舊的 NuGet 套件。

packages.config 檔案已不再需要，而且可以從專案中刪除，因為 NuGet 套件參考現在會在項目檔中宣告。此外，名為 Packages 的本機 NuGet 套件快取資料夾位於專案的資料夾或父資料夾。您可以刪除此本機快取資料夾。新的 NuGet 套件參考會針對名為 .nuget\packages 的使用者配置文件目錄中提供的套件使用全域快取資料夾。
拿掉連結 System.Configuration 庫。

大部分的 .NET Framework 應用程式都會參考連結 System.Configuration 庫。升級之後，可能仍會直接參考此連結庫。

連結 System.Configuration 庫會 使用 app.config 檔案，將運行時間組態選項提供給您的應用程式。針對 .NET，此連結庫已由 System.Configuration.ConfigurationManager NuGet 套件取代。拿掉連結庫的參考，並將 NuGet 套件新增至您的專案。
檢查位置以將您的應用程式現代化。

自 .NET 發行以來，API 和連結庫已變更相當多。在大部分情況下，.NET Framework 無法存取這些改進功能。藉由升級至 .NET，您現在可以存取更現代化的連結庫。

下一節將說明您將本文所用範例應用程式現代化的區域。

現代化：網頁瀏覽器控制項

WebBrowser WPF 範例應用程式所參考的控件是以 Internet Explorer 為基礎，這是過期的。適用於 .NET 的 WPF 可以使用以 Microsoft Edge 為基礎的 WebView2 控制件。完成下列步驟，以升級至新的 WebView2 網頁瀏覽器控制項：

新增 Microsoft.Web.WebView2 NuGet 套件。

在 MainWindow.xaml 檔案中：

將控制項匯入至根元素中的 wpfControls 命名空間：

<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">

關閉宣告 <Border> 元素的位置、移除 WebBrowser 控制項，並將它取代為 wpfControls:WebView2 控制項：

<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>

編輯 MainWindow.xaml.cs 程式碼後置檔案。更新 ListBox_SelectionChanged 方法，以將 browser.Source 屬性設定為有效的 Uri。此程式碼先前以字串形式傳入網站 URL，但 WebView2 控制項需要 Uri。

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>");
}

根據您應用程式使用者執行所在的 Windows 版本而定，他們可能需要安裝 WebView2 執行階段。如需詳細資訊，請參閱開始使用 WPF 應用程式中的 WebView2。

現代化：appsettings.json

.NET Framework 會使用App.config 檔案來載入應用程式的設定，例如連接字串和記錄提供者。 .NET 現在會 針對應用程式設定使用appsettings.json 檔案。 透過 NuGet 套件在 .NET 中支援 App.config 檔案，而 nuGet 套件會Microsoft.Extensions.Configuration提供appsettings.json支援。System.Configuration.ConfigurationManager

當其他連結庫升級至 .NET 時，它們會藉由支援 appsettings.json 而不是 App.config 來現代化。例如，已針對 .NET 6+ 升級的 .NET Framework 記錄提供者不再使用 App.config 進行設定。最好遵循其方向，也可以離開使用 App.config 。

搭配 WPF 範例應用程式使用 appsettings.json

例如，升級 WPF 範例應用程式之後，請使用 appsettings.json 將連接字串至本機資料庫。

移除 System.Configuration.ConfigurationManager NuGet 套件。
新增 Microsoft.Extensions.Configuration.Json NuGet 套件。
將檔案新增至名為 appsettings.json 的專案。
設定要複製到輸出目錄的 appsettings.json 檔案。

在選取方案總管中的檔案之後，使用 [屬性] 視窗，透過 Visual Studio 將複本設定為輸出設定。或者，您可以直接編輯專案，並新增下列 ItemGroup專案：
```
  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
```
將 App.config 檔案中的設定移轉至新的appsettings.json檔案。

在 WPF 範例應用程式中，app.config 只包含單一連接字串。 編輯appsettings.json檔案以定義連接字串：
```
{
  "ConnectionStrings": {
    "database": "DataSource=sqlite.db;"
  }
}
```

編輯App.xaml.cs檔案，實例化載入appsettings.json檔案的組態物件，會反白顯示新增的行：

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();
        }
    }
}

在 .\Models\Database.cs 檔案中，將 OpenConnection 方法變更為使用新的 App.Config 屬性。這需要匯入 Microsoft.Extensions.Configuration 命名空間：

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 是 Microsoft.Extensions.Configuration 命名空間所提供的擴充方法。