Applicare il Package Support Framework in Visual Studio

Articolo
12/12/2023

Package Support Framework (PSF) è un progetto open source che consente di applicare correzioni all'applicazione desktop esistente. PSF consente l'esecuzione di un'applicazione in un formato in pacchetto senza modificare il codice. PSF consente di seguire le procedure consigliate degli ambienti di runtime moderni per le app.

Nelle sezioni seguenti verrà illustrato come creare un nuovo progetto di Visual Studio, includere Package Support Framework nella soluzione e creare correzioni di runtime.

Passaggio 1: Creare una soluzione di pacchetto in Visual Studio

In Visual Studio creare una nuova soluzione di Visual Studio vuota. Includere tutti i progetti dell'applicazione nella soluzione vuota appena creata.

Passaggio 2: Aggiungere un progetto di creazione pacchetti

Se non si ha già un progetto di creazione pacchetti di applicazioni Windows, crearne uno e aggiungerlo alla soluzione. Creare un nuovo progetto visual C# -> Windows universale -> Creazione pacchetti di applicazioni Windows e aggiungerlo alla soluzione appena creata.

Per altre informazioni sul progetto di creazione pacchetti di applicazioni Windows, vedere Creare un pacchetto dell'applicazione usando Visual Studio.

In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto di creazione del pacchetto, scegliere Modifica file di progetto e quindi aggiungerlo nella parte inferiore del file di progetto:

...
  <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>

Passaggio 3: Aggiungere un progetto per la correzione del runtime

Aggiungere un nuovo progetto Visual C++ -> Windows Desktop -> Dll (Dynamic-Link Library) alla soluzione.

Fare quindi clic con il pulsante destro del mouse sul progetto e scegliere Proprietà.

Nella pagina delle proprietà individuare il campo Proprietà di configurazione -> C/C++ - Linguaggio ->> Standard del linguaggio C++. Selezionare quindi ISO C++17 Standard (/std:c++17) dal menu a discesa.

Fare clic con il pulsante destro del mouse sul progetto e scegliere l'opzione Gestisci pacchetti NuGet dal menu di scelta rapida. Assicurarsi che l'opzione Origine pacchetto sia impostata su Tutti o nuget.org.

Fare clic sull'icona delle impostazioni accanto a tale campo.

Cercare i pacchetti NuGet per PSF, quindi installare Microsoft.PackageSupportFramework per questo progetto.

nuget package

Passaggio 4: Aggiungere un progetto che avvia l'eseguibile dell'utilità di avvio PSF

Aggiungere un nuovo progetto Visual C++ -> Generale -> Vuoto alla soluzione.

Effettua i passaggi seguenti:

Fare clic con il pulsante destro del mouse sul progetto e scegliere l'opzione Gestisci pacchetti NuGet dal menu di scelta rapida. Assicurarsi che l'opzione Origine pacchetto sia impostata su Tutti o nuget.org.
Fare clic sull'icona delle impostazioni accanto a tale campo.
Cercare i pacchetti NuGet per PSF, quindi installare Microsoft.PackageSupportFramework per questo progetto.

Aprire le pagine delle proprietà per il progetto e nella pagina Impostazioni generali impostare la proprietà Nome destinazione su PSFLauncher32 o PSFLauncher64 a seconda dell'architettura dell'applicazione.

Aggiungere un riferimento al progetto di correzione del runtime nella soluzione.

Fare clic con il pulsante destro del mouse sul riferimento e quindi nella finestra Proprietà applicare questi valori.

Proprietà	valore
Copiare localmente	True
Copia assembly satellite locale	True
Output assembly di riferimento	True
Collega dipendenze di libreria	False
Input delle dipendenze della libreria di collegamenti	False

Passaggio 5: Configurare il progetto di creazione del pacchetto

Per configurare il progetto di creazione pacchetti, seguire questa procedura:

Nel progetto di creazione del pacchetto fare clic con il pulsante destro del mouse sulla cartella Applicazioni e quindi scegliere Aggiungi riferimento dal menu a discesa.
Scegliere il progetto di utilità di avvio PSF e il progetto di applicazione desktop, quindi scegliere il pulsante OK .
Selezionare sia l'utilità di avvio PSF che il progetto Applicazione desktop, quindi fare clic sul pulsante OK. Se il codice sorgente dell'applicazione non è disponibile, selezionare solo il progetto launcher PSF.
Nel nodo Applicazioni fare clic con il pulsante destro del mouse sull'applicazione Launcher PSF e quindi scegliere Imposta come punto di ingresso.

Aggiungere un file denominato config.json al progetto di creazione del pacchetto, quindi copiare e incollare il testo JSON seguente nel file. Impostare la proprietà Azione pacchetto su Contenuto.

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

Specificare un valore per ogni chiave. Usare questa tabella come riferimento.

Matrice	key	valore
applications	ID	Usare il valore dell'attributo `Id` dell'elemento `Application` nel manifesto del pacchetto.
applications	eseguibile	Percorso relativo al pacchetto dell'eseguibile da avviare. Nella maggior parte dei casi, è possibile ottenere questo valore dal file manifesto del pacchetto prima di modificarlo. È il valore dell'attributo `Executable` dell'elemento `Application` .
applications	Workingdirectory	(Facoltativo) Percorso relativo al pacchetto da usare come directory di lavoro dell'applicazione che viene avviata. Se non si imposta questo valore, il sistema operativo usa la `System32` directory come directory di lavoro dell'applicazione.
di sistema	eseguibile	Nella maggior parte dei casi, questo sarà il nome dell'oggetto `executable` configurato in precedenza con il percorso e l'estensione di file rimossi.
correzioni	Libreria dll	Percorso relativo al pacchetto della DLL di correzione da caricare.
correzioni	config	(Facoltativo) Controlla il comportamento della DLL di correzione. Il formato esatto di questo valore varia in base alla correzione per correzione, perché ogni correzione può interpretare questo "BLOB" come vuole.

Al termine, il config.json file avrà un aspetto simile al seguente.

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

Nota

Le applicationschiavi , processese fixups sono matrici. Ciò significa che è possibile usare il file config.json per specificare più di un'applicazione, un processo e una DLL di correzione.

Eseguire il debug di una correzione di runtime

In Visual Studio premere F5 per avviare il debugger. La prima cosa che viene avviata è l'applicazione Launcher PSF, che a sua volta avvia l'applicazione desktop di destinazione. Per eseguire il debug dell'applicazione desktop di destinazione, è necessario collegarsi manualmente al processo dell'applicazione desktop scegliendo Debug-Collega> a processo e quindi selezionando il processo dell'applicazione. Per consentire il debug di un'applicazione .NET con una DLL di correzione del runtime nativo, selezionare tipi di codice gestiti e nativi (debug in modalità mista).

È possibile impostare punti di interruzione accanto a righe di codice nel codice dell'applicazione desktop e nel progetto di correzione del runtime. Se non si dispone del codice sorgente per l'applicazione, sarà possibile impostare punti di interruzione solo accanto a righe di codice nel progetto di correzione del runtime.