Criador de perfil de recursos do aplicativo (ACP)

Os aplicativos empacotados podem precisar acessar recursos fora da área restrita. Exemplos de tais recursos incluem arquivos de usuário, imagens, itens de registro, câmera, localização e microfone, entre outros. A declaração de funcionalidade permite que aplicativos em área restrita acessem alguns desses recursos. As declarações são feitas no manifesto do pacote do aplicativo em área restrita. Consulte msix-packaging-tool para referência.

O criador de perfil de recursos do aplicativo é um conjunto de ferramentas que ajudam a identificar quais recursos podem precisar ser declarados por um pacote de aplicativos, para que ele receba o acesso ao recurso necessário. Além disso, ele fornece informações úteis de diagnóstico sobre tentativas de acesso com falha pelo pacote de aplicativos.

Importante

Esse recurso está em versão preliminar: algumas informações estão relacionadas ao produto em pré-lançamento, o qual poderá ser modificado substancialmente antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Preparar o sistema de destino para a criação de perfil

As etapas a seguir são necessárias para configurar o sistema de destino para a criação de perfil:

1. Verifique se sua conta de usuário tem privilégio de administrador para o sistema Windows de destino.

2. Habilite o modo de desenvolvedor no sistema de destino. Essa configuração pode ser encontrada em Configurações do Windows | Privacidade & segurança | Para desenvolvedores. Consulte Habilitar seu dispositivo para desenvolvimento para obter mais informações.

3. Instale o PowerShell 7.3 ou posterior. Consulte Instalar o PowerShell no Windows para obter as instruções de instalação.

   Isso é necessário para a compatibilidade do módulo Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.

4. Instale o Windows Performance Recorder (WPR) se ainda não estiver instalado e adicione-o ao PATH.

   Consulte Windows Performance Recorder para obter as instruções.

   Get-Command wpr
   

   

5. Baixe o arquivo do criador de perfil de recursos do aplicativo e extraia-o para um caminho conveniente.

   O arquivo do criador de perfil de recursos do aplicativo pode ser baixado dos ativos da versão deste projeto.

6. Siga as instruções em msix-packaging-tool para empacotar o aplicativo e instalá-lo no sistema de destino.

7. Obtenha o manifesto do pacote de aplicativos de destino (recomendado) e/ou o nome completo do pacote de aplicativos de destino.

   1. (Recomendado) Obtenha o manifesto do pacote de aplicativos de destino. A maneira mais fácil de fazer isso é abri-lo usando a ferramenta de empacotamento MSIX e salvar uma cópia do manifesto em um caminho conveniente.

      

      

      

   2. Obtenha o nome completo do pacote de aplicativos executando o seguinte comando no PowerShell:

      Get-AppxPackage | where-object {$_.name -like '*Test-AppSilo*'}
      

      

8. (Opcional) Instale o Windows Performance Analyzer. Consulte Windows Performance Analyzer para obter as instruções. Isso não é necessário para a criação de perfil, mas pode ser útil na visualização de alguns dos dados capturados e gerados pelo ACP.

Importar o módulo do PowerShell

Informações sobre o módulo podem ser encontradas aqui: Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.

Execute o seguinte comando no PowerShell com privilégios de administrador para importar o módulo:

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

Observação

O módulo Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.dll está localizado na pasta ACP extraída do arquivo na etapa 5 das instruções Preparar o sistema de destino para a criação de perfil acima.

Iniciar criação de perfil

O cmdlet Start-Profiling usa o caminho para o manifesto do pacote de aplicativos de destino ou o nome completo do pacote de aplicativos.

Start-Profiling instrumentará o pacote de aplicativos de destino para o registro de rastreamento e habilitará um provedor de registros de rastreamento para tentativas de acesso feitas pelo pacote de aplicativos de destino. Consulte Start-Profiling para obter mais informações..

Execute o seguinte comando no PowerShell com privilégios de administrador para iniciar a criação de perfil:

Start-Profiling -ManifestPath TestApp-AppXManifest.xml

Executar os cenários do aplicativo

Nesta etapa, é importante que todos os cenários críticos do aplicativo sejam executados. Os resultados da criação de perfil são tão abrangentes quanto os cenários executados nesta etapa. Quanto mais cenários do aplicativo forem exercitados, maior e mais completa será a quantidade de dados capturados pela sessão de registro de rastreamento iniciada acima.

Interromper a criação de perfil

O cmdlet Stop-Profiling interrompe uma sessão de registro de rastreamento de tentativa de acesso que foi iniciada e remove a instrumentação de todos os pacotes de aplicativos que foram instrumentados para o registro de rastreamento.

Stop-Profiling aceita um parâmetro de caminho de rastreamento opcional que controla o caminho usado para o arquivo de saída do log de rastreamento de eventos (.etl). <current_directory>\trace.etl por padrão. Consulte Stop-Profiling para obter mais informações.

Execute o seguinte comando no PowerShell com privilégios de administrador para interromper a criação de perfil:

Stop-Profiling

Obter os resultados da criação de perfil

O cmdlet Get-ProfilingResults analisa o arquivo de rastreamento obtido nas etapas acima e localiza os recursos exigidos pelo(s) pacote(s) de aplicativos identificado(s) no rastreamento. Ele gera os recursos e as informações para cada pacote de aplicativos identificado no rastreamento, a menos que filtros para um pacote específico tenham sido especificados.

Get-ProfilingResults aceita o caminho para o arquivo de rastreamento a ser analisado. Se nenhum caminho for fornecido, Get-ProfilingResults tentará invocar Stop-Profiling para obter um rastreamento a ser analisado.

