Adjust ACP tutorial to point readers to release and individual cmdlet pages. (#7)
* adjust main tutorial based on new documentation.
* nit.
* Point readers to release assets.
* point readers to Win32 Iso version of MPT.
---------
Co-authored-by: Matheus Cruz Correia de Carvalho Souza <[email protected]>
This page will cover everything needed to package an existing MSIX or win32 application into
8
-
Isolated Win32 App. This will be done through the [MSIX Packaging Tool](https://learn.microsoft.com/en-us/windows/msix/packaging-tool/tool-overview)
8
+
Isolated Win32 App. This will be done through the MSIX Packaging Tool(MPT).**Note**thattheversionofMPTthatsupportsWin32AppIsolationisv1.2023.517.0,availableinthereleaseassetsofthisproject.The[storeversionofMPT](https://learn.microsoft.com/en-us/windows/msix/packaging-tool/tool-overview) is**outdated**forthepurposesoftheWin32AppIsolationfeature.
The Start-Profiling cmdlet is used to start access attempt profiling for an application package. The cmdlet both starts an access attempt trace logging session and instruments the application package so it’s able to log to the session.
26
+
The Start-Profiling cmdlet is used to start access attempt profiling for an application package. The cmdlet both starts an access attempt trace logging session and instruments the application package so it’s able to log to the session.**Note**thatStart-ProfilingrequiresadministratorprivilegesandthatDeveloperModebeenabled.
The Stop-Profiling cmdlet is used to stop access attempt profiling for a specified application package. The cmdlet stops an active trace logging session started via [Start-Profiling](Start-Profiling.md), collects the resulting Event Trace Log (ETL) file and takes away access attempt trace logging instrumentation from all currently instrumented packages.
27
+
The Stop-Profiling cmdlet is used to stop access attempt profiling for a specified application package. The cmdlet stops an active trace logging session started via [Start-Profiling](Start-Profiling.md), collects the resulting Event Trace Log (ETL) file and takes away access attempt trace logging instrumentation from all currently instrumented packages.**Note**thatStop-ProfilingrequiresadministratorprivilegesandthatDeveloperModebeenabled.
Packaged applications may need to access resources outside of the sandbox. Examples of such resources include user files, pictures, registry items, camera, location, and microphone, among others. [Capability declaration](https://learn.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations) allows sandboxed applications to access some of those resources. Declarations are made in the sandboxed application's package manifest. See [msix-packaging-tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) for reference.
5
+
Packaged applications may need to access resources outside of the sandbox. Examples of such resources include user files, pictures, registry items, camera, location, and microphone, among others. [Capability declaration](https://learn.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations) allows sandboxed applications to access some of those resources. Declarations are made in the sandboxed application's package manifest. See [msix-packaging-tool](../packaging/msix-packaging-tool.md) for reference.
6
6
7
7
Application Capability Profiler is a set of tools that help identify what capabilities may need to be declared by an application package, so it's granted the resource access it needs. Furthermore, it provides useful diagnostic information on failed access attempts by the application package.
#### 5. Download the Application Capability Profiler archive and extract it to a convenient path.
30
30
31
-
[Download ACP]().
31
+
The Application Capability Profiler archive can be downloaded from this project's release assets.
32
32
33
-
#### 6. Follow the instructions on [msix-packaging-tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) to package the application and install it on the target system.
33
+
#### 6. Follow the instructions on [msix-packaging-tool](../packaging/msix-packaging-tool.md) to package the application and install it on the target system.
34
34
35
35
#### 7. Obtain the target application package manifest (recommended) and/or the target application package full name.
36
36
37
-
1. **(Recommended)** Obtain the target application package manifest. The easiest way to do this is to open it using the [MSIX packaging tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) and save a copy of the manifest to a convenient path.
37
+
1. **(Recommended)** Obtain the target application package manifest. The easiest way to do this is to open it using the [MSIX packaging tool](../packaging/msix-packaging-tool.md) and save a copy of the manifest to a convenient path.
#### 8. **(Optional)** Install the Windows Performance Analyzer.
52
52
skipped 11 lines
64
64
65
65
The Start-Profiling cmdlet takes the path to the target application package manifest or the full name of the application package.
66
66
Start-Profiling will instrument the target application package for trace logging and enable a trace logging provider for access attempts made by the target application package.
67
-
Start-Profiling requires administrator privileges and that Developer Mode be enabled.
67
+
Start-Profiling requires administrator privileges and that Developer Mode be enabled.See[Start-Profiling](Start-Profiling.md)fordetails.
## Profiling step 3: run the application scenarios
76
76
skipped 3 lines
80
80
81
81
The Stop-Profiling cmdlet stops an access attempt trace logging session that has been started and takes away the instrumentation for any application packages that had been instrumented for trace logging.
82
82
Stop-Profiling takes an optional trace path parameter that controls the path used for the output Event Trace Log (.etl) file. <current_directory>\trace.etl by default.
83
-
Stop-Profiling requires administrator privileges and that Developer Mode be enabled.
83
+
Stop-Profiling requires administrator privileges and that Developer Mode be enabled.See[Stop-Profiling](Stop-Profiling.md)fordetails.
Get-ProfilingResults takes in the path to the trace file to parse. If none is provided, Get-ProfilingResults will attempt to Stop-Profiling to obtain a trace to parse.
96
96
Get-ProfilingResults optionally takes a path to a target application manifest. If information in the parsed trace can be attributed to the target application package manifest, the file is edited directly with the output capabilities. Otherwise, a copy of the manifest is made for each of the packages identified in the trace and their identified capabilities.
97
97
98
+
See [Get-ProfilingResults](Get-ProfilingResults.md) for details.
1. Include the newly identified capabilities in the target application package manifest (Get-ProfilingResults will edit the manifest directly if provided).
107
-
2. Follow instructions in [msix-packaging-tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) to repackage the target application with the new capabilities, and reinstall it.
109
+
2. Follow instructions in [msix-packaging-tool](../packaging/msix-packaging-tool.md) to repackage the target application with the new capabilities, and reinstall it.
108
110
109
111
## Helper cmdlets
110
112
111
-
The Merge-ProfilingResults cmdlet can be used to merge the output from multiple runs of Get-ProfilingResults.
113
+
The [Merge-ProfilingResults](Merge-ProfilingResults.md) cmdlet can be used to merge the output from multiple runs of Get-ProfilingResults.
112
114
113
115
## Interpreting Get-ProfilingResults output
114
116
skipped 29 lines
144
146
1. Open trace.etl in WPA.
145
147
2. Configure WPA Symbol paths to point to the application symbols and the Microsoft public symbol server.
[Installing PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3)
