winui-wpf-migration

移行プロセス

winui-dev-workflow に記載されている WinApp CLI 0.7 以降の前提条件と、アプリごとのアナライザーのセットアップを使用してください。通常の SDK パスには、.NET 8.0.100 以降 と ターゲット TFM で必要な SDK の両方が必要です。Native AOT には、さらに MSVC／デスクトップ C++ ツールが必要です。前提条件が満たされていない場合は、同ドキュメントの説明に従って対応してください。

ステップ 1：WPF ソースを監査する

コードを書く前に、WPF 固有の API を一覧にします。

# Find all WPF namespace usage
Select-String -Path (Get-ChildItem -Recurse -Filter "*.cs" | Where-Object { $_.FullName -notlike "*\obj\*" }) -Pattern "System\.Windows\." | Select-Object -Property Filename, LineNumber, Line

使用している WPF コントロール、カスタム MVVM フレームワーク、画像処理 API、スレッド処理パターン、Win32 相互運用を一覧にします。

ステップ 2：WinUI 3 プロジェクトを作成し、名前空間を合わせる

winapp new --name <AppName> --template winui-mvvm --template-version latest --use-defaults

すぐに .csproj の <RootNamespace> を WPF の名前空間に合わせて設定します。App.xaml、MainWindow.xaml およびそれぞれのコードビハインドファイルの x:Class を更新します。winui-dev-workflow に従ってアナライザーを追加します。コードを移植する前にビルドし、問題がないことを確認します。

API の置き換えを実装する前に、古い WPF プロジェクトやマシンの SDK ではなく、WinUI プロジェクトのディレクトリからアプリプロジェクトを復元し、正確な参照を確認します。

winapp find-api DispatcherQueue --json --project-dir .
winapp find-api members DispatcherQueue --filter TryEnqueue --json --project-dir .
winapp find-api check-property ListView ItemsSource SelectionMode --json --project-dir .

使用例は winapp find-ui "<intent>" で確認してください。プロジェクトの選択と API の一括確認については、winui-design を参照してください。

ステップ 3：名前空間を置き換える

WPF	WinUI 3
System.Windows	Microsoft.UI.Xaml
System.Windows.Controls	Microsoft.UI.Xaml.Controls
System.Windows.Media	Microsoft.UI.Xaml.Media
System.Windows.Input	Microsoft.UI.Xaml.Input
System.Windows.Data	Microsoft.UI.Xaml.Data
System.Windows.Threading.Dispatcher	Microsoft.UI.Dispatching.DispatcherQueue
PresentationCore / PresentationFramework	完全に削除

ステップ 4：コントロールを置き換える

WPF コントロール	WinUI 3 の同等機能
DataGrid	グリッド列ヘッダーを備えた ListView
WrapPanel	ItemsRepeater + UniformGridLayout
TabControl	TabView
StatusBar	下部に TextBlock 要素を配置した Grid の行
Menu / MenuItem	MenuBar / MenuBarItem / MenuFlyoutItem
ToolBar	CommandBar
Expander（カスタム）	Expander（組み込み）

ステップ 5：スレッド処理を置き換える

// WPF
Application.Current.Dispatcher.Invoke(() => { /* UI work */ });

// WinUI 3
dispatcherQueue.TryEnqueue(() => { /* UI work */ });

DispatcherQueue.GetForCurrentThread() で取得します。WinUI 3 に Application.Current.Dispatcher はありません。

ステップ 6：画像処理を置き換える

重要： PresentationCore.dll と System.Windows.Media.Imaging は WinUI XAML コンパイラーをクラッシュさせます。これはアーキテクチャ上の非互換性であり、回避策はありません。

• 移行開始時に System.Windows.Media.Imaging の参照をすべて削除します
• Windows.Graphics.Imaging（WinRT）または Microsoft.UI.Xaml.Media.Imaging.BitmapImage に置き換えます
• <UseWPF>true</UseWPF> は追加しないでください。ビルドが気づかないうちに破損します
• 画像処理コードが大量にある場合は、早い段階（ステップ 7 ではなくステップ 2）で移行します

ステップ 7：MVVM フレームワークを置き換える

カスタムの ObservableObject／RelayCommand／DelegateCommand を削除します。CommunityToolkit.Mvvm を使用します。

• INotifyPropertyChanged の基底クラス → [ObservableProperty] を使った ObservableObject の partial プロパティ（MVVMTK0045 を修正し、フィールドを残さないでください）
• カスタムの RelayCommand → [RelayCommand] 属性
• 型が明確な場合は {x:Bind} を優先し、必要に応じて実行時の {Binding}／DisplayMemberPath を使用します。バインディングモード、x:DataType、AOT 対応の実行時バインディングについては、winui-packaging の references/sourcegen-patterns.md を参照してください。
• DynamicResource → {ThemeResource}

ステップ 8：リソースを置き換える

• .resx → .resw（コピーして Strings\en-us\ に名前を変更）
• ローカライズ文字列の {x:Static} → x:Uid
• Properties.Resources.Key → ResourceLoader.GetString("Key")

重要なルール

• ❌ PresentationCore、PresentationFramework、または System.Windows.Controls アセンブリを参照しないでください
• ❌ <UseWPF>true</UseWPF> を追加しないでください
• パッケージ化をデフォルトのままにしてください。パッケージ化されていない状態での実験については、winui-dev-workflow の「重要なルール」を参照してください。
• ❌ Package.appxmanifest を削除しないでください
• ❌ App.xaml / App.xaml.cs を上書きしないでください。WPF のコードは WinUI 3 のボイラープレートにマージしてください
• ✅ .exe を直接起動するのではなく、プロジェクトモードの winapp run で起動してください。
• ✅ 移行はファイル単位のタスクに分割してください。一度に大規模な書き換えを行わないでください

移行後の検証

# Check for remaining WPF references (should return nothing)
Select-String -Path (Get-ChildItem -Recurse -Filter "*.cs" | Where-Object { $_.FullName -notlike "*\obj\*" }) -Pattern "System\.Windows\."

# Verify packaging preserved
Test-Path "Package.appxmanifest"  # should be True

# Build (the analyzer participates when installed)
dotnet build .\MyApp.csproj -p:Platform=x64

# Run the migrated app
winapp run .\MyApp.csproj --detach --json

UI の検証については winui-ui-testing を、クラッシュの診断については winui-dev-workflow を参照してください。AOT を使用する場合は、ワークフローの AOT パスを使って公開済みの成果物もテストしてください。上記の実行は Release でも JIT です。