Beginnen Sie mit dem Paket Unterstützungs FrameworkGet Started with Package Support Framework

Das Paket Unterstützungs Framework ist ein Open Source-Kit, mit dem Sie Korrekturen auf Ihre vorhandene Desktop Anwendung anwenden können (ohne den Code zu ändern), sodass Sie in einem msix-Container ausgeführt werden kann.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. Durch das Package Support Framework können in Ihrer Anwendung die bewährten Methoden moderner Laufzeitumgebungen angewandt werden.The Package Support Framework helps your application follow the best practices of the modern runtime environment.

Dieser Artikel bietet einen indepten Einblick in jede Komponente des Paket Unterstützungs Frameworks sowie eine Schritt-für-Schritt-Anleitung für die Verwendung.This article provides an indepth look at each component of Package Support Framework and step by step guide to using it.

Verstehen, was sich innerhalb eines Paket Unterstützungs Frameworks befindetUnderstand what is inside a Package Support Framework

Das Package Support Framework umfasst eine ausführbare Datei, eine Runtime-Manager-DLL und eine Reihe von Runtimekorrekturen.The Package Support Framework contains an executable, a runtime manager DLL, and a set of runtime fixes.

Framework zur Paketunterstützung (Package Support Framework, PSF)

Dies ist der folgende Prozess:Here is the process:

  1. Erstellen Sie eine Konfigurationsdatei, die die Fixes angibt, die Sie auf Ihre Anwendung anwenden möchten.Create a configuration file that specifies the fixes that you want to apply to your application.
  2. Ändern Sie das Paket so, dass es auf die ausführbare Datei des PSF-Start Programms verweist.Modify your package to point to the Package Support Framework (PSF) launcher executable file.

Wenn Benutzer die Anwendung starten, ist das Paket Unterstützungs Framework-Start Programm die erste ausführbare Datei, die ausgeführt wird.When users starts your application, the Package Support Framework launcher is the first executable that runs. Ihre Konfigurationsdatei wird gelesen, und die Runtimekorrekturen und die Runtime-Manager-DLL werden in den Anwendungsprozess eingefügt.It reads your configuration file and injects the runtime fixes and the runtime manager DLL into the application process. Der Runtime-Manager wendet die Korrektur an, wenn diese erforderlich ist, damit die Anwendung in einem MSIX-Container ausgeführt wird.The runtime manager applies the fix when it's needed by the application to run inside of an MSIX container.

Package Support Framework – Einfügen der DLL

Schritt 1: Identifizieren von Problemen mit der Anwendungs KompatibilitätStep 1: Identify packaged application compatibility issues

Erstellen Sie zunächst ein Paket für Ihre Anwendung.First, create a package for your application. Installieren Sie die Anwendung, führen Sie Sie aus, und beobachten Sie das Verhalten.Then, install it, run it, and observe its behavior. Möglicherweise werden Fehlermeldungen angezeigt, anhand derer Sie ein Kompatibilitätsproblem bestimmen können.You might receive error messages that can help you identify a compatibility issue. Zum Identifizieren von Problemen können Sie auch Process Monitor verwenden.You can also use Process Monitor to identify issues. Häufige Probleme beziehen sich auf Anwendungs Annahmen in Bezug auf die Arbeitsverzeichnis-und Programmpfad Berechtigungen.Common issues relate to application assumptions regarding the working directory and program path permissions.

Identifizieren eines Problems mithilfe des Prozess MonitorsUsing Process Monitor to identify an issue

Process Monitor ist ein leistungsfähiges Dienstprogramm zum beobachten der Datei-und Registrierungs Vorgänge einer APP und ihrer Ergebnisse.Process Monitor is a powerful utility for observing an app's file and registry operations, and their results. Dies kann Ihnen dabei helfen, Probleme mit der Anwendungs Kompatibilität zu verstehen.This can help you to understand application compatibility issues. Fügen Sie nach dem Öffnen des Prozess Monitors einen Filter (Filter > Filter...) hinzu, um nur Ereignisse aus der ausführbaren Datei der Anwendung einzubeziehen.After opening Process Monitor, add a filter (Filter > Filter…) to include only events from the application executable.

Procmon-App-Filter

Eine Liste der Ereignisse wird angezeigt.A list of events will appear. Bei vielen dieser Ereignisse wird das Wort Success in der Spalte Ergebnis angezeigt.For many of these events, the word SUCCESS will appear in the Result column.

Procmon-Ereignisse

Optional können Sie Ereignisse so filtern, dass nur Fehler angezeigt werden.Optionally, you can filter events to only show only failures.

Procmon-Ausschluss erfolgreich

