winui-setup

目的

ほかのすべての winui-* スキルが前提とする前提条件をインストールし、確認します。WinApp CLI 0.7 は winapp new を通じて WinUI テンプレートの検出とインストールを行います。テンプレートパックを別途インストールしないでください。 プロジェクトのターゲットフレームワークには、CLI の最小要件より新しい .NET SDK が必要な場合があります。

重要

ユーザー単位の前提条件（WinApp CLI）は、確認を求めずにインストールし、変更内容をユーザーに伝えてください。管理者権限（UAC）や大規模なツールチェーンが必要なものについては、事前に確認してください。.NET SDK、開発者モード、Native AOT ビルドツールが該当します。Windows Sandbox の有効化はユーザー自身が行います。

このスキルは冪等です。最初にすべてを検出し、必要なものだけをインストールまたはアップグレードして、最後に1回だけ概要を表示します。

手順

すべてを検出する

変更を加える前にユーザーが全体の状態を確認できるよう、これらのチェックをまとめて実行します。

$minimumDotNet = [version]'8.0.100'
$minimumWinApp = [version]'0.7.0'

# .NET SDK — project-mode winapp run requires SDK 8.0.100+
$dotnetSdks = @(& dotnet --list-sdks 2>$null) | ForEach-Object {
    $text = ($_ -replace ' \[.*$','').Trim()
    $parsed = $null
    if ([version]::TryParse(($text -split '-')[0], [ref]$parsed)) { $parsed }
}
$dotnetVersion = $dotnetSdks |
    Where-Object { $_ -ge $minimumDotNet } |
    Sort-Object -Descending |
    Select-Object -First 1
$dotnetOk = $null -ne $dotnetVersion

# WinApp CLI — require released 0.7+ for the migrated workflows
$winappCmd = Get-Command winapp -ErrorAction SilentlyContinue
$winappVersion = $null
$winappPrerelease = $false
if ($winappCmd) {
    foreach ($line in @(& winapp --version 2>$null)) {
        $match = [regex]::Match(
            [string]$line,
            '^\s*v?(?<version>\d+\.\d+\.\d+)(?:-(?<prerelease>[0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\s*$'
        )
        if ($match.Success) {
            $parsed = $null
            if ([version]::TryParse($match.Groups['version'].Value, [ref]$parsed)) {
                $winappVersion = $parsed
                $winappPrerelease = $match.Groups['prerelease'].Success
            }
        }
    }
}
$winappOk = ($winappVersion -ge $minimumWinApp) -and -not $winappPrerelease

