Profileur de capacités d'application (ACP)

Article
10/07/2024

Les applications empaquetées peuvent avoir besoin d'accéder à des ressources en dehors du sandbox. Les exemples de telles ressources incluent les fichiers utilisateur, les images, les éléments du registre, la caméra, la localisation et le microphone, entre autres. La déclaration de capacité permet aux applications en sandbox d'accéder à certaines de ces ressources. Les déclarations sont faites dans le manifeste du package de l'application en sandbox. Veuillez consulter la section msix-packaging-tool pour référence.

Le profileur de capacités d'application est un ensemble d'outils qui aide à identifier les capacités qui doivent être déclarées par un package d'application, afin qu'il obtienne l'accès aux ressources dont il a besoin. En outre, il fournit des informations de diagnostic utiles sur les tentatives d’accès échouées par le package d’application.

Important

Cette fonctionnalité est en cours d'évaluation : Certaines informations concernent un produit en préversion qui peut être modifié de manière substantielle avant d'être commercialisé. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Préparer le système cible pour le profilage

Les étapes suivantes sont nécessaires pour configurer le système cible pour le profilage :

Assurez-vous que votre compte utilisateur dispose des privilèges administrateur sur le système Windows cible.
Activez le mode développeur sur le système cible. Ce paramètre se trouve dans les Paramètres Windows | Confidentialité & sécurité | Pour les développeurs. Veuillez consulter la section Activer votre appareil pour le développement pour plus d'informations.
Installez PowerShell 7.3 ou une version ultérieure. Veuillez consulter la section Installation de PowerShell sur Windows pour les instructions d'installation.

Ceci est nécessaire pour la compatibilité du module Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.
Installez Windows Performance Recorder (WPR) s'il n'est pas déjà installé et ajoutez-le à PATH.

Veuillez consulter la section Windows Performance Recorder pour les instructions.
```
Get-Command wpr
```
Téléchargez l'archive du profileur de capacités d'application et extrayez-la vers un chemin pratique.

L'archive du profileur de capacités d'application peut être téléchargée depuis les éléments de publication de ce projet.
Suivez les instructions sur la section msix-packaging-tool pour empaqueter l'application et l'installer sur le système cible.
Obtenez le manifeste du package de l'application cible (recommandé) et/ou le nom complet du package de l'application cible.
1. (Recommandé) Obtenez le manifeste du package de l'application cible. Le moyen le plus simple de le faire est de l'ouvrir à l'aide de l'outil de packaging MSIX et de sauvegarder une copie du manifeste dans un chemin pratique.
2. Obtenez le nom complet du package de l'application en exécutant la commande suivante dans PowerShell :
```
Get-AppxPackage | where-object {$_.name -like '*Test-AppSilo*'}
```
(Optionnel) Installez l'Analyseur de performance Windows. Veuillez consulter la section Windows Performance Analyzer pour les instructions. Ce n'est pas nécessaire pour le profilage, mais peut être utile pour visualiser certaines des données capturées et sorties par ACP.

Importer le module PowerShell

Les informations sur le module se trouvent ici : Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.

Exécutez la commande suivante dans PowerShell avec des privilèges administrateur pour importer le module :

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

Remarque

Le module Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.dll est situé dans le dossier ACP extrait de l'archive à l'étape 5 des instructions Préparer le système cible pour le profilage ci-dessus.

Démarrer le profilage

Le cmdlet Start-Profiling prend le chemin vers le manifeste du package de l'application cible ou le nom complet du package de l'application.

Start-Profiling instrumentera le package de l'application cible pour la journalisation des traces et activera un fournisseur de journalisation des traces pour les tentatives d'accès effectuées par le package de l'application cible. Veuillez consulter la section Start-Profiling pour plus d'informations.

Exécutez la commande suivante dans PowerShell avec des privilèges administrateur pour démarrer le profilage :

Start-Profiling -ManifestPath TestApp-AppXManifest.xml

Capture d'écran montrant une fenêtre de commande PowerShell exécutant le cmdlet Start-Profiling

Exécutez les scénarios d'application

À cette étape, il est important que tous les scénarios d'application critiques soient exécutés. Les résultats du profilage sont aussi complets que les scénarios exécutés à cette étape. Plus les scénarios d'application sont exercés, plus la quantité de données capturées par la session de journalisation des traces démarrée ci-dessus est grande et complète.

Arrêter le profilage

Le cmdlet Stop-Profiling arrête une session de journalisation des traces de tentatives d'accès qui a été démarrée et supprime l'instrumentation pour tous les packages d'application qui ont été instrumentés pour la journalisation des traces.

Stop-Profiling accepte un paramètre de chemin de trace optionnel qui contrôle le chemin utilisé pour le fichier Event Trace Log (.etl) de sortie. <current_directory>\trace.etl par défaut. Veuillez consulter la section Stop-Profiling pour plus d'informations.

Exécutez la commande suivante dans PowerShell avec des privilèges administrateur pour arrêter le profilage :

Stop-Profiling

Capture d'écran montrant une fenêtre de commande PowerShell exécutant le cmdlet Stop-Profiling

Obtenez les résultats du profilage

Le cmdlet Get-ProfilingResults analyse le fichier de trace obtenu à partir des étapes ci-dessus et trouve les capacités requises par le(s) package(s) d'application identifié(s) dans la trace. Il affiche les capacités et les informations pour chaque package d'application identifié dans la trace, sauf si des filtres vers un package spécifique ont été spécifiés.

