パッケージ ID を使用したデバッグ

多くのWindows API (プッシュ通知、バックグラウンドタスク、共有ターゲット、スタートアップタスク、Windows AI API) では、アプリに package ID が必要です。開発中は、テストのたびに完全な MSIX インストーラーを構築する必要はありません。winapp には、アプリ ID をその場で提供する 2 つのコマンドが用意されています。

パッケージ化プロジェクトでVisual Studioを使用する場合 パッケージ化されたプロジェクトに既にVisual Studioを使用している場合は、デバッグに winapp は必要ない可能性があります。 Visual Studioは、パッケージの登録、ID、AUMID のアクティブ化、デバッガーの添付ファイル、アクティブ化コードのデバッグをすべて F5 から既に処理しています。また、高度なシナリオで使用するために、デバッグ → その他のデバッグターゲット → インストール済みアプリパッケージのデバッグ も提供します。次のワークフローは 、VS Code ユーザー、ターミナルベースのワークフロー、VS がネイティブにパッケージ化しないフレームワーク (Rust、Flutter、Tauri、Electron、plain C++) に最も役立ちます。

2 つの方法: `winapp run` と `create-debug-identity`

	`winapp run`	`create-debug-identity`
登録内容	完全な緩いレイアウトパッケージ (フォルダー全体)	スパースパッケージ (単一実行可能ファイル)
アプリの起動方法	winapp によって起動される (AUMID 起動または実行エイリアス)	exe を自分で起動します (コマンドライン、IDE など)
MSIX のインストールをシミュレートします	はい — 運用環境の動作に最も近い	いいえ — スパース・アイデンティティのみ
ファイルは所定の場所に留まる	AppX レイアウトディレクトリにコピー	はい — exe は元のパスにとどまります
ID スコープ	フォルダー全体の内容 (exe、DLL、アセット)	1 つの実行可能ファイル
デバッガーに対応	起動後に PID にアタッチするか、 `--no-launch` を使用してエイリアスを使用して起動する	IDE のデバッガーから直接起動します。exe は独自のIDを持ちます。
コンソールアプリのサポート	`--with-alias` ターミナルで stdin/stdout を保持する	ターミナルで exe を直接実行する
最適な用途	ほとんどのフレームワーク (.NET、C++、Rust、Flutter、Tauri)	Electron、または完全な IDE デバッガー制御が必要な場合 (F5)

どれをいつ使用するか

既定値: `winapp run`

ほとんどの開発ワークフローに winapp run を使用します。実際の MSIX インストールをシミュレートします。アプリは、運用環境と同じ ID、機能、ファイルの関連付けを取得します。

# Build your app, then:
winapp run .\build\output

次のようなときは `create-debug-identity` を使います。

exe はビルド出力とは別 です。たとえば、electron.exe が node_modules/ にあるという Electron アプリなどです。
スタートアップコードをデバッグする必要 があり、AUMID の起動後にデバッガーを十分に高速にアタッチできない
AUMID を使用して起動できない一部のデバッガーでは 、起動されたプロセスで ID が必要です。 create-debug-identity は exe を登録して、起動方法に関係なく ID を持ちます
スパースパッケージの動作 を具体的にテストしています (AllowExternalContent、TrustedLaunch)

# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

デバッグシナリオ

シナリオ A: ID を使用して実行する

最も簡単なワークフロー - ビルド、ID を使用した実行、完了。

winapp run .\build\Debug

Winapp は、フォルダーをルースレイアウトパッケージとして登録し、アプリを起動します。 ID が必要な API はすぐに機能します。これは、開発とテストのシナリオの大部分を対象とします。

現在のターミナルで stdin/stdout が必要な コンソールアプリ の場合は、 --with-alias追加します。

winapp run .\build\Debug --with-alias

シナリオ B: 実行中のアプリにデバッガーをアタッチする

winapp runで起動し、PID を書き留め、IDE のデバッガーをアタッチします。

