WinUI 3 マイグレーション ガイド

UWP アプリを WinUI 3 / Windows App SDK に移行する場合、または生成されたコードが従来の UWP パターンではなく正しい WinUI 3 API を使用していることを確認する場合に、このスキルを使用します。

---

名前空間の変更

すべての Windows.UI.Xaml.* 名前空間は Microsoft.UI.Xaml.* に移行されます:

UWP 名前空間	WinUI 3 名前空間
Windows.UI.Xaml	Microsoft.UI.Xaml
Windows.UI.Xaml.Controls	Microsoft.UI.Xaml.Controls
Windows.UI.Xaml.Media	Microsoft.UI.Xaml.Media
Windows.UI.Xaml.Input	Microsoft.UI.Xaml.Input
Windows.UI.Xaml.Data	Microsoft.UI.Xaml.Data
Windows.UI.Xaml.Navigation	Microsoft.UI.Xaml.Navigation
Windows.UI.Xaml.Shapes	Microsoft.UI.Xaml.Shapes
Windows.UI.Composition	Microsoft.UI.Composition
Windows.UI.Input	Microsoft.UI.Input
Windows.UI.Colors	Microsoft.UI.Colors
Windows.UI.Text	Microsoft.UI.Text
Windows.UI.Core	Microsoft.UI.Dispatching (ディスパッチャー用)

---

Copilot の最も一般的な 3 つのミス

1. XamlRoot がない ContentDialog

// ❌ 間違い — WinUI 3 で InvalidOperationException をスロー
var dialog = new ContentDialog
{
    Title = "Error",
    Content = "Something went wrong.",
    CloseButtonText = "OK"
};
await dialog.ShowAsync();

// ✅ 正解 — 表示前に XamlRoot を設定
var dialog = new ContentDialog
{
    Title = "Error",
    Content = "Something went wrong.",
    CloseButtonText = "OK",
    XamlRoot = this.Content.XamlRoot  // WinUI 3 では必須
};
await dialog.ShowAsync();

2. ContentDialog の代わりに MessageDialog を使用

// ❌ 間違い — UWP API、WinUI 3 デスクトップでは使用不可
var dialog = new Windows.UI.Popups.MessageDialog("Are you sure?", "Confirm");
await dialog.ShowAsync();

// ✅ 正解 — ContentDialog を使用
var dialog = new ContentDialog
{
    Title = "Confirm",
    Content = "Are you sure?",
    PrimaryButtonText = "Yes",
    CloseButtonText = "No",
    XamlRoot = this.Content.XamlRoot
};
var result = await dialog.ShowAsync();
if (result == ContentDialogResult.Primary)
{
    // ユーザーが確認
}

3. DispatcherQueue の代わりに CoreDispatcher を使用

// ❌ 間違い — CoreDispatcher は WinUI 3 に存在しない
await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
{
    StatusText.Text = "Done";
});

// ✅ 正解 — DispatcherQueue を使用
DispatcherQueue.TryEnqueue(() =>
{
    StatusText.Text = "Done";
});

// 優先度付き:
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.High, () =>
{
    ProgressBar.Value = 100;
});

---

ウィンドウ化マイグレーション

ウィンドウ参照

// ❌ 間違い — Window.Current は WinUI 3 に存在しない
var currentWindow = Window.Current;

// ✅ 正解 — App で静的プロパティを使用
public partial class App : Application
{
    public static Window MainWindow { get; private set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        MainWindow = new MainWindow();
        MainWindow.Activate();
    }
}
// どこからでもアクセス: App.MainWindow

ウィンドウ管理

UWP API	WinUI 3 API
ApplicationView.TryResizeView()	AppWindow.Resize()
AppWindow.TryCreateAsync()	AppWindow.Create()
AppWindow.TryShowAsync()	AppWindow.Show()
AppWindow.TryConsolidateAsync()	AppWindow.Destroy()
AppWindow.RequestMoveXxx()	AppWindow.Move()
AppWindow.GetPlacement()	AppWindow.Position プロパティ
AppWindow.RequestPresentation()	AppWindow.SetPresenter()

タイトル バー

UWP API	WinUI 3 API
CoreApplicationViewTitleBar	AppWindowTitleBar
CoreApplicationView.TitleBar.ExtendViewIntoTitleBar	AppWindow.TitleBar.ExtendsContentIntoTitleBar

---

ダイアログとピッカーのマイグレーション

ファイル/フォルダ ピッカー

// ❌ 間違い — UWP スタイル、ウィンドウ ハンドルなし
var picker = new FileOpenPicker();
picker.FileTypeFilter.Add(".txt");
var file = await picker.PickSingleFileAsync();

// ✅ 正解 — ウィンドウ ハンドルで初期化
var picker = new FileOpenPicker();
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);
picker.FileTypeFilter.Add(".txt");
var file = await picker.PickSingleFileAsync();