Get-ProfilingResults accepte le chemin vers le fichier de trace à analyser. Si aucun chemin n'est fourni, Get-ProfilingResults tentera d'invoquer Stop-Profiling pour obtenir une trace à analyser.

Get-ProfilingResults accepte en option un chemin vers un manifeste d'application cible. Si les informations dans la trace analysée peuvent être attribuées au manifeste du package d'application cible, le fichier est édité directement avec les capacités de sortie. Sinon, une copie du manifeste est faite pour chacun des packages identifiés dans la trace, ajoutant les capacités identifiées.

Veuillez consulter la section Get-ProfilingResults pour plus de détails.

La commande suivante analysera le fichier de trace et affichera les résultats :

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

Capture d'écran montrant une fenêtre de commande PowerShell exécutant le cmdlet Get-ProfilingResults

Reconditionner l'application

Pour reconditionner l'application cible avec les nouvelles capacités identifiées :

Incluez les nouvelles capacités identifiées dans le manifeste du package de l'application cible (Get-ProfilingResults modifiera directement le manifeste s'il est fourni).
Suivez les instructions dans la section msix-packaging-tool pour reconditionner l'application cible avec les nouvelles capacités, et réinstallez-la.

Cmdlets d'aide

Le cmdlet Merge-ProfilingResults peut être utilisé pour fusionner les résultats de plusieurs exécutions de Get-ProfilingResults.

Interpréter la sortie du profilage

La sortie de Get-ProfilingResults se compose des éléments suivants :

Capacités formatées en manifeste

Si l'utilisateur fournit un manifeste à éditer avec le bouton -ManifestPath et que le package auquel appartient le manifeste est identifié dans la trace d'entrée, Get-ProfilingResults modifiera directement le fichier manifeste pour inclure les capacités identifiées dans la trace pour le package. Sinon, pour chaque package identifié dans le fichier de trace, Get-ProfilingResults produira un fichier nommé <package full name><manifest name>.xml contenant l'élément <Capabilities> avec les capacités identifiées dans la trace pour le package correspondant.

Remarque

Il existe deux types spéciaux de capacités que Get-ProfilingResults peut identifier. Ces résultats sont marqués avec des commentaires XML dans le manifeste de sortie.
- Capacités sensibles à la vie privée : Ces capacités protègent les ressources sensibles à la vie privée telles que la caméra, la localisation et le microphone. Ces capacités doivent être déclarées si le package d'application nécessite l'accès à ces ressources. Cependant, la déclaration de capacité seule peut ne pas suffire à garantir l'accès de l'application à la ressource sensible à la vie privée cible. Dans les paramètres de confidentialité, l'utilisateur peut toujours accorder ou refuser l'accès aux ressources à l'application.
- Capacité de demande : Get-ProfilingResults affichera cette capacité sous forme "commentée" lorsqu'il identifiera que la capacité de demande peut s'appliquer à un package d'application. Si elle est déclarée dans le manifeste du package, l'application est inscrite dans le mode de demande de secours. Des demandes utilisateur seront émises chaque fois que l'accès de l'application sera refusé à une ressource éligible à la demande. Cela donne à l'utilisateur une chance d'accorder ou de refuser explicitement l'accès à la ressource. La demande de secours peut être intrusive et affaiblir le sandbox, elle doit donc être utilisée avec précaution, de préférence uniquement lorsque nécessaire pour les scénarios d'application critiques.
AccessAttemptRecords.csv

Ceci est un fichier de valeurs séparées par des virgules contenant des informations de diagnostic détaillées sur les événements de trace analysés et chaque tentative d'accès échouée enregistrée pour le package d'application.
summary.txt

Ceci est un résumé de toutes les exécutions de Get-ProfilingResults. Chaque exécution s'ajoute à ce fichier. -SummaryOutputPath peut être utilisé pour modifier ce chemin de fichier.

Le résumé contient les entrées analysées, les packages et exécutables d'application cibles, les capacités identifiées, le contenu du manifeste édité et une liste résumée de toutes les ressources auxquelles le package d'application a tenté d'accéder mais pour lesquelles aucune capacité n'a été identifiée.

Remarque

Il est possible que le package d'application cible ne puisse pas accéder à ces ressources lorsqu'il est empaqueté.

README.txt

Ce fichier contient des informations pour toutes les exécutions de Get-ProfilingResults. Chaque fois que le script s'exécute, il s'ajoute à ce fichier.

Le README fournit des informations sur l'entrée analysée, le package d'application cible, les fichiers de sortie et leurs chemins, ainsi qu'un guide de dépannage.

Trace des appels

L'archive ACP contient un fichier nommé ACP-StackTrace.wpaProfile. Ceci est un profil pour Windows Performance Analyzer (WPA). Il permet la visualisation des traces d'appels pour le fichier de journalisation des événements capturé par Stop-Profiling. Il décompose les tentatives d'accès, leur cible, et la pile qui a déclenché la tentative. Cela permet une compréhension plus complète des raisons pour lesquelles l'application cible n'est pas en mesure d'accéder à des ressources spécifiques.

Pour visualiser les piles de tentatives d'accès capturées par Stop-Profiling dans trace.etl :

Ouvrez le fichier trace.etl dans WPA.
Configurez les chemins de symboles de WPA pour pointer vers les symboles de l'application et le serveur de symboles public de Microsoft :
Chargez les symboles.
Appliquez le profil dans ACP-StackTrace.wpaProfile pour voir la visualisation de la pile des tentatives d'accès :