アプリケーション機能プロファイラー (ACP)

[アーティクル]
10/16/2024

パッケージ化されたアプリケーションから、サンドボックスの外部にあるリソースにアクセスする必要が生じる場合があります。このようなリソースの例には、ユーザーファイル、画像、レジストリ項目、カメラ、位置情報、マイクなどがあります。機能宣言により、サンドボックス化されたアプリケーションはそれらのリソースの一部にアクセスできるようになります。宣言は、サンドボックス化されたアプリケーションのパッケージマニフェストで行われます。「msix-packaging-tool」を参照してください。

アプリケーション機能プロファイラーは、アプリケーションパッケージによって宣言する必要がある機能を特定し、必要なリソースアクセスを付与するために役立つツールセットです。さらに、アプリケーションパッケージによる失敗したアクセス試行に関する有用な診断情報も提供されます。

重要

この機能はプレビュー段階です: 一部の情報はリリース前の製品に関する内容であり、製品版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

ターゲットシステムをプロファイリング用に準備する

ターゲットシステムをプロファイリング用にセットアップするには、次の手順が必要です。

ユーザーアカウントに、ターゲットの Windows システムに対する管理者権限があることを確認します。
ターゲットシステムで開発者モードを有効にします。この設定は、Windows の [設定] | [プライバシー & セキュリティ] | [開発者向け] にあります。詳細については、「デバイスを開発用に有効にする」を参照してください。
PowerShell 7.3 以降をインストールします。インストール手順については、「Windows への PowerShell のインストール」を参照してください。

これは、Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler モジュールの互換性のために必要です。
Windows Performance Recorder (WPR) がまだインストールされていない場合はインストールし、PATH に追加します。

手順については、「Windows パフォーマンスレコーダー」を参照してください。
```
Get-Command wpr
```
アプリケーション機能プロファイラーアーカイブをダウンロードし、使いやすいパスに解凍します。

アプリケーション機能プロファイラーアーカイブは、このプロジェクトのリリースアセットからダウンロードできます。
msix-packaging-tool の指示に従ってアプリケーションをパッケージ化し、ターゲットシステムにインストールします。
ターゲットアプリケーションパッケージマニフェスト (推奨) またはターゲットアプリケーションパッケージの完全名、あるいはその両方を取得します。
1. (推奨) ターゲットアプリケーションパッケージマニフェストを取得します。これを行う最も簡単な方法は、MSIX パッケージ化ツールを使用してマニフェストを開き、マニフェストのコピーを使いやすいパスに保存することです。
2. PowerShell で次のコマンドを実行して、アプリケーションパッケージの完全名を取得します。
```
Get-AppxPackage | where-object {$_.name -like '*Test-AppSilo*'}
```
(オプション) Windows Performance Analyzer をインストールします。手順については、「Windows Performance Analyzer」を参照してください。これはプロファイリングに必須ではありませんが、ACP によってキャプチャおよび出力されるデータの一部を視覚化する際に役立つ場合があります。

PowerShell モジュールをインポートします

モジュールに関する情報は、「Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler モジュール」で確認できます。

このモジュールをインポートするには、管理者権限で PowerShell で次のコマンドを実行します。

Import-Module .\Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.dll

Note

Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.dll モジュールは、上記の「ターゲットシステムをプロファイリング用に準備する」の手順 5 でアーカイブから抽出した ACP フォルダーにあります。

プロファイリングの開始

Start-Profiling コマンドレットは、ターゲットアプリケーションパッケージマニフェストへのパスまたはアプリケーションパッケージの完全名を取得します。

Start-Profiling は、ターゲットアプリケーションパッケージをトレースログ用にインストルメント化し、ターゲットアプリケーションパッケージによるアクセス試行に対してトレースログプロバイダーを有効にします。詳細については、「Start-Profiling」を参照してください。

プロファイリングを開始するには、管理者権限で PowerShell を使用して、次のコマンドを実行します。

Start-Profiling -ManifestPath TestApp-AppXManifest.xml

Start-Profiling コマンドレットを実行する PowerShell コマンドウィンドウを示すスクリーンショット

アプリケーションシナリオを実行する

このステップでは、すべてのクリティカルなアプリケーションシナリオを実行することが重要です。プロファイリング結果の包括性は、このステップで実行するシナリオに左右されます。実行するアプリケーションシナリオが増えるほど、上記で開始されたトレースログセッションによってキャプチャされるデータの量が増え、より完全になります。

プロファイリングの停止

Stop-Profiling コマンドレットは、開始されたアクセス試行トレースログセッションを停止し、トレースログ用にインストルメンテーションされたすべてのアプリケーションパッケージのインストルメンテーションを削除します。

Stop-Profiling は、出力イベントトレースログ (.etl) ファイルに使用されるパスを制御するオプションのトレースパスパラメーターを受け入れます。既定では <current_directory>\trace.etl です。詳細については、「Stop-Profiling」を参照してください。

プロファイリングを停止するには、管理者権限で PowerShell で次のコマンドを実行します。

Stop-Profiling

Stop-Profiling コマンドレットを実行する PowerShell コマンドウィンドウを示すスクリーンショット

プロファイリング結果を取得する

Get-ProfilingResults コマンドレットは、上記の手順で取得したトレースファイルを解析し、トレース内で識別されたアプリケーションパッケージに必要な機能を検索します。特定のパッケージへのフィルターが指定されていない限り、トレースで識別されたすべてのアプリケーションパッケージの機能と情報を出力します。