winapp run .\build\Debug
# Output: Process ID: 12345

その後、IDE で次の手順を実行します。

VS Code: 実行とデバッグ→ [アタッチ] 構成を選択します (以下の IDE セットアップを参照)
WinDbg: windbg -p 12345

制限： アタッチする前に実行されるコードは見落とされます。スタートアップデバッグの場合は、シナリオ D (create-debug-identity) を使用します。

シナリオ C: ID を登録し、IDE から AUMID またはエイリアスを使用して起動する

--no-launchを使用してパッケージを登録し、その AUMID (run によって報告) または IDE からの実行エイリアスを使用してアプリを起動します。

手順 1: 起動せずにパッケージを登録します。

winapp run .\build\Debug --no-launch

手順 2: AUMID または 実行エイリアス (exe を直接ではなく) 経由で起動するように IDE を構成します。

AUMID を使用した起動: コマンド start shell:AppsFolder\<AUMID>を使用します。 winapp run は、アプリの登録時に AUMID を出力します。
エイリアスを使用して起動する: エイリアスはマニフェストで定義する必要があります (推奨Package.appxmanifest 、 appxmanifest.xml もサポートされています)。

大事な： ビルドフォルダーで exe を起動するだけでは、ID は提供 されません 。アプリは、AUMID アクティブ化またはその実行エイリアスを使用して開始する必要があります。これは、緩いレイアウトパッケージのしくみです。ID は、exe ファイルではなく、アクティブ化パスに関連付けられています。

シナリオ D: ID を使用して IDE から起動する (スタートアップデバッグ)

これは、 完全な IDE コントロールを使用してスタートアップコードをデバッグするための最適な アプローチです。IDE のデバッガーは、最初の命令からプロセスを制御し、起動方法に関係なく exe に ID を持ちます。

winapp create-debug-identity .\build\Debug\myapp.exe

次に、ターミナルから、VS Code の F5 からスクリプトから任意の方法で exe を起動します。 Windows が sparse パッケージを直接指すように登録したため、exe には ID があります。

winapp runとの違い:create-debug-identityでは、ID は exe 自体に関連付けられます (Add-AppxPackage -ExternalLocation経由)。 winapp runでは、ID はルーズレイアウトパッケージに関連付けられます。アプリは AUMID またはエイリアスを使用して起動する必要があります。これにより、ide を起動して exe を直接デバッグする必要がある場合は、 create-debug-identity の方が適しています。

これは、exe パスがソースディレクトリと異なる Electron アプリ にも最適なアプローチです。

シナリオ E: デバッグ出力とクラッシュ診断をキャプチャする

OutputDebugStringメッセージと初回例外をインラインでキャプチャします。フレームワークノイズ (WinUI、COM、DirectX 内部トレース) はコンソールからフィルター処理されるため、アプリのデバッグメッセージのみが表示されます。完全な調査のために、すべてが引き続きログファイルに書き込まれます。

アプリがクラッシュすると、ミニダンプが自動的にキャプチャされ、分析されます。

winapp run .\build\Debug --debug-output

クラッシュした場合、出力には、ソースファイルと行番号を含む例外の種類、メッセージ、スタックトレースが含まれます (ビルド出力フォルダーの PDB から解決されます)。マネージド (.NET) クラッシュは、外部ツールなしで即座に分析されます。ネイティブ (C++/WinRT) がクラッシュすると、モジュール名とオフセットが表示されます。完全な関数名の PDB シンボルをダウンロードする --symbols を追加します。

winapp run .\build\Debug --debug-output --symbols

大事な： これにより、winapp がデバッガーとしてアタッチされます。 Windowsではプロセスごとに 1 つのデバッガーしか許可されないため、Visual Studio、VS Code、または WinDbg もアタッチできません。

IDE のセットアップ

VS Code

