While Microsoft created the initial open-source project for the Package Support Framework, they have neglected it for some time and seem disinterested in maintaining it, so this fork represents the lastest active branch.
This project provides tools, libraries, documentation and samples for creating runtime fixes (also called fixups) for compatibility issues that enable Windows desktop applications to be distributed and executed as MSIX packaged apps. This fork is directly used by the PsfTooling and TMEditX applications. Additionally, several other tool vendors are believed to look to this source as the basis their own private repositories.
The original fork for this project is a Microsoft project, and this project remains forked from the original, although this fork is now considered the up-to-date and managed source for the PSF and there is no longer any intent to create pull requests back into the Microsoft fork.
Here are some common examples where you can find the Package Support Framework (PSF) useful:
- Your app can't find some DLLs when launched. You may need to set your current working directory. You can learn about the required current working directory in the original shortcut before you converted to MSIX.
- The app writes to the install folder. This issue typically shows up as ACCESS DENIED errors in Process Monitor as demonstrated in the following image.
- Your app needs to pass arguments to the executable when launched. You can easily configure arguments by using PSF Launcher.
You can learn more about how to identify compatibility issues here. If you have feedback, please create an issue or post a message in our tech community.
See these articles for core documentation about using the Package Support Framework:
- Apply runtime fixes by using the Package Support Framework: This article provides step-by-step instructions for the main Package Support Framework workflows.
- Run scripts with the Package Support Framework: This article demonstrates how to run scripts to customize an application dynamically to the user's environment after it is packaged using MSIX.
The following additional resources provide additional information about specific scenarios:
- Package Support Framework package layout
- Package Support Framework NuGet package install
- Instructions for authoring your own fixup DLL
If you wish to build the PSF from source, you will need to install the Windows Driver Kit (WDK) in order to build the MfrFixup.
Look for a versioned folder in the Develop branch code starting with "ZipRelease-v" that will contain pre-built release and debug builds of the PSF in a zip format. We are unable to use the GitHub "release" mechanism without breaking your ability to compare sources here to the original Microsoft sources.
The older Microsoft builds for the Package Support Framework binaries from Nuget.org. To extract the binaries, rename the package extension to .zip, unzip the file, and locate the binaries in the /bin folder. In a future release we are planning to make it easier to locate the binaries directly on GitHub.
The original Microsoft Package Support Framework adopted a develop and master branching style. In this TimMangan fork, the develop develop branch acts like the master and other branches are childs of develop.
The master branch represents the Microsoft Master source in the most recent NuGet package. The code in this branch is old. Do not use.
The develop branch has the latest Release code. Make a private fork off the develop branch to make your own contributions to Package Support Framework.
Each fixup and the PSF Launcher has a metadata file in XML format, which is used for some of the automated testing. Each file contains the following:
Version: The version of the Package Support Framework is in MAJOR.MINOR.PATCH format according to Sem Version 2.MinimumWindowsPlatform: The minimum windows version required for the fixup or PSF Launcher.Description: A short description of the fixup.WhenToUse: Heuristics on when you should apply the fixup.
The metadata file schema is provided here.
The Package Support Framework includes telemetry that collects usage data and sends it to Microsoft to help improve their products and services. Read Microsoft's privacy statement to learn more. However, data will be collected only when both of the following conditions are met:
- The Package Support Framework binaries are used from the NuGet package on a Windows 10 computer.
- The user has enabled collection of data on the computer.
The NuGet package contains signed binaries and will collect usage data from the computer. Telemetry is not collected when the binaries are built locally by cloning the repo or downloading the binaries directly. This means that while telemetry code is present in the binaries in the ZipRelease folder, it isn't active if you include those binaries in your MSIX packages.
The Package Support Framework code is licensed under the MIT License.
This project welcomes contributions and suggestions. Contributions to the Microsoft branch require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
For contributing to the TimMangan fork, contact Tim as tmangan@tmurgent.com
Submit your own fixup(s) to the community:
- Create a private fork for yourself
- Make your changes in your private branch
- For new files that you are adding include the following Copyright statement.
//-------------------------------------------------------------------------------------------------------
// Copyright (c) #YOUR NAME#. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
//------------------------------------------------------------------------------------------------------- - Create a pull request into 'fork:Microsoft/MSIX-PackageSupportFramework' 'base:develop'
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
Here is how you can contribute to the Package Support Framework:
- Submit bugs and help us verify fixes.
- Submit pull requests for bug fixes and features and discuss existing proposals.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Before making a pull request please run the regression tests to make sure your changes did not break existing behavior.
Please head to the tests solution and follow the instructions inside readme.md for details on how to run these automated tests.
Each fixup and the PSF Launcher has a metadata file in xml format. Each file contains the following
- Version: The version of the PSF is in MAJOR.MINOR.PATCH format according to Sem Version 2
- Minimum Windows Platform the the minimum windows version required for the fixup or PSF Launcher.
- Description: Short description of the fixup.
- WhenToUse: Heuristics on when you should apply the fixup.
Additionally, we have the XSD for the metadata files located in the solutions folder.
Scripting support is allowed on RS2 and higher builds of windows. If PSf is executed on RS1, scripts will not execute even if they are specified in the configuration file.
PSF allows you to write the configuration file in either json or xml. Configuration files written in xml need to be translated to json before psf can use them.
Because PSF uses json files for the configuration you will need to convert the xml configuration file to json.
To convert an xml configuration to json please use msxsl.exe located in the xmlToJsonConverter folder to convert your xml configuration to json. Here is an example command.
msxsl.exe [location of your xml file] -format.xsl -o config.json
Telemetry datapoint has been hooked to collect usage data and sends it to Microsoft to help improve our products and services. Read Microsoft's privacy statement to learn more. However, data will be collected only when the PSF binaries are used from Nuget package on Windows 10 devices and only if users have enabled collection of data. The Nuget package has binaries signed and will collect usage data from machine. When the binaries are built locally by cloning the repo or downloading the bits, then telemetry is not collected.