Introduction to Package Support Framework

To help with the MSIX transition, Microsoft has released the Package Support Framework (PSF) - an open-source framework that enables you to apply runtime fixups for issues that might appear when migrating legacy applications that you don’t have the source code for.


If you have been looking for a secure way to migrate legacy applications to Windows 10 without accessing the source code, you will find this article quite helpful.

Inside the Package Support Framework (PSF)

Under the hood, the Package Support Framework uses the Detours technology, an open-source framework for handling API redirection and hooking. Aside from allowing you to move forward in instances when you can't access the source code, this technology will also help smarten up your application.

As you will probably find out, with this framework, you can either choose to use predefined fixups or create a new fixup yourself. In this article, we will focus on how to use a predefined fixup.

The official Microsoft release for the Package Support Framework is available on Github. But, to start using PSF inside your MSIX package, you don’t need the entire Github repository.

The main resources that must be included into the MSIX (next to your application binaries) are:

  • the runtime fixups DLL(s) - predefined or any custom ones you might build
  • a config JSON - specifies and configures the fixups used by your application
  • an executable - aka the launcher, it reads the config file and injects the manager and fixups into your main application process
  • the PSF runtimes - these should be included depending on your application’s architecture



PSF resources from an extracted sample MSIX package


To align with the official release from Microsoft, the PSF support from Advanced Installer includes various enhancements. Here are the major improvements you can find:

  • Advanced Installer provides a single-click debugging experience that can automatically trace your application and suggest fixups. (see the video from the next section)

  • The PSF launcher (AiStub.exe) included by Advanced Installer also handles additional tasks not supported by default inside an MSIX package (eg. shortcut switches, Copy-on-Write for AppData, running PS scripts, etc..)

  • We added additional predefined fixups, as visible in the AppCompat page.

  • We now generate the config JSON automatically, based on the configurations from our GUI.

NoteThe PSF integration from Advanced Installer dramatically decreases your packaging time (making it up to 400% faster) and also increases the quality of your package.


If you are looking for a free alternative tool to help you leverage the PSF within your MSIX package, without having to do everything manually ( in the case you’re using only the MSIX Packaging Tool), we recommend you check out PsfTooling , built by Tim Mangan.

Using the Package Support Framework

Determining what fixups your application requires can be a very time-consuming process.

Although Microsoft offers the Package Support Framework as an open-source kit on its GitHub page, they do not provide any additional tools to make it easy to integrate it into your packaging and debugging workflow.

This means that you will have to invest a lot of time to track your app’s compatibility issues. To do that, you have the option of using Microsoft’s tracing DLL from the repository or tools like Process Monitor and DebugView. Then, depending on your needs, you may have to create/code your own fixup, if the few predefined fixups provided in the repository are not what you're looking for.

To write your own fixups, review Microsoft’s documentation about this topic.

To simplify and speed up this process, Advanced Installer has a built-in debugger that traces your app and tells you what fixups are required. As mentioned above, it also offers additional built-in fixups on top of the standard ones from Microsoft.

In our first Ignite talk about MSIX, you can see a demo of our Package Support Framework integration with Advanced Installer.



Depending on the app’s specifications, there might be new scenarios for which we do not provide a predefined fixup. Please contact us (it does not matter if you are using the free Express edition or one of our paid versions) through email at support at advancedinstaller dot com and we’ll analyze your problem and try to provide a fixup.


How Fixups Work

Fixups are written in C++. The resulting DLLs hook into your application when launched, and redirect its API calls. These DLLs need to be included in the MSIX package next to your application binaries and other PSF resources, as mentioned previously in this article.

The executable inside the Package Support Framework (PSF) becomes the entry point in your package. Basically, this executable is the first code that gets executed every time your application gets launched.


A sequence of steps executed when an application is launched


As pictured above, the PSF launcher will first load the correspondent runtime manager DLL and the configured fixups and then, it launches your main app. Meanwhile, it is injecting the fixups into the main application process, based on the configuration specified in the config.json file.

For example, when an application is trying to write in its installation folder (an action forbidden by the MSIX standard), the runtime fixups redirect the call to a new location under AppData. (check the video above to see this example in action)


Predefined Fixups

The Package Support Framework contains several predefined fixups but also gives you the option of creating custom fixups depending on your needs.

Advanced Installer offers support for multiple predefined fixups which can be quickly configured and integrated into your installer by using the Trace App functionality.

  • File Redirection
  • WorkingDirectory
  • Loading Static HTML files from your package
  • Command-line arguments management
  • Custom PowerShell scripts


Inspecting Fixups

Do you want to know if a package uses PSF fixups? Here are a couple of options to inspect it.

The first one is simple, extract the MSIX package using 7-Zip or a similar tool. In the package contents, you should notice the PSF-specific resources that you can see on the first image of this article.

To understand the exact configuration of the fixups, if present, open the config.json file. For example, the JSON file that configures the file redirection for all files with the extension “.log” will look like the one below.


A sample configuration JSON file


Another useful tool for inspecting fixups is MSIX Hero. This free application informs you about any PSF fixups present in the package. Here is how it looks inspecting the same MSIX package.


The same sample configuration file - interpreted by MSIX Hero

Video Tutorial

Conclusion

Although Microsoft introduced PSF to help the enterprises overcome the issues that might appear when migrating legacy applications, the implementing process can be quite overwhelming.And as we could see in this article, one of the best ways to make your life easier is to have an integrated tool with predefined fixups added.

If you have more questions about the Package Support Framework leave us a comment below or join the Microsoft PSF-dedicated community.

Comments: