Aplicar o Package Support Framework no Visual Studio

Artigo
12/12/2023

O Package Support Framework (PSF) é um projeto de código aberto que permite aplicar correções ao seu aplicativo de área de trabalho existente. O PSF permite que um aplicativo seja executado em um formato empacotado sem modificar o código. O Package Support Framework ajuda seu aplicativo a seguir as melhores práticas do ambiente moderno do runtime.

Nas seções a seguir, exploraremos como criar um novo projeto do Visual Studio, incluir o Package Support Framework para a solução e criar correções de tempo de execução.

Etapa 1: Criar uma solução de pacote no Visual Studio

No Visual Studio, crie um novo Visual Studio Solutions, Blank Solution. Inclua quaisquer projetos de aplicativo na Solução em Branco recém-criada.

Etapa 2: Adicionar um projeto de empacotamento

Se você ainda não tiver um Projeto de Empacotamento de Aplicativos do Windows, crie um e adicione-o à sua solução. Crie um novo Visual C# - Windows Universal - Windows Application Packaging Project e adicione-o à sua solução recém-criada>>.

Para obter mais informações sobre o projeto de empacotamento de aplicativos do Windows, consulte Empacotar seu aplicativo usando o Visual Studio.

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto de empacotamento, selecione Editar Arquivo de Projeto e adicione-o à parte inferior do arquivo de projeto:

...
  <Target Name="PSFRemoveSourceProject" AfterTargets="ExpandProjectReferences" BeforeTargets="_ConvertItems">
    <ItemGroup>
      <FilteredNonWapProjProjectOutput Include="@(_FilteredNonWapProjProjectOutput)">
      <SourceProject Condition="'%(_FilteredNonWapProjProjectOutput.SourceProject)'=='_Runtime fix project name_'" />
      </FilteredNonWapProjProjectOutput>
      <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
      <_FilteredNonWapProjProjectOutput Include="@(FilteredNonWapProjProjectOutput)" />
    </ItemGroup>
  </Target>
</Project>

Etapa 3: Adicionar projeto para a correção de tempo de execução

Adicione um novo projeto Visual C++ - Windows Desktop - Dynamic-Link>> Library (DLL) à solução.

Em seguida, clique com o botão direito do mouse no projeto e escolha Propriedades.

Na página de propriedades, localize o campo Propriedades de Configuração - C/C++ - Idioma ->>> Padrão de Linguagem C++. Em seguida, selecione ISO C++17 Standard (/std:c++17) no menu suspenso.

Clique com o botão direito do mouse no projeto e, no menu de contexto, escolha a opção Gerenciar Pacotes Nuget. Verifique se a opção Origem do pacote está definida como Todos ou nuget.org.

Clique no ícone de configurações ao lado desse campo.

Pesquise os pacotes Nuget para PSF e, em seguida, instale o Microsoft.PackageSupportFramework para este projeto.

nuget package

Etapa 4: Adicionar um projeto que inicia o executável do PSF Launcher

Adicione um novo Visual C++ - Geral ->> Projeto vazio para a solução.

Execute as seguintes etapas:

Clique com o botão direito do mouse nesse projeto e, no menu de contexto, escolha a opção Gerenciar Pacotes Nuget. Verifique se a opção Origem do pacote está definida como Todos ou nuget.org.
Clique no ícone de configurações ao lado desse campo.
Pesquise os pacotes Nuget para PSF e, em seguida, instale o Microsoft.PackageSupportFramework para este projeto.

Abra as páginas de propriedades do projeto e, na página Configurações gerais, defina a propriedade Nome de destino como PSFLauncher32 ou PSFLauncher64 dependendo da arquitetura do seu aplicativo.

Adicione uma referência de projeto ao projeto de correção de tempo de execução em sua solução.

Clique com o botão direito do mouse na referência e, na janela Propriedades , aplique esses valores.

Propriedade	Valor
Copiar local	Verdadeiro
Assemblies Satélite do Local da Cópia	Verdadeiro
Saída do Assembly de Referência	Verdadeiro
Dependências da Biblioteca de Links	Falso
Entradas de dependência da biblioteca de links	Falso

Etapa 5: Configurar o projeto de empacotamento

Para configurar o projeto de empacotamento, execute as seguintes etapas:

No projeto de empacotamento, clique com o botão direito do mouse na pasta Aplicativos e escolha Adicionar Referência no menu suspenso.
Escolha o projeto PSF Launcher e seu projeto de aplicativo de área de trabalho e, em seguida, escolha o botão OK .
Selecione o PSF Launcher e o projeto Desktop Application e clique no botão Ok. Se o código-fonte do aplicativo não estiver disponível, selecione apenas o projeto PSF Launcher.
No nó Aplicativos, clique com o botão direito do mouse no aplicativo Iniciador PSF e escolha Definir como Ponto de Entrada.

Adicione um arquivo nomeado config.json ao seu projeto de empacotamento e, em seguida, copie e cole o seguinte texto json no arquivo. Defina a propriedade Ação do pacote como Conteúdo.

{
    "applications": [
        {
            "id": "",
            "executable": "",
            "workingDirectory": ""
        }
    ],
    "processes": [
        {
            "executable": "",
            "fixups": [
                {
                    "dll": "",
                    "config": {
                    }
                }
            ]
        }
    ]
}

Forneça um valor para cada chave. Use essa tabela como um guia.

Array	chave	Valor
de dimensionamento da Web	ID	Use o `Id` valor do atributo do elemento no manifesto do `Application` pacote.
de dimensionamento da Web	executável	O caminho relativo ao pacote para o executável que você deseja iniciar. Na maioria dos casos, você pode obter esse valor do arquivo de manifesto do pacote antes de modificá-lo. É o `Executable` valor do atributo do `Application` elemento.
de dimensionamento da Web	workingDirectory	(Opcional) Um caminho relativo ao pacote a ser usado como o diretório de trabalho do aplicativo que é iniciado. Se você não definir esse valor, o sistema operacional usará o `System32` diretório como o diretório de trabalho do aplicativo.
sistema	executável	Na maioria dos casos, este será o nome do configurado acima com o caminho e a extensão de `executable` arquivo removidos.
Correções	dll	Caminho relativo ao pacote para a DLL de correção a ser carregada.
Correções	config	(Opcional) Controla como a DLL de correção se comporta. O formato exato desse valor varia em uma base de correção por fixup, pois cada correção pode interpretar esse "blob" como quiser.

Quando terminar, seu config.json arquivo terá a seguinte aparência.

{
  "applications": [
    {
      "id": "DesktopApplication",
      "executable": "DesktopApplication/WinFormsDesktopApplication.exe",
      "workingDirectory": "WinFormsDesktopApplication"
    }
  ],
  "processes": [
    {
      "executable": ".*App.*",
      "fixups": [ { "dll": "RuntimeFix.dll" } ]
    }
  ]
}

Observação

As applicationschaves , processese fixups são matrizes. Isso significa que você pode usar o arquivo config.json para especificar mais de um aplicativo, processo e DLL de correção.

Depurar uma correção de tempo de execução

No Visual Studio, pressione F5 para iniciar o depurador. A primeira coisa que inicia é o aplicativo PSF Launcher, que, por sua vez, inicia seu aplicativo de desktop de destino. Para depurar o aplicativo da área de trabalho de destino, você terá que anexar manualmente ao processo do aplicativo da área de trabalho escolhendo Depurar-Anexar> ao Processo e, em seguida, selecionando o processo do aplicativo. Para permitir a depuração de um aplicativo .NET com uma DLL de correção de tempo de execução nativa, selecione os tipos de código gerenciado e nativo (depuração de modo misto).

Você pode definir pontos de interrupção ao lado de linhas de código no código do aplicativo da área de trabalho e no projeto de correção de tempo de execução. Se você não tiver o código-fonte para seu aplicativo, poderá definir pontos de interrupção apenas ao lado de linhas de código em seu projeto de correção de tempo de execução.