Skip to main content This browser is no longer supported. Show
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support. Get Started with Package Support Framework
In this articleThe 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. The Package Support Framework helps your application follow the best practices of the modern runtime environment. This article provides an indepth look at each component of Package Support Framework and step by step guide to using it. Understand what is inside a Package Support FrameworkThe Package Support Framework contains an executable, a runtime manager DLL, and a set of runtime fixes. Here is the process:
When users starts your application, the Package Support Framework launcher is the first executable that runs. It reads your configuration file and injects the runtime fixes and the runtime manager DLL into the application process. The runtime manager applies the fix when it's needed by the application to run inside of an MSIX container. Step 1: Identify packaged application compatibility issuesFirst, create a package for your application. Then, install it, run it, and observe its behavior. You might receive error messages that can help you identify a compatibility issue. You can also use Process Monitor to identify issues. Common issues relate to application assumptions regarding the working directory and program path permissions. Using Process Monitor to identify an issueProcess Monitor is a powerful utility for observing an app's file and registry operations, and their results. This can help you to understand application compatibility issues. After opening Process Monitor, add a filter (Filter > Filter…) to include only events from the application executable. A list of events will appear. For many of these events, the word SUCCESS will appear in the Result column. Optionally, you can filter events to only show only failures. If you suspect a filesystem access failure, search for failed events that are under either the System32/SysWOW64 or the package file path. Filters can also help here, too. Start at the bottom of this list and scroll upwards. Failures that appear at the bottom of this list have occurred most recently. 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. The PSFSample has two issues. You can see those issues in the list that appears in the following image. 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. It's unlikely that the application is trying to reference that path directly. 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. This suggests that the application is expecting its current working directory to be set to somewhere in the package. Looking inside of the appx, we can see that the file exists in the same directory as the executable. The second issue appears in the following image. In this issue, the application is failing to write a .log file to its package path. This would suggest that a file redirection fixup might help. Step 2: Find a runtime fixThe PSF contains runtime fixes that you can use right now, such as the file redirection fixup. File Redirection FixupYou 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. 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. Runtime fixes from the communityMake sure to review the community contributions to our GitHub page. It's possible that other developers have resolved an issue similar to yours and have shared a runtime fix. Step 3: Apply a runtime fixYou can apply an existing runtime fix with a few simple tools from the Windows SDK, and by following these steps.
Let's go through each task. Create the package layout folderIf 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. You 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
This will give you something that looks like the following. If you don't have a .msix (or .appx) file to start with, you can create the package folder and files from scratch. Get the Package Support Framework filesYou can get the PSF Nuget package by using the standalone Nuget command line tool or via Visual Studio. Get the package by using the command line toolInstall the Nuget command line tool from this location: https://www.nuget.org/downloads. Then, from the Nuget command line, run this command:
Alternatively, you can rename the package extension to .zip and unzip it. All the files you need will be under the /bin folder. Get the package by using Visual StudioIn Visual Studio, right-click your solution or project node and pick one of the Manage Nuget Packages commands. Search for Microsoft.PackageSupportFramework or PSF to find the package on Nuget.org. Then, install it. Add the Package Support Framework files to your packageAdd the required 32-bit and 64-bit PSF DLLs and executable files to the package directory. Use the following table as a guide. You'll also want to include any runtime fixes that you need. In our example, we need the file redirection runtime fix.
Your package content should now look something like this. Modify the package manifestOpen your package manifest in a text editor, and then set the
Create a configuration fileCreate a file name
Following is a guide for the config.json schema:
The Package and test the appNext, create a package.
Then, sign it.
For more information, see how to create a package signing certificate and how to sign a package using signtool Using PowerShell, install the package. Note Remember to uninstall the package first.
Run the application and observe the behavior with runtime fix applied. Repeat the diagnostic and packaging steps as necessary. Check whether the Package Support Framework is runningYou can check whether your runtime fix is running. A way to do this is to open Task Manager and click More details. Find the app that the package support framework was applied to and expand the app detail to veiw more details. You should be able to view that the Package Support Framework is running. Use the Trace FixupAn alternative technique to diagnosing packaged application compatibility issues is to use the Trace Fixup. This DLL is included with the PSF and provides a detailed diagnostic view of the app's behavior, similar to Process Monitor. It is specially designed to reveal application compatibility issues. 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.
By default, the Trace Fixup filters out failures that might be considered "expected". For example, applications might try to unconditionally delete a file without checking to see if it already exists, ignoring the result. 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. 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". This is a failure that is frequently observed and not generally assumed to be unexpected. 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. By default, the output from the Trace Fixup gets sent to the attached debugger. For this example, we aren't going to attach a debugger, and will instead use the DebugView program from SysInternals to view its output. After running the app, we can see the same failures as before, which would point us towards the same runtime fixes. Debug, extend, or create a runtime fixYou can use Visual Studio to debug a runtime fix, extend a runtime fix, or create one from scratch. You'll need to do these things to be successful.
When you're done, your solution will look something like this. Let's look at each project in this example.
To look at a complete sample that contains all of these types of projects, see PSFSample. Let's walk through the steps to create and configure each of these projects in your solution. Create a package solutionIf you don't already have a solution for your desktop application, create a new Blank Solution in Visual Studio. You may also want to add any application projects you have. Add a packaging projectIf you don't already have a Windows Application Packaging Project, create one and add it to your solution. For more information on Windows Application Packaging project, see Package your application by using Visual Studio. In Solution Explorer, right-click the packaging project, select Edit, and then add this to the bottom of the project file:
Add project for the runtime fixAdd a C++ Dynamic-Link Library (DLL) project to the solution. Right-click the that project, and then choose Properties. 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. Right-click that project, and then in the context menu, choose the Manage Nuget Packages option. Ensure that the Package source option is set to All or nuget.org. Click the settings icon next that field. Search for the PSF* Nuget package, and then install it for this project. 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. If you intend to create a brand new fix, don't add anything to this project just yet. We'll help you add the right files to this project later in this guide. For now, we'll continue setting up your solution. Add a project that starts the PSF Launcher executableAdd a C++ Empty Project project to the solution. Add the PSF Nuget package to this project by using the same guidance described in the previous section. Open the property pages for the project, and in the General settings page, set the Target Name
property to Add a project reference to the runtime fix project in your solution. Right-click the reference, and then in the Properties window, apply these values.
Configure the packaging projectIn the packaging project, right-click the Applications folder, and then choose Add Reference. Choose the PSF Launcher project and your desktop application project, and then choose the OK button. Note If you don't have the source code to your application, just choose the PSF Launcher project. We'll show you how to reference your executable when you create a configuration file. In the Applications node, right-click the PSF Launcher application, and then choose Set as Entry Point. Add a file named
Provide a value for each key. Use this table as a guide.
When you're done, your
Note The Debug a runtime fixIn Visual Studio, press F5 to start the debugger. The first thing that starts is the PSF Launcher application, which in turn, starts your target desktop 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. To permit the debugging of a .NET application with a native runtime fix DLL, select managed and native code types (mixed mode debugging). 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. 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. 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. As a result, it may not be possible to reproduce package path access denial errors prior to applying a runtime fix. To address this issue, use .msix / .appx package deployment rather than F5 loose file deployment. To create a .msix / .appx package file, use the MakeAppx utility from the Windows SDK, as described above. Or, from within Visual Studio, right-click your application project node and select Store -> Create App Packages. Another issue with Visual Studio is that it does not have built-in support for attaching to any child processes launched by the debugger. 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. To address this issue, use a debugger that supports child process attach. Note that it is generally not possible to attach a just-in-time (JIT) debugger to the target application. This is because most JIT techniques involve launching the debugger in place of the target app, via the ImageFileExecutionOptions registry key. This defeats the detouring mechanism used by PSFLauncher.exe to inject FixupRuntime.dll into the target app. WinDbg, included in the Debugging Tools for Windows, and obtained from the Windows SDK, supports child process attach. It also now supports directly launching and debugging a UWP app. To debug target application startup as a child process, start
At the
(execute until target application starts and breaks into the debugger)
(execute until the fixup DLL is loaded)
Note PLMDebug can be also used to attach a debugger to an app upon launch, and is also included in the Debugging Tools for Windows. However, it is more complex to use than the direct support now provided by WinDbg. SupportHave questions? Ask us on the Package Support Framework conversation space on the MSIX tech community site. FeedbackSubmit and view feedback for Which of the following task manager tabs on a Windows system is used to display the processes?The Users tab shows all the users logged in to the computer. In Windows 8, the Users tab also shows the processes that each user is running.
Which command can be used to eliminate the hard drive as the source of an application error?To eliminate the hard drive as the source of an application error, use the Chkdsk command with the /r parameter to check the drive and recover data in bad sectors.
Which of the following Windows tools is used to measure how well software and hardware are performing by displaying statistics in real time?Which of the following Windows tools is used to measure how well software and hardware are performing by displaying statistics in real time? A Microsoft Management Console snap-in that can track activity by hardware and software to measure performance.
Which of the following steps should the technician take first to determine whether startup processes are responsible for the slow startup?Which of the following steps should the technician take first to determine whether startup processes are responsible for the slow startup? The technician should measure the time it takes to start the system using a normal boot and compare that time against the time it takes for the system to perform a clean boot.
|