Wenn Sie vermuten, dass ein Fehler aufgrund eines Dateisystem Zugriffs aufgetreten ist, suchen Sie nach Fehlern, die sich unter dem System32/syswow64-oder Paketdatei Pfad befinden.If you suspect a filesystem access failure, search for failed events that are under either the System32/SysWOW64 or the package file path. Filter können auch hier helfen.Filters can also help here, too. Starten Sie am Ende dieser Liste, und Scrollen Sie nach oben.Start at the bottom of this list and scroll upwards. Fehler, die am Ende dieser Liste angezeigt werden, sind zuletzt aufgetreten.Failures that appear at the bottom of this list have occurred most recently. Achten Sie besonders auf Fehler, die Zeichen folgen wie "Zugriff verweigert" und "Pfad/Name nicht gefunden" enthalten, und ignorieren Sie Dinge, die nicht verdächtig erscheinen.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. In PSF Sample sind zwei Probleme aufgetreten.The PSFSample has two issues. Diese Probleme werden in der Liste angezeigt, die in der folgenden Abbildung dargestellt ist.You can see those issues in the list that appears in the following image.

Procmon-Config.txt

Beim ersten in diesem Bild angezeigten Problem kann die Anwendung nicht aus der Datei "Config.txt" lesen, die sich im Pfad "c:\windows\SysWOW64" befindet.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. Es ist unwahrscheinlich, dass die Anwendung versucht, direkt auf diesen Pfad zu verweisen.It's unlikely that the application is trying to reference that path directly. Höchstwahrscheinlich versucht es, aus dieser Datei zu lesen, indem ein relativer Pfad verwendet wird. Standardmäßig ist "System32/syswow64" das Arbeitsverzeichnis der Anwendung.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. Dies deutet darauf hin, dass die Anwendung erwartet, dass das aktuelle Arbeitsverzeichnis auf eine beliebige Stelle im Paket festgelegt wird.This suggests that the application is expecting its current working directory to be set to somewhere in the package. Wenn wir innerhalb von AppX suchen, sehen wir, dass die Datei im selben Verzeichnis wie die ausführbare Datei vorhanden ist.Looking inside of the appx, we can see that the file exists in the same directory as the executable.

App-Config.txt

Das zweite Problem wird in der folgenden Abbildung angezeigt.The second issue appears in the following image.

Procmon-Protokolldatei

In diesem Fall kann die Anwendung die Log-Datei nicht in den zugehörigen Paketpfad schreiben.In this issue, the application is failing to write a .log file to its package path. Dies würde darauf hindeuten, dass ein Datei Umleitungen-Fixup hilfreich sein könnte.This would suggest that a file redirection fixup might help.

Schritt 2: Suchen eines Lauf Zeit FixesStep 2: Find a runtime fix

Das PSF enthält Lauf Zeit Korrekturen, die Sie zurzeit verwenden können, z. b. das Korrigieren der Datei Umleitung.The PSF contains runtime fixes that you can use right now, such as the file redirection fixup.

Datei Umleitung-FixupFile Redirection Fixup

Sie können das Fixup für die Datei Umleitung zum Umleiten von versuchen zum Schreiben oder Lesen von Daten in einem Verzeichnis verwenden, das nicht von einer Anwendung aus zugänglich ist, die in einem msix-Container ausgeführt wird.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.

Wenn Ihre Anwendung z. b. in eine Protokolldatei schreibt, die sich in demselben Verzeichnis wie die ausführbare Datei der Anwendung befindet, können Sie die Datei Umleitung verwenden, um diese Protokolldatei an einem anderen Speicherort (z. b. dem lokalen app-Datenspeicher) zu erstellen.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.

Lauf Zeit Fehlerbehebungen aus der CommunityRuntime fixes from the community

Überprüfen Sie die Communitybeiträge zu unserer GitHub -Seite.Make sure to review the community contributions to our GitHub page. Es ist möglich, dass andere Entwickler ein ähnliches Problem gelöst haben und eine Lauf Zeitkorrektur freigegeben haben.It's possible that other developers have resolved an issue similar to yours and have shared a runtime fix.

Schritt 3: Anwenden eines Lauf Zeit FixesStep 3: Apply a runtime fix

Sie können eine vorhandene Lauf Zeitkorrektur mit einigen einfachen Tools aus dem Windows SDK anwenden, und befolgen Sie diese Schritte.You can apply an existing runtime fix with a few simple tools from the Windows SDK, and by following these steps.

  • Erstellen eines paketlayoutordnersCreate a package layout folder
  • Paket Unterstützungs Framework-DateienGet the Package Support Framework files
  • Fügen Sie Sie dem Paket hinzu.Add them to your package
  • Ändern des Paket ManifestsModify the package manifest
  • Erstellen einer KonfigurationsdateiCreate a configuration file

Wir werden jede Aufgabe durchgehen.Let's go through each task.

Erstellen des paketlayoutordnersCreate the package layout folder

Wenn Sie bereits über eine msix-Datei (oder eine AppX-Datei) verfügen, können Sie den Inhalt in einen layoutordner entpacken, der als Stagingbereich für das Paket fungiert.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. Sie können dies über eine Eingabeaufforderung mithilfe des makeappx-Tools ausführen, basierend auf Ihrem Installationspfad des SDKs. hier finden Sie das makeappx.exe Tool auf Ihrem 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.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

Dadurch erhalten Sie etwas, das wie folgt aussieht.This will give you something that looks like the following.

Paket Layout

Wenn Sie nicht über eine msix-Datei (oder eine AppX-Datei) verfügen, können Sie den Paket Ordner und die Dateien von Grund auf neu erstellen.If you don't have a .msix (or .appx) file to start with, you can create the package folder and files from scratch.

Paket Unterstützungs Framework-DateienGet the Package Support Framework files

Sie können das PSF-nuget-Paket mit dem eigenständigen nuget-Befehlszeilen Tool oder über Visual Studio erhalten.You can get the PSF Nuget package by using the standalone Nuget command line tool or via Visual Studio.

Paket mit dem Befehlszeilen ToolGet the package by using the command line tool

Installieren Sie das nuget-Befehlszeilen Tool von diesem Speicherort: https://www.nuget.org/downloads .Install the Nuget command line tool from this location: https://www.nuget.org/downloads. Führen Sie dann in der nuget-Befehlszeile den folgenden Befehl aus:Then, from the Nuget command line, run this command:

nuget install Microsoft.PackageSupportFramework

Alternativ können Sie die Paket Erweiterung in ZIP-Datei umbenennen und diese entzippen.Alternatively, you can rename the package extension to .zip and unzip it. Alle benötigten Dateien befinden sich im Ordner "/bin".All the files you need will be under the /bin folder.

Paket mit Visual StudioGet the package by using Visual Studio

Klicken Sie in Visual Studio mit der rechten Maustaste auf den Projektmappen-oder Projekt Knoten, und wählen Sie einen der Befehle nuget-Pakete verwalten aus.In Visual Studio, right-click your solution or project node and pick one of the Manage Nuget Packages commands. Suchen Sie nach Microsoft. packagesupportframework oder PSF , um das Paket auf Nuget.org zu finden. Installieren Sie es dann.Search for Microsoft.PackageSupportFramework or PSF to find the package on Nuget.org. Then, install it.

Fügen Sie dem Paket die Framework-Unterstützungs Dateien für das Paket hinzu.Add the Package Support Framework files to your package

Fügen Sie dem Paket Verzeichnis die erforderlichen 32-Bit-und 64-Bit-PSF-DLLs und ausführbaren Dateien hinzu.Add the required 32-bit and 64-bit PSF DLLs and executable files to the package directory. Orientieren Sie sich an der folgenden Tabelle.Use the following table as a guide. Außerdem möchten Sie alle benötigten Lauf Zeit Korrekturen einschließen.You'll also want to include any runtime fixes that you need. In unserem Beispiel benötigen wir die Lauf Zeitkorrektur für die Datei Umleitung.In our example, we need the file redirection runtime fix.

Ausführbare Datei der Anwendung ist x64Application executable is x64 Ausführbare Datei der Anwendung ist x86Application executable is x86
PSFLauncher64.exePSFLauncher64.exe PSFLauncher32.exePSFLauncher32.exe
PSFRuntime64.dllPSFRuntime64.dll PSFRuntime32.dllPSFRuntime32.dll
PSFRunDll64.exePSFRunDll64.exe PSFRunDll32.exePSFRunDll32.exe

Ihr Paket Inhalt sollte nun in etwa wie folgt aussehen.Your package content should now look something like this.

Paket Binärdateien

Ändern des Paket ManifestsModify the package manifest

Öffnen Sie das Paket Manifest in einem Text-Editor, und legen Sie dann das- Executable Attribut des- Application Elements auf den Namen der ausführbaren Datei des PSF-Start Programms fest.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. Wenn Sie die Architektur der Zielanwendung kennen, wählen Sie die entsprechende Version aus, PSFLauncher32.exe oder PSFLauncher64.exe.If you know the architecture of your target application, select the appropriate version, PSFLauncher32.exe or PSFLauncher64.exe. Wenn dies nicht der Fall ist, funktioniert PSFLauncher32.exe in allen Fällen.If not, PSFLauncher32.exe will work in all cases. Hier finden Sie ein Beispiel dafür.Here's an example.

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

Erstellen einer KonfigurationsdateiCreate a configuration file

Erstellen Sie einen Dateinamen config.json , und speichern Sie die Datei im Stamm Ordner des Pakets.Create a file name config.json, and save that file to the root folder of your package. Ändern Sie die deklarierte APP-ID des config.jsin der Datei so, dass Sie auf die soeben ersetzte ausführbare Datei verweist.Modify the declared app ID of the config.json file to point to the executable that you just replaced. Mithilfe des Wissens, das Sie bei der Verwendung des Prozess Monitors gewonnen haben, können Sie auch das Arbeitsverzeichnis festlegen und die Datei Umleitung zum Umleiten von Lese-/Schreibvorgängen an Log-Dateien im Paket bezogenen "psfsampleapp"-Verzeichnis verwenden.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"
                                    ]
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}

Im folgenden finden Sie eine Anleitung für die config.jsfür das Schema:Following is a guide for the config.json schema:

ArrayArray Schlüsselkey WertValue
applicationsapplications idid Verwenden Sie den Wert des- Id Attributs des- Application Elements im Paket Manifest.Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications executableexecutable Der Paket relative Pfad zur ausführbaren Datei, die Sie starten möchten.The package-relative path to the executable that you want to start. In den meisten Fällen können Sie diesen Wert aus der Paket Manifest-Datei erhalten, bevor Sie ihn ändern.In most cases, you can get this value from your package manifest file before you modify it. Dies ist der Wert des- Executable Attributs des- Application Elements.It's the value of the Executable attribute of the Application element.
applicationsapplications workingDirectoryworkingDirectory Optionale Ein Paket relativer Pfad, der als Arbeitsverzeichnis der Anwendung verwendet werden soll, die gestartet wird.(Optional) A package-relative path to use as the working directory of the application that starts. Wenn Sie diesen Wert nicht festlegen, verwendet das Betriebssystem das System32 Verzeichnis als Arbeitsverzeichnis der Anwendung.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
Prozesseprocesses executableexecutable In den meisten Fällen ist dies der Name der executable oben konfigurierten, wobei der Pfad und die Dateierweiterung entfernt wurden.In most cases, this will be the name of the executable configured above with the path and file extension removed.
Fixupsfixups DLL-Dateidll Paket relativer Pfad zum Fixup,. msix/. AppX, das geladen werden soll.Package-relative path to the fixup, .msix/.appx to load.
Fixupsfixups configconfig Optionale Steuert, wie sich die Fixup-dll verhält.(Optional) Controls how the fixup dll behaves. Das genaue Format dieses Werts variiert je nach Fixup, da jedes Fixup dieses "BLOB" wie erwartet interpretieren kann.The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

Die applications processes Schlüssel, und fixups sind Arrays.The applications, processes, and fixups keys are arrays. Dies bedeutet, dass Sie die config.json-Datei verwenden können, um mehr als eine Anwendung, einen Prozess und eine Fixup-DLL anzugeben.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

Packen und Testen der APPPackage and test the app

Erstellen Sie als nächstes ein Paket.Next, create a package.

makeappx pack /d PackageContents /p PSFSamplePackageFixup.msix

Signieren Sie Sie anschließend.Then, sign it.

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

Weitere Informationen finden Sie unter Erstellen eines Paket Signatur Zertifikats und Signieren eines Pakets mithilfe von SignTool .For more information, see how to create a package signing certificate and how to sign a package using signtool

Installieren Sie das Paket mithilfe von PowerShell.Using PowerShell, install the package.

Hinweis

Denken Sie daran, das Paket zuerst zu deinstallieren.Remember to uninstall the package first.

powershell Add-AppPackage .\PSFSamplePackageFixup.msix

Führen Sie die Anwendung aus, und beobachten Sie das Verhalten bei angewendetem Lauf ZeitkorrekturRun the application and observe the behavior with runtime fix applied. Wiederholen Sie die Schritte zur Diagnose und Paket Erstellung nach Bedarf.Repeat the diagnostic and packaging steps as necessary.

Überprüfen, ob das Paket Unterstützungs Framework ausgeführt wirdCheck whether the Package Support Framework is running

Sie können überprüfen, ob die Lauf Zeitkorrektur ausgeführt wird.You can check whether your runtime fix is running. Eine Möglichkeit besteht darin, den Task- Manager zu öffnen und auf Weitere Detailszu klicken.A way to do this is to open Task Manager and click More details. Suchen Sie die APP, auf die das Paket Unterstützungs Framework angewendet wurde, und erweitern Sie das App-Detail, um weitere Details zu erhalten.Find the app that the package support framework was applied to and expand the app detail to veiw more details. Sie sollten anzeigen können, dass das Paket Unterstützungs Framework ausgeführt wird.You should be able to view that the Package Support Framework is running.

Verwenden des Ablaufverfolgungs-FixupUse the Trace Fixup

Eine alternative Methode zur Diagnose von Problemen mit der Anwendungs Kompatibilität ist die Verwendung des Ablaufverfolgungs-Fixup.An alternative technique to diagnosing packaged application compatibility issues is to use the Trace Fixup. Diese dll ist im PSF enthalten und bietet eine ausführliche Diagnose Ansicht des App-Verhaltens, ähnlich wie bei Process Monitor.This DLL is included with the PSF and provides a detailed diagnostic view of the app's behavior, similar to Process Monitor. Es wurde speziell entwickelt, um Anwendungs Kompatibilitätsprobleme offenzulegen.It is specially designed to reveal application compatibility issues. Fügen Sie zum Verwenden des Ablaufverfolgungs-Fixup die dll zum Paket hinzu, fügen Sie dem config.jsauf das folgende Fragment hinzu, und Verpacken und installieren Sie dann die Anwendung.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"
        }
    }
}

