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 インク

WinUI には、Windows アプリ SDKの試験的なリリースの実験用 API としてInkCanvas、InkToolbar、およびInkPresenterが含まれています。 安定版リリースには含まれません。 セットアップ、ツール バーのカスタマイズ、既知の制限事項については、「 WinUI アプリの Inking コントロール」を参照してください。

試験段階のリリースでは、インク入力を処理するコントロールと型は Microsoft.UI.Xaml.Controls にあります。 ストロークと描画属性は、 Windows.UI.Input.Inkingに残ります。

最初の 2 つの行のすべての UWP 型には同じ名前の対応する型がありますが、Windows アプリ SDK 2.5.4-experimental にはそれらのメンバーのすべてが含まれているわけではありません。

• InkStrokeContainer にはパブリック コンストラクターがなく、 InkPresenter.StrokeContainer は読み取り専用です。 ストロークのセットを切り替えるには、各セットを SaveAsync で保存し、LoadAsync で復元します。これは現在のストロークを置き換えます。
• SaveAsyncとLoadAsyncはIAsyncActionを返すため、進行状況は報告されません。また、SaveAsyncは書き込んだバイト数を返しません。
• InkStrokeContainer.GetRecognitionResults、 InkStrokeContainer.UpdateRecognitionResults、および InkInputConfiguration.IsPenHapticFeedbackEnabled は使用できません。
• InkToolbarRulerButton.Ruler と InkToolbar.IsRulerButtonCheckedChanged イベントは使用できません。 UWP では InkToolbarStencilButton は非推奨になり、代わりに InkToolbarRulerButton が推奨されるため、代わりにステンシル ボタンと InkToolbar.IsStencilButtonCheckedChanged イベントを使用してください。

Windows アプリ SDK 2.4.1-experimental では、InkToolbarEraserKind や InkToolbarEraserButton.SelectedEraser などの消しゴム API が追加されましたが、これらは 2.5.4-experimental で削除されました。 これらは UWP の一部だったことは一度もないため、移行されたコードに追加しないでください。 完全な一覧については、「 2.4.1-experimental からの変更」を参照してください。

InkPresenterやInkStrokeContainerなどの型は両方の名前空間に存在するため、Microsoft.UI.Xaml.ControlsとWindows.UI.Input.Inkingの両方をインポートすると、これらの名前を使用するとエラー CS0104 が発生します。 Microsoft.UI.Xaml.Controlsをインポートし、使用するWindows.UI.Input.Inking型のエイリアス ディレクティブを追加します。

using Microsoft.UI.Xaml.Controls;
using InkDrawingAttributes = Windows.UI.Input.Inking.InkDrawingAttributes;
using InkStroke = Windows.UI.Input.Inking.InkStroke;

InkStrokeContainer.SaveAsyncはIOutputStreamに書き込み、IInputStreamはLoadAsyncから読み取ります。 System.IOファイル ストリームを使用するには、AsOutputStreamとAsInputStreamに変換します。 ファイルには、これらのWindows ランタイムメソッドを await するための using System.IO; が、using Windows.Storage.Streams; および using System; と併せて必要です。

// Save ink strokes to a file.
using (FileStream fileStream = File.Create(filePath))
using (IOutputStream output = fileStream.AsOutputStream())
{
    await inkStrokeContainer.SaveAsync(output);
    await output.FlushAsync();
}

// Load ink strokes from a file.
using (FileStream fileStream = File.OpenRead(filePath))
using (IInputStream input = fileStream.AsInputStream())
{
    await inkStrokeContainer.LoadAsync(input);
}

InkToolbar.TargetInkCanvasを使用してツール バーをキャンバスに接続し続けたり、TargetInkPresenterを設定して、ツール バーをInkPresenterに直接接続したりできます。 ツール バーに独自のツールを追加するには、インク ツール バーのカスタマイズ に示すように、InkToolbarCustomToolButton と InkToolbarCustomToggleButton を使用します。 移行する前に、ルーラーと分度器ステンシルに関して報告された問題など、既知の制限事項を確認してください。

アプリで安定版を使用する必要がある場合、移行先の組み込みの手描き入力コントロールはありません。 Win2D でストロークをレンダリングし、ポインター入力を自分で処理するか、サード パーティ製の手描き入力ライブラリを使用します。 InkToolbarを置き換えるには、CommandBar 項目を含む AppBarToggleButton を使用します。

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)
- InkCanvas, InkToolbar, InkPresenter, InkStrokeContainer, and the other ink input types → Microsoft.UI.Xaml.Controls (experimental Windows App SDK releases only; if the project uses a stable release, flag them instead)
- Ink members that Windows App SDK 2.5.4-experimental doesn't include (new InkStrokeContainer(), assignments to InkPresenter.StrokeContainer, GetRecognitionResults, UpdateRecognitionResults, IsPenHapticFeedbackEnabled, InkToolbarRulerButton.Ruler, IsRulerButtonCheckedChanged, and progress or byte counts from SaveAsync and LoadAsync) → flag them
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- InkStroke, InkDrawingAttributes, InkPoint, InkStrokeBuilder → no change (Windows.UI.Input.Inking; use using aliases to avoid CS0104)

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
Do not add InkToolbarEraserKind, SelectedEraser, or other eraser APIs from Windows App SDK 2.4.1-experimental. Version 2.5.4-experimental removed them.
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 から移行する