This post provides a free MSIX Packaging tool for the Package Support Framework (PSF), and is hosted in the PowerShell Gallery.
Most of us already know that native MSIX has its limitations (at time of writing) in terms of compatibility with some applications. For example, once we package an application into MSIX format we may find that it has issues finding DLLs, or generates Access Denied warnings amongst other annoying things.
So the folks over at Microsoft created the Package Support Framework (PSF), which was later forked by the great Tim Mangan to include additional functionality. The PSF essentially comprises of an executable which acts as the “PSF launcher”, a bunch of associated DLLs that provide “fix-ups”, and a config.json file which tells the launcher what to fix!
How Does The Package Support Framework Work?
In simple terms, we redirect any problematic shortcuts to the PSF launcher instead of the original executable. The PSF launcher then reads the associated config.json file which tells it what to do in terms of which executable to launch (the original executable) and which fix-ups to apply at runtime.
Why AlkanePSF?
When I originally wrote this (over a year ago), injecting the PSF into an MSIX package manually was a bit laborious and fiddly to say the least. The official MSIX packaging tool GUI didn’t support PSF configurations at the time (if I recall), and amending JSON files is prone to human error. So I created this PowerShell module called AlkanePSF that makes life easy (or easier).
The advantages of this scripted approach are that:
- It doesn’t require the MSIX packager. You can extract, inject fix-ups, recompile and sign on-the-fly.
- It could be used as part of an automation pipeline to inject fixes into a bunch of packages on a file share, or perhaps at the end of an automated conversion batch.
- It supports Tim Mangan’s PSF (which includes fix-ups like the MFR fix-up), which the official MSIX packaging tool doesn’t natively support.
- It’s fast when making fix-up modifications and re-retesting packages.
Caveats
- Whilst it does support every fix-up type, it doesn’t support every single fix-up configuration.
Assumptions
- You’ve already packaged your MSIX, launched it and it doesn’t work.
- You might have run some process monitoring, and have an understanding of which fixups you might need to apply. Maybe read the Package Support Framework Overview first.
- You have a code signing certificate and a password.
- You have a basic understanding of fix-ups. If not, use the links below to understand the different types.
Available Cmdlets
Install-AlkanePSFPrerequisite – Installs Windows SDK/Microsoft PSF/Tim Mangan PSF.
New-AlkanePSFStagedPackage – Extracts/stages MSIX.
Add-AlkanePSFApplication – Adds an application from the AppxManifest.xml to “fix”. This must be called for any application that requires fixing.
Add-AlkanePSFFileRedirectionFixup – Adds a FileRedirectionFixup to the application.
Add-AlkanePSFRegLegacyFixup – Adds a RegLegacyFixup to the application.
Add-AlkanePSFEnvVarFixup – Adds a EnvVarFixup to the application.
Add-AlkanePSFDynamicLibraryFixup – Adds a DynamicLibraryFixup to the application.
Add-AlkanePSFMFRFixup – Adds a MFRFixup to the application (Tim Mangan only).
Add-AlkanePSFTraceFixup – Adds support for the trace module.
Add-AlkanePSFStartScript – Adds a StartScript.
Add-AlkanePSFEndScript – Adds an EndScript.
Set-AlkanePSF – Updates AppxManifest.xml, generates config.json.
New-AlkanePSFMSIX – Compiles and signs new MSIX.
Usage of Free MSIX Packaging Tool for the Package Support Framework
One day I’ll get around to documenting it properly. But until that day comes, there are three things to do:
- Copy the script below and paste it into a PowerShell ISE session.
- Update the variables inside the TODO1 section
- Add your own fixups – I’ve added lots of examples below, so remove what you don’t require and modify the rest.
cls
#********************************************
#********************************************
#START TODO1 : Define variables
#********************************************
#********************************************
#The version of AlkanePSF - always check for the latest version here: https://www.powershellgallery.com/packages/AlkanePSF/
$alkanePSFVersion = "2.0.8"
#Define path to input MSIX that needs fixing
$alkanePathToMSIX ="C:\Alkane\alkane.msix"
#Define path to output MSIX
$alkanePathToFixedMSIX ="C:\Alkane\alkane-fixed.msix"
#Define application architecture (32/64). This will define which PSF DLLs to copy.
$alkaneAppArchitecture = "32"
#Define path to code signing certificate
$alkanePathToCertificate = "C:\Alkane\alkanecertificate.pfx"
#Define password for code signing certificate (if your password contains $ you'll need to prefix with a backtick `$)
$alkaneCertificatePassword = "alkanepassword"
#Specify the name of Tim Mangan's zip release, listed here: https://github.com/TimMangan/MSIX-PackageSupportFramework
$alkaneTmZipName = "ZipRelease.zip-v2024-1-2.zip"
#********************************************
#********************************************
#END TODO1 : Define variables
#********************************************
#********************************************
#Checking if we need to install module
$foundModule = $false
get-module -Name AlkanePSF | foreach {
$version = [string]$_.Version
if ($version -ne $alkanePSFVersion) {
write-host "Removing AlkanePSF version $version"
$_ | Remove-Module -Force
} else {
$foundModule = $true
}
}
if (!($foundModule)) {
write-host "Installing AlkanePSF version $alkanePSFVersion"
Install-Module AlkanePSF -RequiredVersion $alkanePSFVersion -Force
}
#Import module
Import-Module AlkanePSF -RequiredVersion $alkanePSFVersion -Force
#Install prerequisites such as Windows SDK, MS PSF, TM PSF
Install-AlkanePSFPrerequisite -ForceReinstall $false
#Stage and extract our MSIX package so we can apply fixups
New-AlkanePSFStagedPackage
#********************************************
#********************************************
#START TODO2 : Define Fixups
#********************************************
#********************************************
#Add first app for PSF fix with working directory fixup and inPackageContext fixup
Add-AlkanePSFApplication -FixupApplicationId "SAMPLEAPP" -FixupWorkingDirectory "VFS\ProgramFilesX86\Alkane\" -FixupArguments @("-exampleargument") -FixupInPackageContext $true
Add-AlkanePSFTraceFixup -FixupApplicationId "SAMPLEAPP" -FixupTraceMethod "outputDebugString" -FixupWaitForDebugger $false -FixupTraceFunctionEntry $false -FixupTraceCallingModule $true -FixupIgnoreDllLoad $true -FixupTraceLevelProperty "default" -FixupTraceLevelValue "allFailures" -FixupBreakOnProperty "default" -FixupBreakOnValue "allFailures"
#Add env var fixups
Add-AlkanePSFEnvVarFixup -FixupApplicationId "SAMPLEAPP" -FixupVarName "alkaneenv1" -FixupVarValue "alkanevalue1" -FixupVarUseRegistry $true
Add-AlkanePSFEnvVarFixup -FixupApplicationId "SAMPLEAPP" -FixupVarName "alkaneenv2" -FixupVarValue "alkanevalue2" -FixupVarUseRegistry $true
#Add DLL fixups
Add-AlkanePSFDynamicLibraryFixup -FixupApplicationId "SAMPLEAPP" -FixupDllName "alkane1.dll" -FixupDllFilepath "VFS\Alkane\alkane1.dll"
Add-AlkanePSFDynamicLibraryFixup -FixupApplicationId "SAMPLEAPP" -FixupDllName "alkane2.dll" -FixupDllFilepath "VFS\Alkane\alkane2.dll"
#Add reg legacy fixups
Add-AlkanePSFRegLegacyFixup -FixupApplicationId "SAMPLEAPP" -FixupType "FakeDelete" -FixupHive "HKCU" -FixupAccess "FULL2RW" -FixupPatterns@(".+\.exe",".+\.dll")
Add-AlkanePSFRegLegacyFixup -FixupApplicationId "SAMPLEAPP" -FixupType "ModifyKeyAccess" -FixupHive "HKLM" -FixupAccess "Full2MaxAllowed" -FixupPatterns@(".+\.exe",".+\.dll")
#Add MFR fixups (only applies to Tim Mangan PSF)
Add-AlkanePSFMFRFixup -FixupApplicationId "SAMPLEAPP" -FixupType "overrideLocalRedirections" -FixupName "ThisPCDesktopFolder" -FixupMode "Disabled"
Add-AlkanePSFMFRFixup -FixupApplicationId "SAMPLEAPP" -FixupType "overrideLocalRedirections" -FixupName "Personal" -FixupMode "traditional"
#Add file redirection fixups
Add-AlkanePSFFileRedirectionFixup -FixupApplicationId "SAMPLEAPP" -FixupType "packageDriveRelative" -FixupBase "example3" -FixupPatterns @(".+\.log")
Add-AlkanePSFFileRedirectionFixup -FixupApplicationId "SAMPLEAPP" -FixupType "knownFolders" -FixupId "ProgramFilesX64" -FixupBase "example1" -FixupPatterns @(".+\.log")
Add-AlkanePSFFileRedirectionFixup -FixupApplicationId "SAMPLEAPP" -FixupType "packageRelative" -FixupBase "example2" -FixupPatterns @(".+\.log")
Add-AlkanePSFFileRedirectionFixup -FixupApplicationId "SAMPLEAPP" -FixupType "knownFolders" -FixupId "ProgramFilesX64" -FixupBase "example4" -FixupPatterns @(".+\.log")
Add-AlkanePSFFileRedirectionFixup -FixupApplicationId "SAMPLEAPP" -FixupType "packageDriveRelative" -FixupBase "example3" -FixupPatterns @(".+\.log")
#An example of applying dynamic file redirection fixups
$workFolder = (get-item $alkanePathToMSIX).Directory.FullName
$packageName = (get-item $alkanePathToMSIX).Basename
$stagingFolder = "$workFolder\$($packageName)_Staged"
$vfsFolder = "$stagingFolder\VFS"
#find unique directories containing log files
Get-ChildItem -Path $vfsFolder -Recurse -Include *.log | Select -ExpandProperty DirectoryName -Unique | foreach {
$fullPath = $_.Replace($vfsFolder,"VFS")
Add-AlkanePSFFileRedirectionFixup -FixupApplicationId "SAMPLEAPP" -FixupType "packageDriveRelative" -FixupBase $fullPath -FixupPatterns @(".+\.log")
}
#add scripts to run at start and end
Add-AlkanePSFStartScript -FixupApplicationId "SAMPLEAPP" -FixupScriptPath "VFS\ProgramFilesX86\Alkane\example.exe" -FixupScriptArguments @("-install","-allusers") -FixupRunInVirtualEnvironment $true -FixupShowWindow $true -FixupStopOnScriptError $false -FixupWaitForScriptToFinish $true -FixupTimeout 10
Add-AlkanePSFEndScript -FixupApplicationId "SAMPLEAPP" -FixupScriptPath "VFS\ProgramFilesX86\Alkane\example.exe" -FixupScriptArguments @("-install") -FixupRunInVirtualEnvironment $true -FixupShowWindow $true -FixupStopOnScriptError $false -FixupWaitForScriptToFinish $true -FixupTimeout 10
#********************************************
#********************************************
#END TODO2 : Define Fixups
#********************************************
#********************************************
#update AppxManifest.xml, generate config.json
Set-AlkanePSF -FixupPSFType "TM" -FixupOpenConfigJson $false
#Compile staged files into MSIX and sign
New-AlkanePSFMSIX
You can quickly tweak and regenerate your MSIX file to test modifications in a matter of seconds – just re-run the script!
Hint: If you want to view the config.json at the end of each compilation, set
-FixupOpenConfigJson $true
.
This is work in progress, so your feedback in the comments below is always welcome!