スレッド処理マイグレーション

UWP パターン	WinUI 3 同等物
CoreDispatcher.RunAsync(priority, callback)	DispatcherQueue.TryEnqueue(priority, callback)
Dispatcher.HasThreadAccess	DispatcherQueue.HasThreadAccess
CoreDispatcher.ProcessEvents()	同等物なし — 非同期コードをリストラクチャ
CoreWindow.GetForCurrentThread()	利用不可 — DispatcherQueue.GetForCurrentThread() を使用

主な違い: UWP は ASTA (Application STA) を使用し、ビルトインの再入可能性ブロック機能を持ちます。WinUI 3 は標準 STA を使用し、この保護機能がありません。非同期コードがメッセージをポンプする場合、再入可能性の問題に注意してください。

---

バックグラウンド タスク マイグレーション

// ❌ 間違い — UWP IBackgroundTask
public sealed class MyTask : IBackgroundTask
{
    public void Run(IBackgroundTaskInstance taskInstance) { }
}

// ✅ 正解 — Windows App SDK AppLifecycle
using Microsoft.Windows.AppLifecycle;

// アクティベーションを登録
var args = AppInstance.GetCurrent().GetActivatedEventArgs();
if (args.Kind == ExtendedActivationKind.AppNotification)
{
    // バックグラウンド アクティベーションを処理
}

---

アプリ設定マイグレーション

シナリオ	パッケージ化されたアプリ	パッケージ化されていないアプリ
シンプルな設定	ApplicationData.Current.LocalSettings	LocalApplicationData の JSON ファイル
ローカル ファイル ストレージ	ApplicationData.Current.LocalFolder	Environment.GetFolderPath(SpecialFolder.LocalApplicationData)

---

GetForCurrentView() の置き換え

すべての GetForCurrentView() パターンは WinUI 3 デスクトップ アプリでは使用不可能です:

UWP API	WinUI 3 置き換え
UIViewSettings.GetForCurrentView()	AppWindow プロパティを使用
ApplicationView.GetForCurrentView()	AppWindow.GetFromWindowId(windowId)
DisplayInformation.GetForCurrentView()	Win32 GetDpiForWindow() または XamlRoot.RasterizationScale
CoreApplication.GetCurrentView()	利用不可 — ウィンドウを手動で追跡
SystemNavigationManager.GetForCurrentView()	NavigationView で戻るナビゲーションを直接処理

---

テスト マイグレーション

UWP 単体テスト プロジェクトは WinUI 3 では機能しません。WinUI 3 テスト プロジェクト テンプレートに移行する必要があります。

UWP	WinUI 3
Unit Test App (Universal Windows)	Unit Test App (WinUI in Desktop)
UWP タイプを持つ標準 MSTest プロジェクト	XAML ランタイム用に WinUI テスト アプリを使用する必要があります
すべてのテストで [TestMethod]	ロジックには [TestMethod]、XAML/UI テストには [UITestMethod]
Class Library (Universal Windows)	Class Library (WinUI in Desktop)

// ✅ WinUI 3 単体テスト — XAML と連携する場合は [UITestMethod] を使用
[UITestMethod]
public void TestMyControl()
{
    var control = new MyLibrary.MyUserControl();
    Assert.AreEqual(expected, control.MyProperty);
}

重要: [UITestMethod] 属性はテスト ランナーに対して、XAML UI スレッドでテストを実行するよう指示します。これは任意の Microsoft.UI.Xaml タイプをインスタンス化するために必要です。

---

マイグレーション チェックリスト

1. すべての Windows.UI.Xaml.* using ディレクティブを Microsoft.UI.Xaml.* で置き換え
2. Windows.UI.Colors を Microsoft.UI.Colors で置き換え
3. CoreDispatcher.RunAsync を DispatcherQueue.TryEnqueue で置き換え
4. Window.Current を App.MainWindow 静的プロパティで置き換え
5. すべての ContentDialog インスタンスに XamlRoot を追加
6. すべてのピッカーを InitializeWithWindow.Initialize(picker, hwnd) で初期化
7. MessageDialog を ContentDialog で置き換え
8. ApplicationView/CoreWindow を AppWindow で置き換え
9. CoreApplicationViewTitleBar を AppWindowTitleBar で置き換え
10. すべての GetForCurrentView() 呼び出しを AppWindow 同等物で置き換え
11. Share and Print managers の相互運用を更新
12. IBackgroundTask を AppLifecycle アクティベーションで置き換え
13. プロジェクト ファイルを更新: TFM を net10.0-windows10.0.22621.0 に、<UseWinUI>true</UseWinUI> を追加
14. 単体テストを Unit Test App (WinUI in Desktop) プロジェクトに移行; XAML テストには [UITestMethod] を使用
15. パッケージ化および非パッケージ化の両方の構成をテスト