Get-ProfilingResults opcionalmente usa um caminho para um manifesto do aplicativo de destino. Se as informações no rastreamento analisado puderem ser atribuídas ao manifesto do pacote de aplicativos de destino, o arquivo será editado diretamente com os recursos de saída. Caso contrário, uma cópia do manifesto será feita para cada um dos pacotes identificados no rastreamento, adicionando os recursos identificados.

Consulte Get-ProfilingResults para obter detalhes

O comando a seguir analisará o arquivo de rastreamento e produzirá os resultados:

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

Reempacotando o aplicativo

Para reempacotar o aplicativo de destino com os recursos recém-identificados:

1. Incluir os recursos recém-identificados no manifesto do pacote de aplicativos de destino (Get-ProfilingResults editará o manifesto diretamente, se fornecido).
2. Siga as instruções em msix-packaging-tool para reempacotar o aplicativo de destino com os novos recursos e reinstalá-lo.

Cmdlets auxiliares

O cmdlet Merge-ProfilingResults pode ser usado para mesclar a saída de várias execuções de Get-ProfilingResults.

Interpretando a saída de criação de perfil

A saída de Get-ProfilingResults consiste no seguinte:

1. Recursos formatados em manifesto

   Se o usuário fornecer um manifesto a ser editado com a -ManifestPath opção e o pacote ao qual o manifesto pertence for identificado no rastreamento de entrada, Get-ProfilingResults editará o arquivo de manifesto diretamente para incluir os recursos identificados no rastreamento do pacote. Caso contrário, para cada pacote identificado no arquivo de rastreamento, Get-ProfilingResults produzirá um arquivo chamado <package full name><manifest name>.xml contendo o elemento <Capabilities> com os recursos identificados no rastreamento para o pacote correspondente.

   Observação

   Há dois tipos especiais de recursos que Get-ProfilingResults pode identificar. Esses resultados são sinalizados com comentários XML no manifesto de saída.

   • Capacidades sensíveis à privacidade: essas capacidades protegem recursos sensíveis à privacidade, como câmera, localização e microfone. Essas capacidades devem ser declaradas se o pacote de aplicativos exigir acesso a esses recursos. No entanto, a declaração de funcionalidade por si só pode não ser suficiente para garantir o acesso do aplicativo ao recurso sensível à privacidade de destino. Nas configurações de privacidade, o usuário ainda pode conceder ou negar acesso a recursos ao aplicativo.
   • Capacidade de prompt: Get-ProfilingResults produzirá essa capacidade no formulário "comentado" quando identificar que a capacidade de prompt pode se aplicar a um pacote de aplicativos. Se declarado no manifesto do pacote, o aplicativo será aceito na solicitação de fallback. Os prompts do usuário serão emitidos sempre que o aplicativo tiver seu acesso negado a um recurso qualificado para solicitações. Isso dá ao usuário a chance de conceder ou negar explicitamente o acesso ao recurso. A solicitação de fallback pode ser intrusiva e enfraquecer a área restrita, portanto, ela deve ser usada com cautela, de preferência somente quando necessário para cenários críticos de aplicativos.

2. AccessAttemptRecords.csv

   Este é um arquivo de valores separados por vírgula que contém informações detalhadas de diagnóstico sobre eventos de rastreamento analisados e cada tentativa de acesso com falha registrada para o pacote de aplicativos.

3. summary.txt

   Este é um resumo de todas as execuções de Get-ProfilingResults. Cada execução é anexada a esse arquivo. -SummaryOutputPath pode ser usado para modificar esse caminho de arquivo.

   O resumo contém as entradas analisadas, pacotes de aplicativos de destino e executáveis, recursos identificados, conteúdo de manifesto editado e uma lista resumida de todos os recursos que o pacote de aplicativos tentou acessar, mas para os quais nenhum recurso foi identificado.

Observação

É possível que o aplicativo de destino não consiga acessar esses recursos quando empacotado.

1. README.txt

   Esse arquivo contém informações para todas as execuções de Get-ProfilingResults. Cada vez que o script é executado, ele é anexado a esse arquivo.

   O README fornece informações sobre a entrada analisada, o pacote de aplicativos de destino, a saída de arquivos e seus caminhos, bem como um guia de solução de problemas.

Rastreamento de pilha

O arquivo ACP contém um arquivo chamado ACP-StackTrace.wpaProfile. Este é um perfil para o Windows Performance Analyzer (WPA). Ele habilita a visualização de rastreamento de pilha para o arquivo de registro de rastreamento de eventos capturado por Stop-Profiling. Ele divide as tentativas de acesso, seu destino e a pilha que emitiu a tentativa. Isso habilita uma compreensão mais completa dos motivos pelos quais o aplicativo de destino não consegue acessar recursos específicos.

Para visualizar pilhas de tentativas de acesso capturadas por Stop-Profiling em trace.etl:

1. Abra o arquivo trace.etl no WPA.

2. Configure os caminhos de símbolo do WPA para apontar para os símbolos do aplicativo e o servidor de símbolos públicos da Microsoft:

   

3. Carregue os símbolos.

4. Aplique o perfil em ACP-StackTrace.wpaProfile para exibir a visualização da pilha de tentativas de acesso:

   

   

Tópicos relacionados

Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler

Start-Profiling

Stop-Profiling

Get-ProfilingResults

Merge-ProfilingResults

msix-packaging-tool

Declaração de funcionalidade

Windows Performance Recorder

Windows Performance Analyzer

Instalar o PowerShell no Windows