Get-ProfilingResults は、解析するトレースファイルへのパスを受け入れます。パスが指定されていない場合、Get-ProfilingResults は Stop-Profiling を呼び出して、解析するトレースの取得を試行します。

Get-ProfilingResults は、オプションでターゲットアプリケーションマニフェストへのパスを受け取ります。解析されたトレースの情報がターゲットアプリケーションパッケージマニフェストに起因するものである場合、ファイルは出力機能を使用して直接編集されます。それ以外の場合は、トレースで識別されたパッケージごとにマニフェストのコピーが作成され、識別された機能が追加されます。

詳細については、「Get-ProfilingResults」を参照してください。

次のコマンドはトレースファイルを解析し、結果を出力します。

Get-ProfilingResults -EtlFilePaths trace.etl -ManifestPath TestApp-AppXManifest.xml

Get-ProfilingResults コマンドレットを実行する PowerShell コマンドウィンドウを示すスクリーンショット

アプリの再パッケージ化

新しく識別された機能を使用してターゲットアプリケーションを再パッケージ化するには:

新しく識別された機能をターゲットアプリケーションパッケージマニフェストに含めます (Get-ProfilingResults は、マニフェスト (提供されている場合) を直接編集します)。
msix-packaging-tool の指示に従って、ターゲットアプリケーションを新しい機能で再パッケージ化し、再インストールします。

ヘルパーコマンドレット

Merge-ProfilingResults コマンドレットを使用すると、Get-ProfilingResults の複数回の実行からの出力をマージできます。

プロファイリング出力の解釈

Get-ProfilingResults の出力は次の内容で構成されます。

マニフェスト形式の機能

ユーザーが -ManifestPath スイッチを使用して編集するマニフェストを提供し、かつそのマニフェストが属するパッケージが入力トレースで識別された場合、Get-ProfilingResults はマニフェストファイルを直接編集して、パッケージのトレースで識別された機能を含めます。それ以外の場合、Get-ProfilingResults は、トレースファイルで識別された各パッケージについて、<package full name><manifest name>.xml という名前のファイルを出力します。このファイルには、対応するパッケージのトレースで識別された機能を格納した <Capabilities> 要素が含まれています。

Note

Get-ProfilingResults が識別できる特別な種類の機能が 2 つあります。出力マニフェスト内では、これらの結果に XML コメントが付きます。
- プライバシー関連機能: これらの機能は、カメラ、位置情報、マイクなど、プライバシーに関連するリソースを保護します。アプリケーションパッケージがこれらのリソースにアクセスする必要がある場合は、これらの機能を宣言する必要があります。ただし、機能の宣言だけでは、対象のプライバシー関連リソースへのアプリケーションアクセスを保証するには十分でない可能性があります。プライバシー設定では、ユーザーはアプリケーションへのリソースアクセスを許可または拒否できます。
- プロンプト機能: Get-ProfilingResults は、プロンプト機能がアプリケーションパッケージに適用される可能性があると判断すると、この機能を "コメントアウト" 形式で出力します。パッケージマニフェストで宣言されている場合、アプリケーションはフォールバックプロンプトを選択します。アプリケーションがプロンプト対象リソースへのアクセスを拒否されるたびに、ユーザープロンプトが発行されます。これにより、ユーザーはリソースへのアクセスを明示的に許可または拒否できるようになります。フォールバックプロンプトは煩わしさにつながりサンドボックスを弱める可能性があるため、クリティカルなアプリケーションシナリオに必要な場合にのみ注意して使用する必要があります。
AccessAttemptRecords.csv

これは、解析されたトレースイベントとアプリケーションパッケージに記録された、失敗した各アクセス試行に関する詳細な診断情報を含む、コンマ区切り値ファイルです。
summary.txt

これは、Get-ProfilingResults のすべての実行の概要です。実行するたびにこのファイルに追加されます。 -SummaryOutputPath を使用してこのファイルパスを変更できます。

概要には、解析された入力、ターゲットアプリケーションパッケージと実行可能ファイル、識別された機能、編集されたマニフェストの内容のほか、アプリケーションパッケージがアクセスを試みても機能を識別できなかったすべてのリソースの概要リストが含まれます。

Note

パッケージ化されると、ターゲットアプリケーションがこれらのリソースにアクセスできなくなる可能性があります。

README.txt

このファイルには、Get-ProfilingResults のすべての実行に関する情報が含まれています。スクリプトが実行されるたびに、このファイルに追加されます。

README には、解析された入力、ターゲットアプリケーションパッケージ、出力されるファイルとそのパス、およびトラブルシューティングガイドに関する情報が記載されています。

スタックトレース

ACP アーカイブには、ACP-StackTrace.wpaProfile という名前のファイルが含まれています。これは Windows Performance Analyzer (WPA)のプロファイルです。 Stop-Profiling によってキャプチャされたイベントトレースログファイルに対し、スタックトレースの視覚化を有効にします。アクセス試行、そのターゲット、および試行を発行したスタックが分類されます。これにより、ターゲットアプリケーションが特定のリソースにアクセスできない理由をより完全に把握できるようになります。

trace.etl で Stop-Profiling によってキャプチャされたアクセス試行スタックを視覚化するには: