PsfLauncher

The PsfLauncher is an executable that is provided in the PSF to act as a wrapper for any containerized application entry-point that needs the PSF. The most common use of PsfLauncher is to act at the target of Start Menu items. The PsfLauncher uses configuration from the config.json file to know what to do, which will include what target application to actually launch inside the container.

PsfLauncher is more than just for those typical start menu entry-points. It is used for:

• Start Menu entry-points to exes in the package.
• Start Menu entry-points to exes not in the package but must run in the container for configuration and/or plug-ins.
• Start Menu entry-points to non exe targets, like scripts and documents and Web URLs.
• File Type Association entry-points.
• Protocol Handler entry-points.

32 and 64 Bit

PsfLauncher is available in both 32-bit and 64-bit varieties. The bitness of the application (Microsoft uses the overloaded term 'Architecture' for this) must match the bitness of the PsfLauncher used. This bitness rule also applies to all of the dlls (both PsfRuntime dll and Fixup dlls).

Only one Application entry in the AppXManifest per exe.

One of the limitations of the MSIX AppXManifest file is that you must have an independent Application element in the manifest for each entry-point, and no two Application elements can have the same exe. To make this work, we often make multiple copies of PsfLauncher in the package and give them different names. We recommend starting that name with the 'PsfLauncher' string to make debugging easier. Some tools just call them PsfLauncher1.exe, PsfLauncher2.exe, and so on.

High-level Overview of PsfLauncher.

The following drawing walks through the typical way that a traditional application is started from a Start Menu shortcut, and how it works with Psflauncher:

In the traditional application, the installer creates a shortcut (lnk file) and deposits into one of the start menu folders. In windows 10, this is detected and an entry in the Windows 10 Start Menu is added (along with other lnk files and entries from UAP/MSIX packages). This entry points to the target application and it is normally run outside of the container and/or PSF.

The bottom part of the image shows what happens when the app is containerized with the PSF.

The MSIX package will have an applicaiton entry-point that is added to the start menu. This will now point to a copy of the PsfLaunncher application. Then:

1. PsfLauncher automatically loads in PsfRuntime dll, and this dll finds and reads the Application section of the config.json file to find the matching entry for the name of our PsfLauncher file.
2. That configuration will cause the runtime to start the idenfied target application and
3. inject another copy of PsfRuntime into that new process.
4. The copy of PsfRuntime in the new process will also locate and read the config.json file, but in this case looking for a matching entry from the Process section of that file, and
5. The PsfRutime in that process will inject and configure any additional Fixup dlls defined in that Process configuration.

Identifying the correct Application in the config.json

The Applications section of the json identifies applications by matching to the Application Id field of an application in the AppXManifest file and not necessarily the actual name of the exe process. While other third party tooling may use different naming schemes for the creation of the Id field in the AppXManifest file, the Microsoft MSIX Packaging Tool uses a munging of the process name that you can see in this partial AppXManifest file:

<Package ...>
   ...
   <Applications>
    <Application Id="PSFLAUNCHEROne" Executable="PsfLauncher1.exe" EntryPoint="Windows.FullTrustApplication">
      <uap:VisualElements BackgroundColor="transparent" DisplayName="7-Zip File Manager" Square150x150Logo="Assets\SevenZFM-Square150x150Logo.png" Square44x44Logo="Assets\SevenZFM-Square44x44Logo.png" Description="7-Zip File Manager">
        <uap:DefaultTile Wide310x150Logo="Assets\SevenZFM-Wide310x150Logo.png" Square310x310Logo="Assets\SevenZFM-Square310x310Logo.png" Square71x71Logo="Assets\SevenZFM-Square71x71Logo.png" />
      </uap:VisualElements>
      ...
    </Application>
    <Application Id="PSFLAUNCHERTwo" Executable="PsfLauncher2.exe"  EntryPoint="Windows.FullTrustApplication">
      ...
    </Application
  </Applications>
</Package>

The config.json file for this package might have an applications section such as this:

"applications": [
    {
      "id": "PSFLAUNCHEROne",
      "executable": "VFS\\ProgramFilesX64\\7-Zip\\7zFM.exe",
      "arguments": "",
      "workingDirectory": "VFS\\ProgramFilesX64\\7-Zip"
    },
    {
      "id": "PSFLAUNCHERTwo",
      "executable": "VFS\\ProgramFilesX64\\7-Zip\\7-zip.chm",
      "arguments": "",
      "workingDirectory": ""
    }
  ],

Support for Process launch and Shell launch

Although Windows 10 Start Menu items may not be files, by using PsfLauncher we can use the shell launch method to get an appropriate client side application to open the file. This is shown in the previous json for PSFLAUNCHERTWO. When the launcher sees that the executable file is not an exe file, it will look up the default program for that file type on the end-user system. It will then use a technique to perform a shell launch and force the resulting program to run inside this container (if possible).