Prise en main de l’infrastructure de support des packagesGet Started with Package Support Framework

L' infrastructure de prise en charge des packages est un kit Open source qui vous permet d’appliquer des correctifs à votre application de bureau existante (sans modifier le code) pour qu’elle puisse s’exécuter dans un conteneur MSIX.The Package Support Framework is an open source kit that helps you apply fixes to your existing desktop application (without modifying the code) so that it can run in an MSIX container. Le Framework de prise en charge de package aide votre application à respecter les bonnes pratiques de l’environnement d’exécution moderne.The Package Support Framework helps your application follow the best practices of the modern runtime environment.

Cet article fournit une présentation détaillée de chaque composant de l’infrastructure de prise en charge des packages, ainsi que du Guide pas à pas de son utilisation.This article provides an indepth look at each component of Package Support Framework and step by step guide to using it.

Comprendre ce qui se trouve dans un Framework de prise en charge de packageUnderstand what is inside a Package Support Framework

Le Framework de prise en charge de package contient un exécutable, une DLL de gestionnaire de runtime et un ensemble de correctifs de runtime.The Package Support Framework contains an executable, a runtime manager DLL, and a set of runtime fixes.

Framework de prise en charge de package

Voici le processus :Here is the process:

  1. Créez un fichier de configuration qui spécifie les correctifs que vous souhaitez appliquer à votre application.Create a configuration file that specifies the fixes that you want to apply to your application.
  2. Modifiez votre package pour qu’il pointe vers le fichier exécutable du lanceur de l’infrastructure de support des packages.Modify your package to point to the Package Support Framework (PSF) launcher executable file.

Lorsque les utilisateurs démarrent votre application, le lanceur de l’infrastructure de prise en charge des packages est le premier exécutable qui exécute.When users starts your application, the Package Support Framework launcher is the first executable that runs. Il lit votre fichier de configuration et injecte les correctifs de runtime et la DLL de gestionnaire de runtime dans le processus d’application.It reads your configuration file and injects the runtime fixes and the runtime manager DLL into the application process. Le gestionnaire de runtime applique le correctif quand l’application en a besoin pour s’exécuter à l’intérieur d’un conteneur MSIX.The runtime manager applies the fix when it's needed by the application to run inside of an MSIX container.

Injection de DLL par le Framework de prise en charge de package

Étape 1 : identifier les problèmes de compatibilité des applications empaquetéesStep 1: Identify packaged application compatibility issues

Tout d’abord, créez un package pour votre application.First, create a package for your application. Ensuite, installez-le, exécutez-le et observez son comportement.Then, install it, run it, and observe its behavior. Vous recevrez peut-être des messages d’erreur qui vous aideront à identifier un problème de compatibilité.You might receive error messages that can help you identify a compatibility issue. Vous pouvez également utiliser Process Monitor pour identifier les problèmes.You can also use Process Monitor to identify issues. Les problèmes courants sont liés aux hypothèses de l’application concernant les autorisations du répertoire de travail et du chemin d’accès au programme.Common issues relate to application assumptions regarding the working directory and program path permissions.

Utilisation de process Monitor pour identifier un problèmeUsing Process Monitor to identify an issue

Process Monitor est un utilitaire puissant pour observer les opérations de fichier et de registre d’une application, ainsi que leurs résultats.Process Monitor is a powerful utility for observing an app's file and registry operations, and their results. Cela peut vous aider à comprendre les problèmes de compatibilité des applications.This can help you to understand application compatibility issues. Après l’ouverture du moniteur de processus, ajoutez un filtre (filtre > filtre...) pour inclure uniquement les événements de l’exécutable de l’application.After opening Process Monitor, add a filter (Filter > Filter…) to include only events from the application executable.

Filtre d’application ProcMon

Une liste d’événements s’affiche.A list of events will appear. Pour la plupart de ces événements, le mot « Success » s’affiche dans la colonne de résultats .For many of these events, the word SUCCESS will appear in the Result column.

Événements ProcMon

Si vous le souhaitez, vous pouvez filtrer les événements pour n’afficher que les échecs.Optionally, you can filter events to only show only failures.

ProcMon exclure le succès

Si vous soupçonnez un échec d’accès au système de fichiers, recherchez les événements ayant échoué qui se trouvent sous le chemin d’accès system32/SysWOW64 ou le fichier de package.If you suspect a filesystem access failure, search for failed events that are under either the System32/SysWOW64 or the package file path. Les filtres peuvent également être utiles ici.Filters can also help here, too. Démarrez en bas de cette liste et faites défiler vers le haut.Start at the bottom of this list and scroll upwards. Les erreurs qui s’affichent en bas de cette liste ont été les plus récentes.Failures that appear at the bottom of this list have occurred most recently. Payez la plus grande attention aux erreurs qui contiennent des chaînes telles que « accès refusé » et « chemin/nom introuvable », et ignorez les choses qui ne semblent pas suspectes.Pay most attention to errors that contain strings such as "access denied," and "path/name not found", and ignore things that don't look suspicious. PSFSample présente deux problèmes.The PSFSample has two issues. Vous pouvez voir ces problèmes dans la liste qui s’affiche dans l’image suivante.You can see those issues in the list that appears in the following image.