WinApp VS Code 拡張機能は、パッケージ ID を使用してアプリを起動し、デバッガーをアタッチするカスタム winapp デバッグの種類を提供します。これらはすべて、1 回の F5 キーを押して実行します。

ID 認証を用いたワンプレスF5デバッグ

winapp起動構成を.vscode/launch.jsonに追加します。

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

F5 キーを押すと、

拡張機能は、ワークスペースをスキャンして、 .exe ファイルを含むビルド出力ディレクトリを探します。
実行するビルドフォルダーを選択します (または、プロンプトをスキップするように inputFolder 設定します)。
winapp run経由でアプリを起動し、パッケージ ID を付与します。
子デバッグセッションは、指定したデバッガーを使用して実行中のプロセスにアタッチします。

デバッガーがアタッチされると、完全な VS Code デバッグエクスペリエンスが得られます。余白をクリックしてブレークポイントを設定し、コードを 1 行ずつ (F10)、関数にステップイン (F11)、変数ペインで変数を検査し、 デバッグコンソールで式を評価します。アプリはパッケージ ID で実行されるため、ID に依存する API は運用環境とまったく同じように動作します。

大事な：winappデバッグの種類では、プロジェクトは自動的にビルドされません。コードを変更した後、F5 キーを押す前に再構築します。

`preLaunchTask` を使用してビルドを自動化する

再構築を忘れないようにするには、すべてのデバッグセッションの前にプロジェクトをビルドする preLaunchTask を追加します。

.vscode/tasks.jsonでビルドタスクを定義します (例: .NET)。

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}

launch.jsonで参照します。

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

設定プロパティ

財産	タイプ	Default	Description
`inputFolder`	文字列		アプリバイナリを含むビルド出力フォルダーへのパス (例: `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`)。設定されていない場合は、フォルダーを選択するように求められます。
`manifest`	文字列		AppX マニフェストファイルへのパス ( `AppxManifest.xml`、 `Package.appxmanifest`、 `appxmanifest.xml`など)。設定されていない場合、CLI は入力フォルダーまたは現在のディレクトリから自動検出します。
`debuggerType`	文字列	`coreclr`	使用する基になるデバッガー (`coreclr`、 `cppvsdbg`、または `node`)。
`workingDirectory`	文字列	workspace フォルダー	アプリケーションの作業ディレクトリ。
`args`	文字列		アプリケーションに渡すコマンドライン引数。
`outputAppxDirectory`	文字列		ルーズレイアウトパッケージの出力ディレクトリ。既定値は、入力フォルダー内の `AppX` フォルダーです。
`port`	数値	`9229`	(`node` のみ) Node.js `--inspect` リスナーと接続接続に使用されるポート。既定のポートが既に使用されている場合はオーバーライドします。

サポートされているデバッガー

`debuggerType`	Language	必要な拡張機能
`coreclr` (既定値)	C# / .NET	C# 開発キット
`cppvsdbg`	C / C++	C/C++
`node`	Node.js/Electron	組み込み

C++ プロジェクトの例:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

デバッグ ID の作成によるスタートアップデバッグ

最初の命令からスタートアップコードをデバッグする必要がある場合は、F5 アタッチアプローチで初期コードが見逃される可能性があります。代わりに、コマンドパレット () から Ctrl+Shift+P コマンドを使用して実行可能ファイルのスパースパッケージを登録し、標準デバッガーで起動します。

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

create-debug-identityは exe 自体に ID を登録するため、アプリの起動方法に関係なく、標準の VS Code 起動構成からの ID を持ちます。

実行中のプロセスにアタッチする

ターミナルから winapp run を使用して起動してからアタッチする場合は、標準のアタッチ構成を使用します。

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

C++/Rust の場合は、 "type": "cppvsdbg" (MSVC) または "type": "lldb" (LLDB) を使用します。

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

クリーンアップ

テストが完了したら、コマンドパレットから WinApp: Unregister Package を実行して、VS Code を終了せずにサイドロードされた開発パッケージを削除します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-12