> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Otimização guiada por perfil no Visual Studio
> Otimização guiada por perfil no Visual Studio
Este tópico descreve como usar [otimizações guiadas por perfil](https://learn.microsoft.com/cpp/build/profile-guided-optimizations) (PGO) para jogos implantados e em execução em um XBOX Series X Dev Kit ou XBOX One Dev Kit. A PGO é uma tecnologia de otimização do compilador em tempo de execução que usa dados de criação de perfil coletados durante a execução de cenários de usuário importantes ou centrados em desempenho para criar uma versão otimizada do título.
As otimizações guiadas por perfil têm vantagens significativas em relação às otimizações estáticas tradicionais, porque se baseiam em como o título provavelmente será usado em um ambiente de varejo. A PGO favorece a velocidade em caminhos de código correspondentes a cenários de usuário comuns e favorece o tamanho em cenários de usuário incomuns. O resultado é um código mais rápido para cenários comuns e um código menor para cenários usados com menos frequência.
Os ganhos de desempenho da PGO variam de acordo com o título, mas você pode esperar ganhos de 5 a 30%. Esteja ciente de que a PGO não trata do desempenho de nenhuma parte da aplicação centrada na GPU.
## Criar um build instrumentado
O treinamento com a PGO depende de um build do seu título que contenha a instrumentação de PGO. A PGO usa essa instrumentação para determinar quais caminhos de código são executados com mais frequência. Para criar um build instrumentado, basta definir duas propriedades de build no Visual Studio.
#### Para criar um build instrumentado
1. No **Solution Explorer**, clique com o botão direito do mouse no projeto e selecione **Properties**.
2. Na caixa de diálogo **Property Pages**, expanda os nós **Configuration Properties** e **C/C++**.
3. Selecione a página de propriedades **Optimization** e defina **Whole Program Optimization** como **Yes** (figura 1). **Figura 1. Definindo a propriedade Whole Program Optimization.** 
4. Expanda o nó **Linker**.
5. Selecione a página de propriedades **Optimization** e defina **Link Time Code Generation** como **Profile Guided Optimization - Instrument** (figura 2). **Figura 2. Definindo a propriedade Link Time Code Generation para um build instrumentado.** 
\[!NOTE] As duas propriedades descritas neste procedimento correspondem à opção de compilador `/GL` e à opção de vinculador `/LTCG:PGInstrument` no MSBuild.
6. Compile e implante o build instrumentado no seu console XBOX One. Com o título em execução, você pode ver que os arquivos de PGO são implantados como parte do título, de forma semelhante à figura 3. **Figura 3. Os arquivos de PGO implantados por um build instrumentado.** 
## Implantar os arquivos necessários
O Microsoft Game Development Kit (GDK) inclui três arquivos que devem ser implantados com o seu título para usar a PGO. Um arquivo, chamado *psapi.dll*, é instalado em *C:\Program Files (x86)\Microsoft GDK\edition\GXDK\bin*. Os outros dois, chamados *pgort140.dll* e *pgosweep.exe*, vêm da sua instalação do Visual Studio.
Se você estiver usando o MSBuild para compilar o título, esses arquivos serão copiados automaticamente para o diretório *Layout* quando você criar um build instrumentado.
Se você estiver usando `makefiles` para compilar o título, precisará adicionar manualmente esses três arquivos ao diretório *Layout* para que sejam implantados com o título. No Visual Studio, adicionar esses arquivos ao projeto e excluí-los do build é uma forma conveniente de copiá-los para o diretório *Layout* e implantá-los com o título.
#### Para adicionar os arquivos necessários ao seu projeto do Visual Studio
1. No **Solution Explorer**, clique com o botão direito do mouse no projeto, selecione **Add** e, em seguida, selecione **Existing Item** (figura 4). **Figura 4. Adicionando os arquivos de PGO a um projeto.** 
2. Vá para *C:\Program Files (x86)\Microsoft GDK\edition\GXDK\bin*, selecione o arquivo de PGO (*psapi.dll*) e selecione **Add** para adicionar o arquivo ao projeto.
3. Vá para *C:\Program Files (x86)\Microsoft Visual Studio\2019\edition\VC\Tools\MSVC\version\bin\Hostx64\x64\onecore* ou *C:\Program Files\Microsoft Visual Studio\2022\edition\VC\Tools\MSVC\version\bin\Hostx64\x64\onecore* do seu conjunto de ferramentas e selecione os arquivos de PGO (*pgort140.dll* e *pgosweep.exe*). Em seguida, selecione **Add** para adicionar os arquivos ao projeto.
4. No **Solution Explorer**, clique com o botão direito do mouse em *pgort140.dll* e selecione **Properties**.
5. Na caixa de diálogo **Property Pages**, expanda o nó **Configuration Properties** e selecione a página de propriedades **General**.
6. Defina **Excluded From Build** como **Yes** e **Item Type** como **Does not participate in build** (figura 5). **Figura 5. Excluindo um arquivo de PGO dos builds.** 
Os arquivos de PGO agora serão copiados para o diretório *Layout* e implantados com o título.
## Treinar com o build instrumentado
O treinamento é a fase mais importante da PGO. Os ganhos de desempenho obtidos com a PGO são uma função direta de quão bem o aplicativo é treinado. Na fase de treinamento da PGO, exercite cenários comuns centrados em desempenho com o título em execução.
Depois de exercitar os cenários de desempenho comuns, inicie a coleta de um arquivo de artefato da PGO (.pgc), que captura seus dados de treinamento. Use o *pgosweep.exe* para gerar o arquivo .pgc (figura 6).
**Figura 6. Executando o pgosweep.exe.**
Neste exemplo, criamos um arquivo .pgc chamado *Direct3DGame1!1.pgc*. Ao criar um arquivo .pgc, normalmente usamos a convenção *titlename!#.pgc*, em que *titlename* é o nome do título em execução e *#* é 1 mais o número de arquivos *titlename!#.pgc* criados anteriormente.
Cada execução do *pgosweep.exe* cria um arquivo .pgc separado. O ideal é criar vários arquivos .pgc que representem diversos cenários centrados em desempenho. Quando terminar de criar os arquivos .pgc, você poderá vê-los no diretório *D:\\* do seu **console** (ou seja, SystemScratch), de forma semelhante à figura 7.
**Figura 7. Arquivos .pgc nomeados sequencialmente.**
Em seguida, você precisa mesclar os arquivos .pgc em outro artefato da PGO, conhecido como arquivo .pgd. O arquivo .pgd é usado pelo compilador durante a última fase da PGO, a otimização.
Antes de iniciar a otimização, copie os arquivos .pgc do console de volta para o PC usando o [xbcp.exe](/pt-BR/tools/tools-console/commandlinetools/xbcp). Os arquivos .pgc devem ser copiados para o diretório de saída do build. (Na figura 8, o diretório de saída do build é *C:\temp\Direct3DGame1\Gaming.Xbox.XboxOne.x64\Release*.)
**Figura 8. Copiando arquivos .pgc para o diretório de saída do build.**
## Criar o build otimizado
Para criar o build otimizado, defina a propriedade **Link Time Code Generation** como **Profile Guided Optimization - Update** (figura 9).
**Figura 9. Definindo a propriedade Link Time Code Generation para um build otimizado.**
Essa propriedade corresponde à opção de vinculador `/LTCG:PGOptimize` no MSBuild.
Depois de recompilar o título, a saída do build incluirá mensagens relacionadas à PGO, semelhantes às da figura 10.
**Figura 10. Mensagens relacionadas à PGO na saída do build.**
## Recomendações de PGO para XBOX
As instruções anteriores fornecem uma visão geral do uso da PGO no Microsoft Game Development Kit (GDK) no XBOX usando as propriedades de projeto internas do Visual Studio. No entanto, o compilador Visual C++ preteriu o uso da PGO por meio das opções `/LTCG:PGInstrument`, `/LTCG:PGOptimize` e `/LTCG:PGUpdate`, que as propriedades de projeto do Visual Studio controlam no Visual Studio 2019 e no Visual Studio 2022.
As substituições preferenciais são as seguintes.
* Para o compilador C/C++, use `/GL` (propriedade **Whole Program Optimization** definida como **Yes (/GL)**, conforme mostrado anteriormente na figura 1).
* Para o vinculador, use `/LTCG` (propriedade **Link Time Code Generation** definida como **Use Link Time Code Generation (/LTCG)**, conforme mostrado na figura 11). **Figura 11. Definindo a propriedade Link Time Code Generation.** 
Em seguida, use uma das novas opções de vinculador a seguir, adicionando-a à caixa **Additional Options** da página de propriedades **Command Line**:
* `/FASTGENPROFILE` ou `/GENPROFILE` para gerar um perfil de PGO (figura 12). Para obter detalhes sobre essas opções, veja [ /GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)](https://learn.microsoft.com/cpp/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build) no Microsoft Docs. **Figura 12. Definindo a opção de vinculador para gerar um perfil de PGO.** 
* `/USEPROFILE` para otimizar para um conjunto de perfis de PGO (figura 13). Para obter detalhes sobre essa opção, veja [/USEPROFILE (Run PGO in thread safe mode)](https://learn.microsoft.com/cpp/build/reference/useprofile) no Microsoft Docs. **Figura 13. Definindo a opção de vinculador para otimizar para um conjunto de perfis de PGO.** 
## Solução de problemas da PGO
### Desempenho em tempo de execução
Ao criar o perfil de um build instrumentado, as ferramentas podem causar problemas de desempenho. Esses problemas podem dificultar o controle do título. A opção `/FASTGENPROFILE` é uma boa escolha para tornar um build instrumentado mais rápido para a criação de perfil de sessões de jogo interativas.
### Dependências
Se você habilitar a instrumentação de PGO e descobrir que o título não carrega mais, verifique se *pgort140.dll* e *vcruntime140.dll* estão na mesma pasta que o arquivo .exe do título.
Se a tentativa de executar o *pgosweep.exe* falhar (normalmente com um erro STATUS\_DLL\_NOT\_FOUND), verifique se *pgort140.dll*, *psapi.dll* e *vcruntime140.dll* estão presentes na mesma pasta que o arquivo .exe do título.
Verifique também se você está usando a versão x64 *onecore* de *pgort140.dll* e *pgosweep.exe*.
### Uso de memória
A PGO usa memória para capturar o perfil, o que pode ser um desafio para um título que usa uma parte significativa da memória disponível. Para executar a PGO com êxito, talvez seja necessário usar a configuração ExtraTitleMemory no [xbconfig.exe](/pt-BR/tools/tools-console/commandlinetools/xbconfig), a função [XMemTransferMemory](/pt-BR/reference/system/xmem/functions/xmemtransfermemory) ou ambas.
Usar `/FASTGENPROFILE` em vez de `/LTCG:PGInstrument` ou `/GENPROFILE` produz um consumo de memória menor com um resultado semelhante.
\[!NOTE] A versão da PGO fornecida no GDK de junho de 2020 (e em seus QFEs) usa a memória do título. A PGO será atualizada para usar corretamente a memória das ferramentas em uma versão futura.
## Veja também
[Otimização guiada por perfil](/pt-BR/tools/tools-console/pgo/pgo) [Desenvolvimento de jogos para console XBOX (ambiente e ferramentas)](/pt-BR/tools/tools-console/gc-tools-console-toc)
## Related topics
- [Otimização guiada por perfil](/pt-BR/tools/tools-console/pgo/pgo.md)
- [Otimização guiada por perfil (PGO) para títulos XBOX](/pt-BR/tools/tools-console/pgo/index.md)
- [Recomendações de opções do compilador e do vinculador do Visual C++](/pt-BR/tools/tools-console/visualstudio/compiler-switch-recommendations.md)
- [Ferramentas e APIs do ambiente XBOX](/pt-BR/tools/tools-console/gc-xbox-tools-and-apis-toc.md)
- [Ambiente e ferramentas de desenvolvimento de jogos para console XBOX](/pt-BR/tools/tools-console/gc-tools-console-toc.md)