ProcMon Config.txt

Dans le premier problème qui s’affiche dans cette image, l’application ne parvient pas à lire à partir du fichier « Config.txt » qui se trouve dans le chemin d’accès « C:\Windows\SysWOW64 ».In the first issue that appears in this image, the application is failing to read from the "Config.txt" file that is located in the "C:\Windows\SysWOW64" path. Il est peu probable que l’application essaie de faire référence à ce chemin d’accès directement.It's unlikely that the application is trying to reference that path directly. Il est très probable qu’il essaie de lire à partir de ce fichier à l’aide d’un chemin d’accès relatif et, par défaut, « system32/SysWOW64 » est le répertoire de travail de l’application.Most likely, it's trying to read from that file by using a relative path, and by default, "System32/SysWOW64" is the application's working directory. Cela suggère que l’application attend que son répertoire de travail actuel soit défini sur un emplacement du package.This suggests that the application is expecting its current working directory to be set to somewhere in the package. À l’intérieur de l’AppX, nous pouvons voir que le fichier existe dans le même répertoire que l’exécutable.Looking inside of the appx, we can see that the file exists in the same directory as the executable.

Config.txt d’application

Le deuxième problème apparaît dans l’image suivante.The second issue appears in the following image.

Fichier journal ProcMon

Dans ce problème, l’application ne parvient pas à écrire un fichier. log dans son chemin d’accès au package.In this issue, the application is failing to write a .log file to its package path. Cela peut suggérer l’aide d’une correction de la redirection de fichiers.This would suggest that a file redirection fixup might help.

Étape 2 : Rechercher un correctif du RuntimeStep 2: Find a runtime fix

Les fibres discontinues de polyester contiennent des correctifs de Runtime que vous pouvez utiliser pour le moment, par exemple la correction de la redirection de fichiers.The PSF contains runtime fixes that you can use right now, such as the file redirection fixup.

Correction de la redirection de fichiersFile Redirection Fixup

Vous pouvez utiliser la Correction de redirection de fichiers pour rediriger les tentatives d’écriture ou de lecture de données dans un répertoire qui n’est pas accessible à partir d’une application qui s’exécute dans un conteneur MSIX.You can use the File Redirection Fixup to redirect attempts to write or read data in a directory that isn't accessible from an application that runs in an MSIX container.

Par exemple, si votre application écrit dans un fichier journal qui se trouve dans le même répertoire que l’exécutable de votre application, vous pouvez utiliser la Correction de redirection de fichiers pour créer ce fichier journal dans un autre emplacement, tel que le magasin de données d’applications local.For example, if your application writes to a log file that is in the same directory as your applications executable, then you can use the File Redirection Fixup to create that log file in another location, such as the local app data store.

Correctifs du runtime de la communautéRuntime fixes from the community

Veillez à consulter les contributions de la communauté sur notre page GitHub .Make sure to review the community contributions to our GitHub page. Il est possible que d’autres développeurs résolvent un problème semblable au vôtre et aient partagé un correctif du Runtime.It's possible that other developers have resolved an issue similar to yours and have shared a runtime fix.

Étape 3 : appliquer un correctif du RuntimeStep 3: Apply a runtime fix

Vous pouvez appliquer un correctif de Runtime existant avec quelques outils simples à partir de la SDK Windows et en procédant comme suit.You can apply an existing runtime fix with a few simple tools from the Windows SDK, and by following these steps.

  • Créer un dossier de disposition de packageCreate a package layout folder
  • Récupérer les fichiers de l’infrastructure de prise en charge du packageGet the Package Support Framework files
  • Ajoutez-les à votre packageAdd them to your package
  • Modifier le manifeste du packageModify the package manifest
  • Créer un fichier de configurationCreate a configuration file

Passons en revue chaque tâche.Let's go through each task.

Créer le dossier de disposition de packageCreate the package layout folder

Si vous disposez déjà d’un fichier. msix (ou. AppX), vous pouvez décompresser son contenu dans un dossier de disposition qui servira de zone de transit pour votre package.If you have a .msix (or .appx) file already, you can unpack its contents into a layout folder that will serve as the staging area for your package. Vous pouvez effectuer cette opération à partir d’une invite de commandes à l’aide de l’outil MakeAppx, en fonction du chemin d’installation du kit de développement logiciel (SDK), où se trouve l’outil makeappx.exe sur votre PC Windows 10 : x86 : C:\Program Files (x86) \Windows Kits\10\bin\x86\makeappx.exe x64 : C:\Program Files (x86) \Windows Kits\10\bin\x64\makeappx.exeYou can do this from a command prompt using MakeAppx tool, based on your installation path of the SDK, this is where you will find the makeappx.exe tool on your Windows 10 PC: x86: C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe x64: C:\Program Files (x86)\Windows Kits\10\bin\x64\makeappx.exe

makeappx unpack /p PSFSamplePackage_1.0.60.0_AnyCPU_Debug.msix /d PackageContents

Vous obtiendrez un résultat ressemblant à ce qui suit.This will give you something that looks like the following.

Disposition du package

Si vous n’avez pas de fichier. msix (ou. AppX) à partir duquel commencer, vous pouvez créer le dossier et les fichiers du package à partir de zéro.If you don't have a .msix (or .appx) file to start with, you can create the package folder and files from scratch.

Récupérer les fichiers de l’infrastructure de prise en charge du packageGet the Package Support Framework files

Vous pouvez récupérer le package NuGet NuGet à l’aide de l’outil en ligne de commande NuGet autonome ou de Visual Studio.You can get the PSF Nuget package by using the standalone Nuget command line tool or via Visual Studio.

Récupération du package à l’aide de l’outil en ligne de commandeGet the package by using the command line tool

Installez l’outil en ligne de commande NuGet à partir de cet emplacement : https://www.nuget.org/downloads .Install the Nuget command line tool from this location: https://www.nuget.org/downloads. Ensuite, à partir de la ligne de commande NuGet, exécutez la commande suivante :Then, from the Nuget command line, run this command:

nuget install Microsoft.PackageSupportFramework

Vous pouvez également renommer l’extension de package en. zip et la décompresser.Alternatively, you can rename the package extension to .zip and unzip it. Tous les fichiers dont vous avez besoin se trouvent sous le dossier/bin.All the files you need will be under the /bin folder.

Récupération du package à l’aide de Visual StudioGet the package by using Visual Studio

Dans Visual Studio, cliquez avec le bouton droit sur le nœud de votre solution ou de votre projet, puis sélectionnez l’une des commandes gérer les packages NuGet.In Visual Studio, right-click your solution or project node and pick one of the Manage Nuget Packages commands. Recherchez Microsoft. PackageSupportFramework ou des fibres discontinues pour trouver le package sur NuGet.org. Ensuite, installez-le.Search for Microsoft.PackageSupportFramework or PSF to find the package on Nuget.org. Then, install it.

Ajouter les fichiers de l’infrastructure de prise en charge du package à votre packageAdd the Package Support Framework files to your package

Ajoutez les dll et les fichiers exécutables des fibres discontinues de 32 bits et 64 nécessaires au répertoire du package.Add the required 32-bit and 64-bit PSF DLLs and executable files to the package directory. Inspirez-vous du tableau suivant.Use the following table as a guide. Vous devez également inclure les correctifs de Runtime dont vous avez besoin.You'll also want to include any runtime fixes that you need. Dans notre exemple, nous avons besoin du correctif du runtime de redirection de fichiers.In our example, we need the file redirection runtime fix.

L’exécutable de l’application est x64Application executable is x64 L’exécutable de l’application est x86Application executable is x86
PSFLauncher64.exePSFLauncher64.exe PSFLauncher32.exePSFLauncher32.exe
PSFRuntime64.dllPSFRuntime64.dll PSFRuntime32.dllPSFRuntime32.dll
PSFRunDll64.exePSFRunDll64.exe PSFRunDll32.exePSFRunDll32.exe

Le contenu de votre package doit maintenant ressembler à ce qui suit.Your package content should now look something like this.

Fichiers binaires du package

Modifier le manifeste du packageModify the package manifest

Ouvrez le manifeste de votre package dans un éditeur de texte, puis définissez l' Executable attribut de l' Application élément sur le nom du fichier exécutable du lanceur de fibres discontinues de polyester.Open your package manifest in a text editor, and then set the Executable attribute of the Application element to the name of the PSF Launcher executable file. Si vous connaissez l’architecture de votre application cible, sélectionnez la version appropriée, PSFLauncher32.exe ou PSFLauncher64.exe.If you know the architecture of your target application, select the appropriate version, PSFLauncher32.exe or PSFLauncher64.exe. Si ce n’est pas le cas, PSFLauncher32.exe fonctionnera dans tous les cas.If not, PSFLauncher32.exe will work in all cases. Voici un exemple.Here's an example.

<Package ...>
  ...
  <Applications>
    <Application Id="PSFSample"
                 Executable="PSFLauncher32.exe"
                 EntryPoint="Windows.FullTrustApplication">
      ...
    </Application>
  </Applications>
</Package>

Créer un fichier de configurationCreate a configuration file

Créez un nom de fichier config.json , puis enregistrez ce fichier dans le dossier racine de votre package.Create a file name config.json, and save that file to the root folder of your package. Modifiez l’ID d’application déclaré du config.jssur le fichier pour qu’il pointe vers l’exécutable que vous venez de remplacer.Modify the declared app ID of the config.json file to point to the executable that you just replaced. À l’aide des connaissances acquises à l’aide de process Monitor, vous pouvez également définir le répertoire de travail et utiliser la correction de redirection de fichiers pour rediriger les lectures/écritures vers des fichiers. log sous le répertoire « PSFSampleApp » relatif au package.Using the knowledge that you gained from using Process Monitor, you can also set the working directory as well as use the file redirection fixup to redirect reads/writes to .log files under the package-relative "PSFSampleApp" directory.

{
    "applications": [
        {
            "id": "PSFSample",
            "executable": "PSFSampleApp/PSFSample.exe",
            "workingDirectory": "PSFSampleApp/"
        }
    ],
    "processes": [
        {
            "executable": "PSFSample",
            "fixups": [
                {
                    "dll": "FileRedirectionFixup.dll",
                    "config": {
                        "redirectedPaths": {
                            "packageRelative": [
                                {
                                    "base": "PSFSampleApp/",
                                    "patterns": [
                                        ".*\\.log"
                                    ]
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}

Vous trouverez ci-dessous un guide pour la config.jsdu schéma :Following is a guide for the config.json schema:

ArrayArray keykey ValueValue
applicationsapplications idid Utilisez la valeur de l' Id attribut de l' Application élément dans le manifeste du package.Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications executableexecutable Chemin d’accès relatif au package à l’exécutable que vous souhaitez démarrer.The package-relative path to the executable that you want to start. Dans la plupart des cas, vous pouvez récupérer cette valeur à partir de votre fichier manifeste de package avant de le modifier.In most cases, you can get this value from your package manifest file before you modify it. Il s’agit de la valeur de l' Executable attribut de l' Application élément.It's the value of the Executable attribute of the Application element.
applicationsapplications workingDirectoryworkingDirectory Facultatif Chemin d’accès relatif au package à utiliser comme répertoire de travail de l’application qui démarre.(Optional) A package-relative path to use as the working directory of the application that starts. Si vous ne définissez pas cette valeur, le système d’exploitation utilise le System32 répertoire comme répertoire de travail de l’application.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
processusprocesses executableexecutable Dans la plupart des cas, il s’agit du nom du executable configuré ci-dessus avec le chemin d’accès et l’extension de fichier supprimés.In most cases, this will be the name of the executable configured above with the path and file extension removed.
définitionsfixups dlldll Chemin d’accès relatif au package à la correction,. msix/. AppX à charger.Package-relative path to the fixup, .msix/.appx to load.
définitionsfixups configconfig Facultatif Contrôle le comportement de la dll de correction.(Optional) Controls how the fixup dll behaves. Le format exact de cette valeur varie en fonction de la correction, car chaque correction peut interpréter cet objet « BLOB » comme il le souhaite.The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

Les applications processes clés, et fixups sont des tableaux.The applications, processes, and fixups keys are arrays. Cela signifie que vous pouvez utiliser le config.jssur un fichier pour spécifier plusieurs DLL d’application, de processus et de correction.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

Empaqueter et tester l’applicationPackage and test the app

Ensuite, créez un package.Next, create a package.

makeappx pack /d PackageContents /p PSFSamplePackageFixup.msix

Ensuite, signez-le.Then, sign it.

signtool sign /a /v /fd sha256 /f ExportedSigningCertificate.pfx PSFSamplePackageFixup.msix

Pour plus d’informations, consultez comment créer un certificat de signature de package et Comment signer un package à l’aide de SignToolFor more information, see how to create a package signing certificate and how to sign a package using signtool

À l’aide de PowerShell, installez le package.Using PowerShell, install the package.

Notes

N’oubliez pas de désinstaller le package en premier.Remember to uninstall the package first.

powershell Add-AppPackage .\PSFSamplePackageFixup.msix

Exécutez l’application et observez le comportement avec le correctif de Runtime appliqué.Run the application and observe the behavior with runtime fix applied. Répétez les étapes de diagnostic et d’empaquetage si nécessaire.Repeat the diagnostic and packaging steps as necessary.

Vérifier si l’infrastructure de prise en charge du package est en cours d’exécutionCheck whether the Package Support Framework is running

Vous pouvez vérifier si votre correctif du runtime est en cours d’exécution.You can check whether your runtime fix is running. Pour ce faire, vous pouvez ouvrir le Gestionnaire des tâches et cliquer sur plus de détails.A way to do this is to open Task Manager and click More details. Recherchez l’application à laquelle l’infrastructure de prise en charge du package a été appliquée et développez le détail de l’application pour natifs plus de détails.Find the app that the package support framework was applied to and expand the app detail to veiw more details. Vous devez être en mesure de voir que l’infrastructure de prise en charge du package est en cours d’exécution.You should be able to view that the Package Support Framework is running.

Utiliser la correction de suiviUse the Trace Fixup

Une autre technique pour diagnostiquer les problèmes de compatibilité des applications empaquetées consiste à utiliser la correction de suivi.An alternative technique to diagnosing packaged application compatibility issues is to use the Trace Fixup. Cette DLL est incluse avec les fibres discontinues et fournit une vue de diagnostic détaillée du comportement de l’application, similaire à process Monitor.This DLL is included with the PSF and provides a detailed diagnostic view of the app's behavior, similar to Process Monitor. Il est spécialement conçu pour révéler des problèmes de compatibilité des applications.It is specially designed to reveal application compatibility issues. Pour utiliser la correction de suivi, ajoutez la DLL au package, ajoutez le fragment suivant à votre config.jssur, puis empaquetez et installez votre application.To use the Trace Fixup, add the DLL to the package, add the following fragment to your config.json, and then package and install your application.

{
    "dll": "TraceFixup.dll",
    "config": {
        "traceLevels": {
            "filesystem": "allFailures"
        }
    }
}

Par défaut, la correction de la trace filtre les échecs qui peuvent être considérés comme « attendus ».By default, the Trace Fixup filters out failures that might be considered "expected". Par exemple, les applications peuvent essayer de supprimer de manière inconditionnelle un fichier sans vérifier s’il existe déjà, ce qui a pour effet d’ignorer le résultat.For example, applications might try to unconditionally delete a file without checking to see if it already exists, ignoring the result. Cela a pour conséquence que certains échecs inattendus peuvent être éliminés par filtrage. par conséquent, dans l’exemple ci-dessus, nous choisissons de recevoir tous les échecs des fonctions FileSystem.This has the unfortunate consequence that some unexpected failures might get filtered out, so in the above example, we opt to receive all failures from filesystem functions. Cela est dû au fait que nous savons avant que la tentative de lecture à partir du fichier Config.txt échoue avec le message « fichier introuvable ».We do this because we know from before that the attempt to read from the Config.txt file fails with the message "file not found". Il s’agit d’une défaillance qui est fréquemment observée et qui n’est généralement pas supposée être inattendue.This is a failure that is frequently observed and not generally assumed to be unexpected. En pratique, il est généralement préférable de commencer le filtrage uniquement en cas de défaillances inattendues, puis de revenir à tous les échecs en cas de problème qui ne peut toujours pas être identifié.In practice it's likely best to start out filtering only to unexpected failures, and then falling back to all failures if there's an issue that still can't be identified.

Par défaut, la sortie de la correction de suivi est envoyée au débogueur attaché.By default, the output from the Trace Fixup gets sent to the attached debugger. Pour cet exemple, nous n’allons pas attacher de débogueur et utiliser à la place le programme DebugView de Sysinternals pour afficher sa sortie.For this example, we aren't going to attach a debugger, and will instead use the DebugView program from SysInternals to view its output. Après l’exécution de l’application, nous pouvons voir les mêmes défaillances qu’auparavant, ce qui nous permettrait de faire face aux mêmes corrections du Runtime.After running the app, we can see the same failures as before, which would point us towards the same runtime fixes.

Fichier TraceShim introuvable

Accès TraceShim refusé

Déboguer, étendre ou créer un correctif du RuntimeDebug, extend, or create a runtime fix

Vous pouvez utiliser Visual Studio pour déboguer un correctif du runtime, étendre un correctif du runtime ou en créer un à partir de zéro.You can use Visual Studio to debug a runtime fix, extend a runtime fix, or create one from scratch. Vous devez effectuer ces opérations pour réussir.You'll need to do these things to be successful.

  • Ajouter un projet d’empaquetageAdd a packaging project
  • Ajouter un projet pour le correctif du RuntimeAdd project for the runtime fix
  • Ajouter un projet qui démarre l’exécutable du lanceur de fibres discontinuesAdd a project that starts the PSF Launcher executable
  • Configurer le projet de PackagingConfigure the packaging project

Une fois que vous avez terminé, votre solution ressemblera à ce qui suit.When you're done, your solution will look something like this.

Solution terminée

Examinons chaque projet dans cet exemple.Let's look at each project in this example.

ProjectProject ObjectifPurpose
DesktopApplicationPackageDesktopApplicationPackage Ce projet est basé sur le projet de packaging des applications Windows et génère le package MSIX.This project is based on the Windows Application Packaging project and it outputs the MSIX package.
RuntimefixRuntimefix Il s’agit d’un projet de bibliothèque liée dynamique C++ qui contient une ou plusieurs fonctions de remplacement qui servent de correctif du Runtime.This is a C++ Dynamic-Linked Library project that contains one or more replacement functions that serve as the runtime fix.
PSFLauncherPSFLauncher Il s’agit d’un projet C++ vide.This is C++ Empty Project. Ce projet est un emplacement où collecter les fichiers distribuable du runtime de l’infrastructure de prise en charge du package.This project is a place to collect the runtime distributable files of the Package Support Framework. Il génère un fichier exécutable.It outputs an executable file. Cet exécutable est la première chose qui s’exécute lorsque vous démarrez la solution.That executable is the first thing that runs when you start the solution.
WinFormsDesktopApplicationWinFormsDesktopApplication Ce projet contient le code source d’une application de bureau.This project contains the source code of a desktop application.

Pour consulter un exemple complet qui contient tous ces types de projets, consultez PSFSample.To look at a complete sample that contains all of these types of projects, see PSFSample.

Passons en revue les étapes de création et de configuration de chacun de ces projets dans votre solution.Let's walk through the steps to create and configure each of these projects in your solution.

Créer une solution de packageCreate a package solution

Si vous n’avez pas encore de solution pour votre application de bureau, créez une nouvelle solution vide dans Visual Studio.If you don't already have a solution for your desktop application, create a new Blank Solution in Visual Studio.

Solution vide

Vous pouvez également ajouter les projets d’application de votre choix.You may also want to add any application projects you have.

Ajouter un projet d’empaquetageAdd a packaging project

Si vous n’avez pas encore de projet de création de packages d’applications Windows, créez-en un et ajoutez-le à votre solution.If you don't already have a Windows Application Packaging Project, create one and add it to your solution.

Modèle de projet de package

Pour plus d’informations sur le projet de packaging des applications Windows, consultez empaquetage de votre application à l’aide de Visual Studio.For more information on Windows Application Packaging project, see Package your application by using Visual Studio.

Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet Packaging, sélectionnez modifier, puis ajoutez-le au bas du fichier projet :In Solution Explorer, right-click the packaging project, select Edit, and then add this to the bottom of the project file:

<Target Name="PSFRemoveSourceProject" AfterTargets="ExpandProjectReferences" BeforeTargets="_ConvertItems">
<ItemGroup>
  <FilteredNonWapProjProjectOutput Include="@(_FilteredNonWapProjProjectOutput)">
  <SourceProject Condition="'%(_FilteredNonWapProjProjectOutput.SourceProject)'=='<your runtime fix project name goes here>'" />
  </FilteredNonWapProjProjectOutput>
  <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
  <_FilteredNonWapProjProjectOutput Include="@(FilteredNonWapProjProjectOutput)" />
</ItemGroup>
</Target>

Ajouter un projet pour le correctif du RuntimeAdd project for the runtime fix

Ajoutez un projet de bibliothèque de liens dynamiques (dll) C++ à la solution.Add a C++ Dynamic-Link Library (DLL) project to the solution.

Bibliothèque de correctifs du Runtime

Cliquez avec le bouton droit sur le projet, puis choisissez Propriétés.Right-click the that project, and then choose Properties.

Dans les pages de propriétés, recherchez le champ standard du langage c++ , puis dans la liste déroulante en regard de ce champ, sélectionnez l’option ISO C++ 17 standard (/std : c++ 17) .In the property pages, find the C++ Language Standard field, and then in the drop-down list next to that field, select the ISO C++17 Standard (/std:c++17) option.

ISO 17 (option)

Cliquez avec le bouton droit sur ce projet puis, dans le menu contextuel, choisissez l’option gérer les packages NuGet .Right-click that project, and then in the context menu, choose the Manage Nuget Packages option. Assurez-vous que l’option source du package est définie sur All ou NuGet.org.Ensure that the Package source option is set to All or nuget.org.

Cliquez sur l’icône des paramètres à côté de ce champ.Click the settings icon next that field.

Recherchez le packageNuGet *, puis installez-le pour ce projet.Search for the PSF* Nuget package, and then install it for this project.

package nuget

Si vous souhaitez déboguer ou étendre un correctif du runtime existant, ajoutez les fichiers de correction du runtime que vous avez obtenus à l’aide des conseils décrits dans la section Rechercher un correctif du runtime de ce guide.If you want to debug or extend an existing runtime fix, add the runtime fix files that you obtained by using the guidance described in the Find a runtime fix section of this guide.

Si vous envisagez de créer un tout nouveau correctif, n’ajoutez rien à ce projet pour l’instant.If you intend to create a brand new fix, don't add anything to this project just yet. Nous vous aiderons à ajouter les bons fichiers à ce projet plus loin dans ce guide.We'll help you add the right files to this project later in this guide. Pour le moment, nous allons continuer à configurer votre solution.For now, we'll continue setting up your solution.

Ajouter un projet qui démarre l’exécutable du lanceur de fibres discontinuesAdd a project that starts the PSF Launcher executable

Ajoutez un projet de projet vide C++ à la solution.Add a C++ Empty Project project to the solution.

Projet vide

Ajoutez le package NuGet NuGet à ce projet en utilisant les mêmes instructions que celles décrites dans la section précédente.Add the PSF Nuget package to this project by using the same guidance described in the previous section.

Ouvrez les pages de propriétés du projet et, dans la page paramètres généraux , définissez la propriété nom cible sur PSFLauncher32 ou PSFLauncher64 en fonction de l’architecture de votre application.Open the property pages for the project, and in the General settings page, set the Target Name property to PSFLauncher32 or PSFLauncher64 depending on the architecture of your application.

Référence du lanceur de fibres discontinues

Ajoutez une référence de projet au projet de correctif du runtime dans votre solution.Add a project reference to the runtime fix project in your solution.

Référence du correctif Runtime

Cliquez avec le bouton droit sur la référence, puis, dans la fenêtre Propriétés , appliquez ces valeurs.Right-click the reference, and then in the Properties window, apply these values.

PropertyProperty ValueValue
Copie localeCopy local VraiTrue
Copier les assemblys satellites locauxCopy Local Satellite Assemblies VraiTrue
Sortie de l’assembly de référenceReference Assembly Output VraiTrue
Lier les dépendances de la bibliothèqueLink Library Dependencies FauxFalse
Entrées de dépendance de la bibliothèque de liensLink Library Dependency Inputs FauxFalse

Configurer le projet de PackagingConfigure the packaging project

Dans le projet d’empaquetage, cliquez avec le bouton droit sur le dossier applications , puis choisissez Ajouter une référence.In the packaging project, right-click the Applications folder, and then choose Add Reference.

Ajouter une référence de projet

Choisissez le projet de lancement de fibres discontinues et votre projet d’application de bureau, puis choisissez le bouton OK .Choose the PSF Launcher project and your desktop application project, and then choose the OK button.

Projet de bureau

Notes

Si vous n’avez pas le code source pour votre application, choisissez simplement le projet de lancement de fibres discontinues.If you don't have the source code to your application, just choose the PSF Launcher project. Nous vous montrerons comment référencer votre exécutable lorsque vous créez un fichier de configuration.We'll show you how to reference your executable when you create a configuration file.

Dans le nœud applications , cliquez avec le bouton droit sur l’application du lanceur de fibres discontinues, puis choisissez définir comme point d’entrée.In the Applications node, right-click the PSF Launcher application, and then choose Set as Entry Point.

Définir le point d’entrée

Ajoutez un fichier nommé config.json à votre projet de Packaging, puis copiez et collez le texte JSON suivant dans le fichier.Add a file named config.json to your packaging project, then, copy and paste the following json text into the file. Affectez à la propriété action de package la valeur contenu.Set the Package Action property to Content.

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

Fournissez une valeur pour chaque clé.Provide a value for each key. Utilisez ce tableau comme guide.Use this table as a guide.

ArrayArray keykey ValueValue
applicationsapplications idid Utilisez la valeur de l' Id attribut de l' Application élément dans le manifeste du package.Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications executableexecutable Chemin d’accès relatif au package à l’exécutable que vous souhaitez démarrer.The package-relative path to the executable that you want to start. Dans la plupart des cas, vous pouvez récupérer cette valeur à partir de votre fichier manifeste de package avant de le modifier.In most cases, you can get this value from your package manifest file before you modify it. Il s’agit de la valeur de l' Executable attribut de l' Application élément.It's the value of the Executable attribute of the Application element.
applicationsapplications workingDirectoryworkingDirectory Facultatif Chemin d’accès relatif au package à utiliser comme répertoire de travail de l’application qui démarre.(Optional) A package-relative path to use as the working directory of the application that starts. Si vous ne définissez pas cette valeur, le système d’exploitation utilise le System32 répertoire comme répertoire de travail de l’application.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
processusprocesses executableexecutable Dans la plupart des cas, il s’agit du nom du executable configuré ci-dessus avec le chemin d’accès et l’extension de fichier supprimés.In most cases, this will be the name of the executable configured above with the path and file extension removed.
définitionsfixups dlldll Chemin d’accès relatif au package à la DLL de correction à charger.Package-relative path to the fixup DLL to load.
définitionsfixups configconfig Facultatif Contrôle le comportement de la DLL de correction.(Optional) Controls how the fixup DLL behaves. Le format exact de cette valeur varie en fonction de la correction, car chaque correction peut interpréter cet objet « BLOB » comme il le souhaite.The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

Une fois que vous avez terminé, votre fichier ressemble à config.json ce qui suit.When you're done, your config.json file will look something like this.

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

Notes

Les applications processes clés, et fixups sont des tableaux.The applications, processes, and fixups keys are arrays. Cela signifie que vous pouvez utiliser le config.jssur un fichier pour spécifier plusieurs DLL d’application, de processus et de correction.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

Déboguer un correctif du RuntimeDebug a runtime fix

Dans Visual Studio, appuyez sur F5 pour démarrer le débogueur.In Visual Studio, press F5 to start the debugger. La première chose qui commence est l’application du lanceur de fibres discontinues, qui, à son tour, démarre votre application de bureau cible.The first thing that starts is the PSF Launcher application, which in turn, starts your target desktop application. Pour déboguer l’application de bureau cible, vous devez effectuer un attachement manuel au processus de l’application de bureau en choisissant Déboguer->attacher au processus, puis en sélectionnant le processus d’application.To debug the target desktop application, you'll have to manually attach to the desktop application process by choosing Debug->Attach to Process, and then selecting the application process. Pour autoriser le débogage d’une application .NET avec une DLL de correction du runtime natif, sélectionnez types de code managé et natif (débogage en mode mixte).To permit the debugging of a .NET application with a native runtime fix DLL, select managed and native code types (mixed mode debugging).

Une fois que vous l’avez configurée, vous pouvez définir des points d’arrêt en regard de lignes de code dans le code de l’application de bureau et le projet de correction du Runtime.Once you've set this up, you can set break points next to lines of code in the desktop application code and the runtime fix project. Si vous n’avez pas le code source pour votre application, vous pouvez définir des points d’arrêt uniquement en regard de lignes de code dans votre projet de correction du Runtime.If you don't have the source code to your application, you'll be able to set break points only next to lines of code in your runtime fix project.

Étant donné que le débogage F5 exécute l’application en déployant des fichiers libres à partir du chemin d’accès au dossier de disposition du package, au lieu d’installer à partir d’un package. msix/. AppX, le dossier de disposition n’a généralement pas les mêmes restrictions de sécurité qu’un dossier de package installé.Because F5 debugging runs the application by deploying loose files from the package layout folder path, rather than installing from a .msix/.appx package, the layout folder typically does not have the same security restrictions as an installed package folder. Par conséquent, il n’est pas possible de reproduire les erreurs de refus d’accès au chemin d’accès du package avant d’appliquer un correctif du Runtime.As a result, it may not be possible to reproduce package path access denial errors prior to applying a runtime fix.

Pour résoudre ce problème, utilisez le déploiement de package. msix/. AppX plutôt que le déploiement de fichiers libres F5.To address this issue, use .msix / .appx package deployment rather than F5 loose file deployment. Pour créer un fichier de package. msix/. AppX, utilisez l’utilitaire MakeAppx à partir du SDK Windows, comme décrit ci-dessus.To create a .msix / .appx package file, use the MakeAppx utility from the Windows SDK, as described above. Ou, dans Visual Studio, cliquez avec le bouton droit sur le nœud de votre projet d’application, puis sélectionnez Store-> créer des packages d’application.Or, from within Visual Studio, right-click your application project node and select Store -> Create App Packages.

Un autre problème lié à Visual Studio est qu’il ne dispose pas d’une prise en charge intégrée pour l’attachement à des processus enfants lancés par le débogueur.Another issue with Visual Studio is that it does not have built-in support for attaching to any child processes launched by the debugger. Cela complique le débogage de la logique dans le chemin de démarrage de l’application cible, qui doit être attaché manuellement par Visual Studio après le lancement.This makes it difficult to debug logic in the startup path of the target application, which must be manually attached by Visual Studio after launch.

Pour résoudre ce problème, utilisez un débogueur qui prend en charge l’attachement de processus enfant.To address this issue, use a debugger that supports child process attach. Notez qu’il n’est généralement pas possible de joindre un débogueur juste-à-temps (JIT) à l’application cible.Note that it is generally not possible to attach a just-in-time (JIT) debugger to the target application. Cela est dû au fait que la plupart des techniques JIT impliquent le lancement du débogueur à la place de l’application cible, via la clé de Registre ImageFileExecutionOptions.This is because most JIT techniques involve launching the debugger in place of the target app, via the ImageFileExecutionOptions registry key. Cela annule le mécanisme de détournement utilisé par PSFLauncher.exe pour injecter des FixupRuntime.dll dans l’application cible.This defeats the detouring mechanism used by PSFLauncher.exe to inject FixupRuntime.dll into the target app. WinDbg, inclus dans les outils de débogage pour Windowset obtenu à partir du SDK Windows, prend en charge l’attachement de processus enfant.WinDbg, included in the Debugging Tools for Windows, and obtained from the Windows SDK, supports child process attach. Il prend également en charge le lancement et le débogage directs d’une application UWP.It also now supports directly launching and debugging a UWP app.

Pour déboguer le démarrage de l’application cible en tant que processus enfant, démarrez WinDbg .To debug target application startup as a child process, start WinDbg.

windbg.exe -plmPackage PSFSampleWithFixup_1.0.59.0_x86__7s220nvg1hg3m -plmApp PSFSample

À l' WinDbg invite, activez le débogage enfant et définissez les points d’arrêt appropriés.At the WinDbg prompt, enable child debugging and set appropriate breakpoints.

.childdbg 1
g

(exécuter jusqu’à ce que l’application cible démarre et s’arrête dans le débogueur)(execute until target application starts and breaks into the debugger)

sxe ld fixup.dll
g

(exécuter jusqu’à ce que la DLL de correction soit chargée)(execute until the fixup DLL is loaded)

bp ...

Notes

PLMDebug peut également être utilisé pour attacher un débogueur à une application lors du lancement, et est également inclus dans les outils de débogage pour Windows.PLMDebug can be also used to attach a debugger to an app upon launch, and is also included in the Debugging Tools for Windows. Toutefois, il est plus complexe à utiliser que le support direct fourni à l’heure actuelle par WinDbg.However, it is more complex to use than the direct support now provided by WinDbg.

SupportSupport

Des questions ?Have questions? Posez-nous des questions sur l’espace de conversation de l' infrastructure de support du package sur le site de la communauté MSIX Tech.Ask us on the Package Support Framework conversation space on the MSIX tech community site.