Skip to content
The Package Support Framework (PSF) is a kit for applying compatibility fixes to packaged desktop applications.
Branch: master
Clone or download
dhoehna Merge pull request #73 from microsoft/develop
Making sure the redirection directory is created upfront.
Check for Powershell only when the users wants to run a Powershell script.
Latest commit b92c66e Jun 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Detours Breaking Change: Renaming fraemwork to align with functionality Sep 25, 2018
PsfLauncher Merge pull request #72 from jaholme/master Jun 12, 2019
PsfRunDll Revert "Converting tabs to 4 spaces" Apr 8, 2019
PsfRuntime Fix assert and temporary change to config name Jun 4, 2019
PsfShimMonitor Updates Feb 21, 2019
fixups
include Merge pull request #72 from jaholme/master Jun 12, 2019
samples/PSFSample
tests Merging Master to the fork branch May 30, 2019
.gitignore Update for pre-release review Jul 5, 2018
Authoring.md Breaking Change: Renaming fraemwork to align with functionality Sep 25, 2018
CentennialFixups.sln Adding XSD. Apr 10, 2019
Common.Build.props Add MultiProcessorCompilation Nov 28, 2018
Common.props Reverting SDK back to RS1 May 14, 2019
Fixups.props Breaking Change: Renaming fraemwork to align with functionality Sep 25, 2018
LICENSE Initial commit Jun 7, 2018
MetadataSchema.xsd Removing unnecessary declerations Apr 11, 2019
Microsoft.PackageSupportFramework.nuspec Removing spacing Mar 25, 2019
Microsoft.PackageSupportFramework.targets Pointing PSFSample to newest NuGet package. Sep 26, 2018
README.md
SignConfig.xml Removing the trac to match with exe name Mar 8, 2019
buildall.cmd Adding Any CPU to the build Apr 9, 2019
layout.md Breaking Change: Renaming fraemwork to align with functionality Sep 25, 2018
readme.txt Breaking Change: Renaming fraemwork to align with functionality Sep 25, 2018
thirdparty.txt Update for pre-release review Jul 5, 2018

README.md

Package Support Framework

This project provides tools, libraries, documentation and samples for creating app-compat fixups to enable classic Win32 applications to be distributed and executed as packaged apps.

Documentation

Check out our step by step guide, it will walk you through the main PSF workflows and provides the key documentation.

See also:

License

Code licensed under the MIT License.

Branch structure

Package Support Framework adopts a development and master branching style.

Master

This branch represents the source in the most recent nuget package. The code in this branch is the most stable. Please do not fork off this branch for development.

Develop

This branch has the latest code. Keep in mind that there might be features in this branch that is not yet in master. Please make a private fork off this branch to make any contributions to Package Support Framework.

Contribute

This project welcomes contributions and suggestions. Most contributions 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.

Script support

PSF allows one PowerShell script to be run before an exe runs, and one PowerShell script to be ran after the exe runs.

Each exe defined in the application manifest can have their own scripts.

Prerequisite to allow scripts to run

In order to allow scripts to run you need to set the execution policy to unrestricted or RemoteSigned. The execution policy needs to be set for both the 64-bit powershell executable and the 32-bit powershell executable.

Here are the locations of each executable.

  • If on a 64-bit computer
    • 64-bit: %SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe
    • 32-bit: %SystemRoot%\SysWOW64\WindowsPowerShell\v1.0\powershell.exe
  • If on a 32-bit computer
    • 32-bit: %SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe

More information about PowerShell Execution Policy

Configuration changes

In order to specify what scripts will run for each packaged exe you will need to modify the config.json file. To tell PSF to run a script before the execution of the pacakged exe add an object called "startScript". To tell PSF to run a script after the packaged exe finishes add an object called "endScript". Both objects use the same three keys.

Key name Value type Required?
scriptPath string Yes
scriptArguments string No
runInVirtualEnvironment boolean No (defaults to true)

Key descriptions

  1. scriptPath: The path to the script including the name and extension. The Path starts from the root directory of the application.
  2. scriptArguments: Space delimited argument list. The format is the same for a PowerShell script call. This string gets appended to scriptPath to make a valid PowerShell.exe call.
  3. runInVirtualEnvironment: If the script should run in the same virtual environment that the packaged exe runs in.

Flow of PSF with scripts

Below is the flow of PSF with scripting support.
The flow from beginning to end is [Starting Script] -> [Monitor] -> [Packaged exe] -> [Ending script]

Visual representation of the flow

+------------+ Success, or  +-----------------+              +-----------------+
|  Starting  | Script error |   Monitor and   |   Success    |      Ending     |
|   Script   |------------->|   Packaged exe  |------------> |      Script     |
+------------+              +-----------------+              +-----------------+
     | Create                        | Create                         | Create
     | Process                       | Process                        | Process
     | Error                         | Error                          | Error
     V                               V                                V
+-------------+             +-----------------+   Create Process +----------------+
| Throw error |             |    Run ending   |       Error      |   Throw error  | 
|  and exit   |             |     script      |----------------->|    and exit.   |
+-------------+             +-----------------+                  +----------------+
                                    | 
                                    | Success
                                    |
                                    V
                             +--------------+
                             |  Throw error |
                             |   and exit   |
                             +--------------+

Sample configuration

Here is a sample configuration using two different exes.

    {
  "applications": [
    {
      "id": "Sample",
      "executable": "Sample.exe",
      "workingDirectory": "",
	  "startScript":
	  {
		"scriptPath": "RunMePlease.ps1",
		"scriptArguments": "ThisIsMe.txt",
		"runInVirtualEnvironment": true
	  },
	  "endScript":
	  {
		"scriptPath": "RunMeAfter.ps1",
		"scriptArguments": "ThisIsMe.txt"
	  }
    },
	{
      "id": "CPPSample",
      "executable": "CPPSample.exe",
      "workingDirectory": "",
	  "startScript":
	  {
		"scriptPath": "CPPStart.ps1",
		"scriptArguments": "ThisIsMe.txt",
		"runInVirtualEnvironment": true
	  },
	  "endScript":
	  {
		"scriptPath": "CPPEnd.ps1",
		"scriptArguments": "ThisIsMe.txt"
	  }
    }
  ],
  "processes": [
    ...(taken out for brevity)
  ]
}

Fixup Metadata

Each fixup and the PSF Launcher has a metadata file in xml format. Each file contains the following

  1. Version: The version of the PSF is in MAJOR.MINOR.PATCH format according to Sem Version 2
  2. Minimum Windows Platform the the minimum windows version required for the fixup or PSF Launcher.
  3. Description: Short description of the Fixup.
  4. WhenToUse: Heuristics on when you should apply the fixup.

Addtionally, we have the XSD for the metadata files. THe XSD is located in the solution folder.

Submit your own fixup(s) to the community:

  1. Create a private fork for yourself
  2. Make your changes in your private branch
  3. 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.
    //-------------------------------------------------------------------------------------------------------
  4. 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:

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.

Data/Telemetry

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.

You can’t perform that action at this time.