UWP アプリを WinUI 3 に移行する

UWP は現在、アクティブな開発を行っていません。 WinUI 3 とその後継者であるWindows アプリ SDKは、AI ツールによって移行の大部分を自動化できます。 主な課題は、AI モデルが長年の UWP サンプルでトレーニングされているため、ガイダンスなしで、離れて移動しようとしているパターンを再現することです。 このページは、エージェントが適切に対応するために必要なコンテキストを提供します。

WinUI エージェント プラグインをインストールする

winui-uwp-migration スキルは、一般的な置換を自動的に処理します。

gh copilot plugin install winui@awesome-copilot

詳細については、 WinUI エージェント プラグイン を参照してください。

API 置換テーブル

次の表は、最も一般的な API の置換をまとめたものです。 メンバー、プロパティ、あまり一般的でない API など、完全な詳細なマッピングについては、「UWP API とライブラリをWindows アプリ SDKにマッピングする」を参照してください。

名前空間

スレッド化

Windowing

ダイアログとピッカー

var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);

var dialog = new ContentDialog { XamlRoot = this.Content.XamlRoot, ... };
await dialog.ShowAsync();

Notifications

ネットワークと HTTP

Navigation

MVVM パターン

dotnet add package CommunityToolkit.Mvvm

アプリのライフサイクル

設定とストレージ

var appData = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "YourAppName");
Directory.CreateDirectory(appData);
var json = JsonSerializer.Serialize(data);
await File.WriteAllTextAsync(Path.Combine(appData, "settings.json"), json);

変更されない API

Windows.Devices.*、Windows.Media.*、Windows.UI.ViewManagement.UISettings、Windows.UI.Color、および XAML 名前空間外のほとんどの WinRT API は変更されません。

直接対応するコントロールがないもの

一部の UWP コントロールは WinUI 3 に存在しません。 シナリオに基づいて置換を選択します。

インク、Win2D、印刷

これらのサブシステムには、名前空間の変更以外の特定の移行手順が必要です。

Windows インク

InkCanvas API と InkPresenter API はMicrosoft.UI.Input.Inkingに移行しますが、それ以外の場合は同じです。 明白ではない変更の 1 つは CoreInputDeviceTypesです。

InkStrokeContainer.SaveAsync() LoadAsync()には引き続きIRandomAccessStreamが必要です。 System.IO ストリームからのブリッジ:

// Saving ink strokes to a file using System.IO
using var memoryStream = new MemoryStream();
using var ras = memoryStream.AsRandomAccessStream();
await inkStrokeContainer.SaveAsync(ras);
await File.WriteAllBytesAsync(filePath, memoryStream.ToArray());

// Loading ink strokes from a file
var bytes = await File.ReadAllBytesAsync(filePath);
using var ms = new MemoryStream(bytes);
using var ras = ms.AsRandomAccessStream();
await inkStrokeContainer.LoadAsync(ras);

Win2D

Win2D パッケージ名は変更されましたが、API サーフェスは同じです。

すべての Microsoft.Graphics.Canvas.* API (CanvasDevice、 CanvasBitmap、 CanvasRenderTarget、 DrawInk) は同じように動作します。 更新が必要なのは、NuGet パッケージ参照のみです。

印刷

UWP 印刷では、 PrintManager.GetForCurrentView()が使用されます。 WinUI 3 には、ウィンドウ ハンドル相互運用機能が必要です。

// UWP
var printManager = PrintManager.GetForCurrentView();
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManager.ShowPrintUIAsync();

// WinUI 3 — must pass window handle
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
var printManager = PrintManagerInterop.GetForWindow(hwnd);
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManagerInterop.ShowPrintUIForWindowAsync(hwnd);

PrintDocumentレンダリング API (Paginate、GetPreviewPage、AddPages) は変更されません。

スタート プロンプト

I'm migrating a UWP app to WinUI 3 using the Windows App SDK.

Apply these substitutions:
- Windows.UI.Xaml.* → Microsoft.UI.Xaml.*
- CoreDispatcher / Dispatcher.RunAsync → DispatcherQueue.TryEnqueue
- ApplicationView → AppWindow + AppWindowTitleBar
- CoreWindow → Microsoft.UI.Xaml.Window
- MessageDialog → ContentDialog (set XamlRoot, not InitializeWithWindow)
- FileOpenPicker / FileSavePicker / FolderPicker → add InitializeWithWindow
- Windows.UI.Notifications → Microsoft.Windows.AppNotifications
- SystemNavigationManager.BackRequested → NavigationView back handling
- Pivot → TabView, NavigationView (top mode), or RadioButtons (no direct equivalent)
- InkToolbar custom subclasses → rebuild as CommandBar with AppBarToggleButton
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- Windows.UI.Input.Inking.* → Microsoft.UI.Input.Inking.*

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
x:Bind defaults to Mode=OneTime. Add Mode=OneWay for any binding that should update at runtime.
Flag any APIs without a direct WinUI 3 equivalent rather than guessing.

Project ファイルの変更

UWP ターゲット フレームワークを置き換えます。

<!-- Before (UWP) -->
<TargetPlatformVersion>10.0.19041.0</TargetPlatformVersion>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

<!-- After (WinUI 3) -->
<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
<WindowsSdkPackageVersion>10.0.19041.31</WindowsSdkPackageVersion>

Windows アプリ SDK パッケージを追加します。

dotnet add package Microsoft.WindowsAppSDK

関連するコンテンツ

• Windows アプリ SDK移行ガイド - 完全な手動移行チュートリアル
• UWP API とライブラリをWindows アプリ SDKにマッピングする - 包括的な API マッピング テーブル
• UWP から WinUI への移行時にサポートされる 機能 - 機能のサポート状態
• WPF から移行する