应用程序功能探查器 (ACP)

项目
10/07/2024

打包的应用程序可能需要访问沙盒之外的资源。这些资源包括用户文件、图片、注册表项、摄像头、位置和麦克风等。功能声明允许沙盒应用程序访问其中一些资源。声明在沙盒应用程序的程序包清单中进行。有关参考信息，请参阅 msix-packaging-tool。

应用程序功能探查器是一套工具，可帮助确定应用程序包可能需要声明哪些功能，以便获得所需资源的访问权限。此外，它还能提供有用的诊断信息，说明应用程序包尝试访问失败的情况。

重要

此功能为预览版：某些信息涉及预发布产品，在正式发布前可能会进行大幅修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

准备目标系统进行分析

设置目标系统以进行分析需要以下步骤：

确保用户帐户拥有目标 Windows 系统的管理员权限。
在目标系统上启用开发人员模式。此设置可在 Windows 的“设置 | 隐私和安全 | 面向开发人员”中找到。有关详细信息，请参阅启用用于开发的设备。
安装 PowerShell 7.3 或更高版本。有关安装说明，请参阅在 Windows 上安装 PowerShell。

这是 Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler 模块兼容性所必需的。
如果尚未安装 Windows 性能记录器 (WPR)，请安装并将其添加到 PATH。

有关说明，请参阅 Windows 性能记录器。
```
Get-Command wpr
```
下载应用程序功能探查器存档，并将其解压缩到方便的路径。

应用程序功能探查器存档可从本项目的发布资产中下载。
按照 msix-packaging-tool 上的说明打包应用程序，并将其安装到目标系统上。
获取目标应用程序包清单（推荐）和/或目标应用程序包全名。
1. （推荐）获取目标应用程序包清单。最简单的方法是使用 MSIX 打包工具打开清单，并将清单副本保存到方便的路径。
2. 在 PowerShell 中运行以下命令，获取应用程序包的全名：
```
Get-AppxPackage | where-object {$_.name -like '*Test-AppSilo*'}
```
（可选）安装 Windows 性能分析器。有关说明，请参阅 Windows 性能分析器。这并非分析所必需的，但可能有助于可视化 ACP 捕获和输出的某些数据。

导入 PowerShell 模块

有关该模块的信息，请点击此处：Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler。

以管理员权限在 PowerShell 中运行以下命令以导入模块：

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

注意

Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.dll 模块位于上述准备目标系统进行分析说明的步骤 5 中从存档中提取的 ACP 文件夹中。

开始分析

Start-Profiling cmdlet 可获取目标应用程序包清单的路径或应用程序包的全名。

Start-Profiling 将对目标应用程序包进行跟踪记录，并启用跟踪记录提供程序，以记录目标应用程序包的访问尝试。有关详细信息，请参阅 Start-Profiling。

以管理员权限在 PowerShell 中运行以下命令以开始分析：

Start-Profiling -ManifestPath TestApp-AppXManifest.xml

显示了执行 Start-Profiling cmdlet 的 PowerShell 命令窗口的屏幕截图

运行应用程序方案

在此步骤中，必须运行所有关键应用程序方案。分析结果与在此步骤中运行的方案一样全面。执行的应用程序方案越多，上述跟踪记录会话捕获的数据量就越大、越完整。

停止分析

Stop-Profiling cmdlet 可停止已启动的访问尝试跟踪日志记录会话，并移除跟踪日志记录中任何应用程序包的工具。

Stop-Profiling 可接受一个可选的跟踪路径参数，用于控制输出事件跟踪日志 (.etl) 文件的路径。默认为 <current_directory>\trace.etl。有关详细信息，请参阅 Stop-Profiling。

以管理员权限在 PowerShell 中运行以下命令以停止分析：

Stop-Profiling

显示了执行 Stop-Profiling cmdlet 的 PowerShell 命令窗口的屏幕截图

获取分析结果

Get-ProfilingResults cmdlet 会解析通过上述步骤获得的跟踪文件，并查找跟踪中确定的应用程序包所需的功能。除非指定了针对特定程序包的筛选器，否则它会输出跟踪中确定的每个应用程序包的功能和信息。

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 中的说明，使用新功能重新打包目标应用程序并重新安装。

帮助程序 cmdlet

Merge-ProfilingResults cmdlet 可用于合并 Get-ProfilingResults 多个运行的输出。

解释分析输出

Get-ProfilingResults 的输出包括以下内容：

清单格式的功能

如果用户使用 -ManifestPath 开关 and 提供了要编辑的清单，并且输入跟踪中确定了清单所属的程序包，则 Get-ProfilingResults 将直接编辑清单文件，以包含跟踪中为程序包确定的功能。否则，对于跟踪文件中确定的每个程序包，Get-ProfilingResults 将输出一个名为 <package full name><manifest name>.xml 的文件，其中包含 <Capabilities> 元素，该元素包含跟踪文件中为相应程序包确定的功能。

注意

Get-ProfilingResults 可以识别两种特殊的功能。这些结果会在输出清单中用 XML 注释标记出来。
- 隐私敏感功能：这些功能可保护摄像头、位置和麦克风等隐私敏感资源。如果应用程序包需要访问这些资源，则必须声明这些功能。但是，仅凭功能声明可能尚不足以确保应用程序访问目标隐私敏感资源。在隐私设置中，用户仍可授予或拒绝应用程序的资源访问权限。
- 提示功能：Get-ProfilingResults 在识别提示功能可能适用于某个应用程序包时，将以“注释掉”的形式来输出该功能。如果在程序包清单中声明，应用程序将选择加入回退提示。每次应用程序被拒绝访问符合提示条件的资源时，都会发出用户提示。这样，用户就有机会明确授予或拒绝对资源的访问权限。回退提示可能具有侵入性并会削弱沙盒，因此应谨慎使用，最好只在关键应用程序方案需要时才使用。
AccessAttemptRecords.csv

这是一个以逗号分隔的值文件，其中包含有关已解析跟踪事件的详细诊断信息，以及为应用程序包记录的每次失败访问尝试。
summary.txt

这是 Get-ProfilingResults 所有运行的摘要。每次运行都会对该文件进行追加。 -SummaryOutputPath 可用于修改此文件路径。

要包含已解析的输入、目标应用程序包和可执行文件、已识别的功能、已编辑的清单内容，以及应用程序包尝试访问但未识别功能的所有资源的摘要列表。

注意

目标应用程序在打包时可能无法访问这些资源。

README.txt

此文件包含 Get-ProfilingResults 的所有运行信息。脚本每次运行时，都会追加到此文件中。

README 提供了有关输入解析、目标应用程序包、输出文件及其路径的信息，以及故障排除指南。

堆栈跟踪

ACP 存档中包含一个名为 ACP-StackTrace.wpaProfile 的文件。这是 Windows 性能分析器 (WPA) 的配置文件。它可以使 Stop-Profiling 捕捉到的事件跟踪日志文件的堆栈跟踪可视化。它可以细分访问尝试、目标和发出尝试的堆栈。这样就能更全面地了解目标应用程序无法访问特定资源的原因。

要在 trace.etl 中可视化 Stop-Profiling 捕获的访问尝试堆栈，请执行以下操作：