# Developer Mode
$devModeOk = ((Get-ItemProperty `
    -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
    -Name AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue
).AllowDevelopmentWithoutDevLicense) -eq 1

一度にステータステーブルを表示します。

.NET SDK >= 8.0.100     [OK] found 10.0.100
WinApp CLI >= 0.7.0     [!] found 0.6.0 — will upgrade
Developer Mode          [X] disabled — needs admin to enable

不足しているものをインストールする

.NET SDK（事前に確認）

SDK インストーラーはマシン全体に適用され、UAC が起動します。最初にユーザーに確認してください。 同意があり、8.0.100 以上の SDK が見つからなかった場合は、推奨 SDK をインストールします。

winget install --id Microsoft.DotNet.SDK.10 --exact --silent --accept-package-agreements --accept-source-agreements

すでに CLI の最小要件と、要求されたプロジェクトのターゲットフレームワーク／global.json の両方を満たす SDK がある場合は、別の SDK をインストールしないでください。CLI の最小要件を満たしていても、8.x SDK で net10.0-windows アプリをビルドできるとは限りません。 基本チェックに合格していても、要求されたプロジェクトで別の SDK が必要な場合は、その要件を報告し、該当する SDK のインストールを提案してください。プロジェクトの準備が完了したと判断しないでください。ユーザーが辞退した場合は、後で使用するコマンドを表示します。

WinApp CLI（管理者権限は不要）

WinApp CLI はユーザー単位の MSIX パッケージなので、確認を求めずにインストールまたはアップグレードし、変更内容をユーザーに伝えてください。winapp が見つからない場合はインストールします。リリース版 0.7.0 より古い場合はアップグレードします。インストール済みのバージョンがすでに最小要件を満たしている場合は、どちらもスキップします。

# When winapp is missing
winget install --id Microsoft.WinAppCli --exact --silent --accept-package-agreements --accept-source-agreements

# When winapp does not meet the released 0.7.0 minimum
winget upgrade --id Microsoft.WinAppCli --exact --silent --accept-package-agreements --accept-source-agreements

winget によるインストールまたはアップグレード後は、PATH を更新します。

$env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' +
            [Environment]::GetEnvironmentVariable('Path','User')

バージョン検出を再実行します。リリース版 0.7.0 以降が引き続き利用できない場合は、実際のバージョンを報告してセットアップをブロック扱いにします。古いコマンドへのフォールバックはしないでください。プレビュー版は、ユーザーがプレビュー検証を求めた場合を除き、要件を満たしません。

開発者モード（事前に確認）

開発者モードには管理者権限への昇格が必要です。UAC を起動する前にユーザーに確認してください。 同意があった場合に限り、この操作だけを昇格して実行します。

Start-Process powershell -Verb RunAs -ArgumentList @(
    '-NoProfile','-Command',
    "New-Item -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Force | Out-Null; " +
    "Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' " +
    "-Name AllowDevelopmentWithoutDevLicense -Type DWord -Value 1"
) -Wait

ユーザーが辞退するか UAC を閉じた場合は、概要の表示に進み、後で使用するコマンドを表示します。

要求されたワークフローの追加要件

ワークフロー	追加要件
Native AOT の発行／実行	Windows のネイティブコンパイラー／リンカーツールチェーン：C++ によるデスクトップ開発を含む Visual Studio または Build Tools。対象アーキテクチャのツールと Windows SDK も必要です。Native AOT の前提条件を参照してください。通常の JIT による反復開発では不要です。
Windows Sandbox でのアプリ実行と UI 自動化（利用可能な場合に推奨）	WinApp の統合には、Windows 11 24H2 以降、ハードウェア仮想化、および動作する Windows Sandbox 機能／クライアントが必要です。対応エディションは Pro、Enterprise、Education です。Home は対象外です。入力／キャプチャには、ロック解除されたホストと、接続済みで最小化されていないクライアントが必要です。WinApp Sandbox の前提条件を参照してください。

これらは基本のツールチェーンとは分けて報告してください。winapp target snapshot sandbox --json は、既存のゲストを起動も修復もせずに検査します。「実行中のターゲットがありません」という状態だけでは、Windows の機能が利用できないことを意味しません。Windows Sandbox が利用できない場合の対応は、winui-ui-testing Step 1 で定義されています。

Windows Sandbox の有効化はユーザーの操作です（管理者権限と再起動が必要です）。ユーザーにWindows の機能の有効化または無効化を開いてWindows Sandboxを選択し、再起動を求められた場合は再起動するよう依頼してください。ハードウェア仮想化を有効にする必要があります。VM では、ネストされた仮想化も必要になる場合があります。Microsoft の対応エディションとインストール手順を参照してください。

最終サマリー

サマリーは必ず 1 つだけ出力してください。

==== winui-setup summary ====
.NET SDK >= 8.0.100     [>] already present (10.0.100)
WinApp CLI >= 0.7.0     [OK] upgraded to 0.7.0
Developer Mode          [OK] enabled

要件を満たしたワークフローについてのみ、準備が整ったことを報告してください。現在のハーネスでwinui-devオーケストレーターエージェントを利用できる場合は、そのエージェントで新しいセッションを開始し、WinUI アプリをビルドするよう依頼してください。利用できない場合は、現在のハーネスで新しいセッションを開始し、WinUI タスクを実行するよう依頼してください。関連するwinui-*スキルは必要に応じて読み込まれます。

GitHub Copilot CLI の場合、たとえば次のようにします。

copilot --agent winui:winui-dev -p "build me a WinUI 3 markdown editor"

行ってはいけないこと

• Visual Studio をインストールしないでください。インストールは任意です。Native AOT に必要なのは MSVC C++ ビルドツールのみで、別途、明示的な承認を得てセットアップします。
• ユーザーの AI コーディングハーネスをインストールまたはアップグレードしないでください。このスキルが管理するのは、Windows／WinUI 開発の前提条件のみです。
• セッション全体を昇格させないでください。承認された個別のセットアップ操作に限り、昇格を求めてください。
• 失敗したインストールを黙って再試行しないでください。