Standardmäßig filtert das Ablaufverfolgungs-Fixup Fehler, die möglicherweise als "erwartet" angesehen werden.By default, the Trace Fixup filters out failures that might be considered "expected". Beispielsweise kann es vorkommen, dass Anwendungen versuchen, eine Datei bedingungslos zu löschen, ohne zu überprüfen, ob Sie bereits vorhanden ist. das Ergebnis wird ignoriert.For example, applications might try to unconditionally delete a file without checking to see if it already exists, ignoring the result. Dies hat die bedauerliche Folge, dass einige unerwartete Fehler herausgefiltert werden könnten. im obigen Beispiel haben wir also die Möglichkeit, alle Fehler aus den Dateisystemfunktionen zu erhalten.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. Dies ist der Fall, da wir von erst wissen, dass der Versuch, aus der Config.txt Datei zu lesen, mit der Meldung "Datei nicht gefunden" fehlschlägt.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". Dabei handelt es sich um einen Fehler, der häufig beobachtet wird und nicht als unerwartet angesehen wird.This is a failure that is frequently observed and not generally assumed to be unexpected. In der Praxis ist es wahrscheinlich, dass Sie zunächst nur nach unerwarteten Fehlern Filtern und dann auf alle Fehler zurückgreifen, wenn ein Problem vorliegt, das noch nicht identifiziert werden kann.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.

Standardmäßig wird die Ausgabe des Ablaufverfolgungs-Fixup an den angefügten Debugger gesendet.By default, the output from the Trace Fixup gets sent to the attached debugger. In diesem Beispiel werden wir keinen Debugger anfügen und stattdessen das DebugView -Programm von Sysinternals verwenden, um die Ausgabe anzuzeigen.For this example, we aren't going to attach a debugger, and will instead use the DebugView program from SysInternals to view its output. Nach dem Ausführen der App werden dieselben Fehler wie zuvor angezeigt, was uns auf dieselben Lauf Zeit Korrekturen hinweisen würde.After running the app, we can see the same failures as before, which would point us towards the same runtime fixes.

Die tracesit-Datei wurde nicht gefunden.

Tracesit-Zugriff verweigert

Debuggen, erweitern oder Erstellen einer Lauf ZeitkorrekturDebug, extend, or create a runtime fix

Sie können Visual Studio verwenden, um eine Lauf Zeitkorrektur zu debuggen, eine Lauf Zeitkorrektur zu erweitern oder eine von Grund auf neu zu erstellenYou can use Visual Studio to debug a runtime fix, extend a runtime fix, or create one from scratch. Sie müssen diese Schritte ausführen, um erfolgreich zu sein.You'll need to do these things to be successful.

  • Hinzufügen eines Paket ProjektsAdd a packaging project
  • Projekt für die Lauf Zeitkorrektur hinzufügenAdd project for the runtime fix
  • Fügen Sie ein Projekt hinzu, das die ausführbare PSF-Start ProgrammAdd a project that starts the PSF Launcher executable
  • Konfigurieren des Paket ProjektsConfigure the packaging project

Wenn Sie fertig sind, wird die Projekt Mappe in etwa wie folgt aussehen.When you're done, your solution will look something like this.

Abgeschlossene Lösung

Betrachten wir jedes Projekt in diesem Beispiel.Let's look at each project in this example.

ProjectProject ZweckPurpose
DesktopapplicationpackageDesktopApplicationPackage Dieses Projekt basiert auf dem Windows-anwendungspaketprojekt und gibt das msix-Paket aus.This project is based on the Windows Application Packaging project and it outputs the MSIX package.
RuntimefixRuntimefix Dabei handelt es sich um ein mit einer dynamischen C++ verknüpftes Bibliotheksprojekt, das eine oder mehrere Ersatz Funktionen enthält, die als Lauf Zeitkorrektur dienen.This is a C++ Dynamic-Linked Library project that contains one or more replacement functions that serve as the runtime fix.
PsflauncherPSFLauncher Dabei handelt es sich um ein C++ leeres Projekt.This is C++ Empty Project. Dieses Projekt ist ein Ort, an dem die verteilbaren Laufzeitdateien des Paket Unterstützungs Frameworks erfasst werden können.This project is a place to collect the runtime distributable files of the Package Support Framework. Er gibt eine ausführbare Datei aus.It outputs an executable file. Diese ausführbare Datei ist das erste, was beim Starten der Projekt Mappe ausgeführt wird.That executable is the first thing that runs when you start the solution.
WinformsdesktopapplicationWinFormsDesktopApplication Dieses Projekt enthält den Quellcode einer Desktop Anwendung.This project contains the source code of a desktop application.

Ein vollständiges Beispiel, das alle diese Projekttypen enthält, finden Sie unter psfsample.To look at a complete sample that contains all of these types of projects, see PSFSample.

Gehen wir die Schritte zum Erstellen und Konfigurieren der einzelnen Projekte in der Projekt Mappe durch.Let's walk through the steps to create and configure each of these projects in your solution.

Erstellen einer PaketlösungCreate a package solution

Wenn Sie noch nicht über eine Projekt Mappe für Ihre Desktop Anwendung verfügen, erstellen Sie in Visual Studio eine neue leere Projekt Mappe.If you don't already have a solution for your desktop application, create a new Blank Solution in Visual Studio.

Leere Projekt Mappe

Möglicherweise möchten Sie auch beliebige Anwendungsprojekte hinzufügen.You may also want to add any application projects you have.

Hinzufügen eines Paket ProjektsAdd a packaging project

Wenn Sie noch kein Windows- Paket für die AnwendungspaketErstellung haben, erstellen Sie es, und fügen Sie es der Projekt Mappe hinzu.If you don't already have a Windows Application Packaging Project, create one and add it to your solution.

Paket Projektvorlage

Weitere Informationen zum Paket Erstellungs Projekt für Windows-Anwendungen finden Sie unter Verpacken der Anwendung mithilfe von Visual Studio.For more information on Windows Application Packaging project, see Package your application by using Visual Studio.

Klicken Sie in Projektmappen-Explorermit der rechten Maustaste auf das Paket Erstellungs Projekt, wählen Sie Bearbeitenaus, und fügen Sie es dann am Ende der Projektdatei hinzu: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>

Projekt für die Lauf Zeitkorrektur hinzufügenAdd project for the runtime fix

Fügen Sie der Projekt Mappe ein DLL-Projekt (C++ Dynamic-Link Library) hinzu.Add a C++ Dynamic-Link Library (DLL) project to the solution.

Lauf Zeitkorrektur-Bibliothek

Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie dann Eigenschaftenaus.Right-click the that project, and then choose Properties.

Suchen Sie auf den Eigenschaften Seiten das Feld C++ Language Standard , und wählen Sie dann in der Dropdown Liste neben diesem Feld die Option ISO C++ 17 Standard (/Std: C++ 17) aus.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)

Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie dann im Kontextmenü die Option nuget-Pakete verwalten aus.Right-click that project, and then in the context menu, choose the Manage Nuget Packages option. Stellen Sie sicher, dass die Option Paketquelle auf alle oder nuget.orgfestgelegt ist.Ensure that the Package source option is set to All or nuget.org.

Klicken Sie auf das Symbol "Einstellungen" neben diesem Feld.Click the settings icon next that field.

Suchen Sie nach dem PSF* nuget-Paket, und installieren Sie es für dieses Projekt.Search for the PSF* Nuget package, and then install it for this project.

nuget-paket

Wenn Sie eine vorhandene Lauf Zeitkorrektur Debuggen oder erweitern möchten, fügen Sie die von Ihnen erhaltenen Lauf Zeitkorrektur Dateien mithilfe der Anleitungen im Abschnitt Suchen eines Lauf Zeit Fixes dieses Handbuchs hinzu.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.

Wenn Sie beabsichtigen, einen brandneuen Fix zu erstellen, fügen Sie diesem Projekt noch nichts hinzu.If you intend to create a brand new fix, don't add anything to this project just yet. Wir unterstützen Sie beim Hinzufügen der richtigen Dateien zu diesem Projekt später in diesem Handbuch.We'll help you add the right files to this project later in this guide. Zum jetzigen Zeit werden wir die Einrichtung Ihrer Lösung fortsetzen.For now, we'll continue setting up your solution.

Fügen Sie ein Projekt hinzu, das die ausführbare PSF-Start ProgrammAdd a project that starts the PSF Launcher executable

Fügen Sie der Projekt Mappe ein C++ leeres Projekt Projekt hinzu.Add a C++ Empty Project project to the solution.

Leeres Projekt

Fügen Sie das PSF -nuget-Paket zu diesem Projekt hinzu, indem Sie die im vorherigen Abschnitt beschriebene Anleitung verwenden.Add the PSF Nuget package to this project by using the same guidance described in the previous section.

Öffnen Sie die Eigenschaften Seiten für das Projekt, und legen Sie auf der Seite Allgemeine Einstellungen die Eigenschaft Ziel Name auf oder fest, PSFLauncher32 abhängig von PSFLauncher64 der Architektur Ihrer Anwendung.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.

PSF-Start Programm Referenz

Fügen Sie dem Lauf Zeitkorrektur Projekt in der Projekt Mappe einen Projekt Verweis hinzu.Add a project reference to the runtime fix project in your solution.

Referenz zur Lauf Zeitkorrektur

Klicken Sie mit der rechten Maustaste auf den Verweis, und wenden Sie dann im Eigenschaften Fenster diese Werte an.Right-click the reference, and then in the Properties window, apply these values.

EigenschaftProperty WertValue
Lokale KopieCopy local RichtigTrue
Lokale Satellitenassemblys kopierenCopy Local Satellite Assemblies RichtigTrue
VerweisassemblyausgabeReference Assembly Output RichtigTrue
Bibliothekabhängigkeiten verknüpfenLink Library Dependencies FalschFalse
Verknüpfen von Bibliotheks Abhängigkeits EingabenLink Library Dependency Inputs FalschFalse

Konfigurieren des Paket ProjektsConfigure the packaging project

Klicken Sie im Paket Erstellungs Projekt mit der rechten Maustaste auf den Ordner Anwendungen , und wählen Sie dann Verweis hinzufügenaus.In the packaging project, right-click the Applications folder, and then choose Add Reference.

Hinzufügen eines Projektverweises

Wählen Sie das PSF-Start Programm Projekt und Ihr Desktop Anwendungsprojekt aus, und klicken Sie dann auf die Schaltfläche OK .Choose the PSF Launcher project and your desktop application project, and then choose the OK button.

Desktopprojekt

Hinweis

Wenn Sie nicht über den Quellcode für Ihre Anwendung verfügen, wählen Sie einfach das PSF-Start Programm Projekt aus.If you don't have the source code to your application, just choose the PSF Launcher project. Wir zeigen Ihnen, wie Sie auf die ausführbare Datei verweisen, wenn Sie eine Konfigurationsdatei erstellen.We'll show you how to reference your executable when you create a configuration file.

Klicken Sie im Knoten Anwendungen mit der rechten Maustaste auf die PSF-Start Programm Anwendung, und wählen Sie dann als Einstiegspunkt festlegenaus.In the Applications node, right-click the PSF Launcher application, and then choose Set as Entry Point.

Festlegen als Einstiegspunkt

Fügen Sie dem config.json Paketierungs Projekt eine Datei mit dem Namen hinzu, kopieren Sie den folgenden JSON-Text, und fügen Sie ihn in die Datei ein.Add a file named config.json to your packaging project, then, copy and paste the following json text into the file. Legen Sie die Eigenschaft Paketaktion auf Inhaltfest.Set the Package Action property to Content.

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

Geben Sie einen Wert für jeden Schlüssel an.Provide a value for each key. Verwenden Sie diese Tabelle als Richtlinie.Use this table as a guide.

ArrayArray Schlüsselkey WertValue
applicationsapplications idid Verwenden Sie den Wert des- Id Attributs des- Application Elements im Paket Manifest.Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications executableexecutable Der Paket relative Pfad zur ausführbaren Datei, die Sie starten möchten.The package-relative path to the executable that you want to start. In den meisten Fällen können Sie diesen Wert aus der Paket Manifest-Datei erhalten, bevor Sie ihn ändern.In most cases, you can get this value from your package manifest file before you modify it. Dies ist der Wert des- Executable Attributs des- Application Elements.It's the value of the Executable attribute of the Application element.
applicationsapplications workingDirectoryworkingDirectory Optionale Ein Paket relativer Pfad, der als Arbeitsverzeichnis der Anwendung verwendet werden soll, die gestartet wird.(Optional) A package-relative path to use as the working directory of the application that starts. Wenn Sie diesen Wert nicht festlegen, verwendet das Betriebssystem das System32 Verzeichnis als Arbeitsverzeichnis der Anwendung.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
Prozesseprocesses executableexecutable In den meisten Fällen ist dies der Name der executable oben konfigurierten, wobei der Pfad und die Dateierweiterung entfernt wurden.In most cases, this will be the name of the executable configured above with the path and file extension removed.
Fixupsfixups DLL-Dateidll Paket relativer Pfad zur Fixup-dll, die geladen werden soll.Package-relative path to the fixup DLL to load.
Fixupsfixups configconfig Optionale Steuert, wie sich die Fixup-dll verhält.(Optional) Controls how the fixup DLL behaves. Das genaue Format dieses Werts variiert je nach Fixup, da jedes Fixup dieses "BLOB" wie erwartet interpretieren kann.The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

Wenn Sie fertig sind, config.json sieht die Datei in etwa wie folgt aus.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" } ]
    }
  ]
}

Hinweis

Die applications processes Schlüssel, und fixups sind Arrays.The applications, processes, and fixups keys are arrays. Dies bedeutet, dass Sie die config.json-Datei verwenden können, um mehr als eine Anwendung, einen Prozess und eine Fixup-DLL anzugeben.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

Debuggen einer Lauf ZeitkorrekturDebug a runtime fix

Drücken Sie in Visual Studio F5, um den Debugger zu starten.In Visual Studio, press F5 to start the debugger. Der erste Schritt ist die PSF-Start Programm Anwendung, die ihrerseits ihre Ziel Desktop Anwendung startet.The first thing that starts is the PSF Launcher application, which in turn, starts your target desktop application. Wenn Sie die Ziel Desktop Anwendung debuggen möchten, müssen Sie Sie manuell an den Desktop Anwendungsprozess anfügen, indem Sie Debuggen >an den Prozess anhängenauswählen und dann den Anwendungsprozess auswählen.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. Um das Debuggen einer .NET-Anwendung mit einer systemeigenen Runtime Fix-dll zuzulassen, wählen Sie verwaltete und systemeigene Codetypen (Debuggen im gemischten Modus).To permit the debugging of a .NET application with a native runtime fix DLL, select managed and native code types (mixed mode debugging).

Nachdem Sie diese Einrichtung festgelegt haben, können Sie im Desktop Anwendungscode und im Lauf Zeitkorrektur Projekt Breakpoints neben Codezeilen festlegen.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. Wenn Sie nicht über den Quellcode für Ihre Anwendung verfügen, können Sie Breakpoints nur neben Codezeilen im Lauf Zeitkorrektur Projekt festlegen.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.

Da der F5-Debugger die Anwendung durch Bereitstellen von lockeren Dateien aus dem paketlayoutorpfad ausführt, anstatt aus einem msix-/AppX-Paket zu installieren, weist der layoutordner in der Regel nicht die gleichen Sicherheitseinschränkungen wie ein installierter Paket Ordner auf.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. Daher ist es u. u. nicht möglich, die Zugriffs Verweigerungs Fehler des Paket Pfads zu reproduzieren, bevor Sie eine Lauf Zeitkorrektur anwenden.As a result, it may not be possible to reproduce package path access denial errors prior to applying a runtime fix.

Um dieses Problem zu beheben, verwenden Sie die msix-/AppX-Paketbereitstellung anstelle der F5-Datei Bereitstellung.To address this issue, use .msix / .appx package deployment rather than F5 loose file deployment. Verwenden Sie zum Erstellen einer msix-/AppX-Paketdatei das Dienstprogramm makeappx aus der Windows SDK, wie oben beschrieben.To create a .msix / .appx package file, use the MakeAppx utility from the Windows SDK, as described above. Oder klicken Sie in Visual Studio mit der rechten Maustaste auf den Anwendungsprojekt Knoten, und wählen Sie Store-> App-Pakete erstellenaus.Or, from within Visual Studio, right-click your application project node and select Store -> Create App Packages.

Ein weiteres Problem mit Visual Studio besteht darin, dass es keine integrierte Unterstützung für das Anfügen an untergeordnete Prozesse bietet, die vom Debugger gestartet werden.Another issue with Visual Studio is that it does not have built-in support for attaching to any child processes launched by the debugger. Dies erschwert das Debuggen von Logik im Startpfad der Zielanwendung, die nach dem Start manuell von Visual Studio angefügt werden muss.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.

Um dieses Problem zu beheben, verwenden Sie einen Debugger, der das Anfügen untergeordneter Prozesse unterstützt.To address this issue, use a debugger that supports child process attach. Beachten Sie, dass es im Allgemeinen nicht möglich ist, einen Just-in-time (JIT)-Debugger an die Zielanwendung anzufügen.Note that it is generally not possible to attach a just-in-time (JIT) debugger to the target application. Dies liegt daran, dass bei den meisten JIT-Techniken der Debugger anstelle der Ziel-App über den Registrierungsschlüssel imagefileexecutionoptions gestartet werden muss.This is because most JIT techniques involve launching the debugger in place of the target app, via the ImageFileExecutionOptions registry key. Dadurch wird der von PSFLauncher.exe verwendete detouring-Mechanismus für das Einfügen FixupRuntime.dll in die Ziel-App besiegt.This defeats the detouring mechanism used by PSFLauncher.exe to inject FixupRuntime.dll into the target app. WinDbg, das in den Debuggingtools für Windowsenthalten und vom Windows SDKabgerufen wird, unterstützt das Anfügen von untergeordneten Prozessen.WinDbg, included in the Debugging Tools for Windows, and obtained from the Windows SDK, supports child process attach. Sie unterstützt jetzt auch das direkte starten und Debuggen einer UWP-App.It also now supports directly launching and debugging a UWP app.

Um den Start der Zielanwendung als untergeordneten Prozess zu debuggen, starten Sie WinDbg .To debug target application startup as a child process, start WinDbg.

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

Aktivieren Sie an der Eingabeaufforderung das untergeordnete WinDbg Debuggen, und legen Sie entsprechende BreakpointsAt the WinDbg prompt, enable child debugging and set appropriate breakpoints.

.childdbg 1
g

(ausführen, bis die Zielanwendung gestartet wird und in den Debugger umbricht)(execute until target application starts and breaks into the debugger)

sxe ld fixup.dll
g

(ausführen, bis die Fixup-dll geladen wurde)(execute until the fixup DLL is loaded)

bp ...

Hinweis

Plmdebug kann auch verwendet werden, um beim Start einen Debugger an eine APP anzufügen, und ist auch in den Debuggingtools für Windowsenthalten.PLMDebug can be also used to attach a debugger to an app upon launch, and is also included in the Debugging Tools for Windows. Es ist jedoch komplexer, zu verwenden, als die direkte Unterstützung, die jetzt von WinDBG bereitgestellt wird.However, it is more complex to use than the direct support now provided by WinDbg.

SupportSupport

Haben Sie Fragen?Have questions? Bitten Sie uns, auf der msix Tech Community-Website auf der Seite zur Unterstützung von frameworkkonversationenAsk us on the Package Support Framework conversation space on the MSIX tech community site.