Debugging an MSIX is not such an easy task. The execution is happening in a container so it’s not that easy to find out why an application is crashing. There are many tools out there which can help you debug MSIX apps like Hover, MSIX Commander, Process Monitor, etc. With the first two tools you can jump into the container and perform your debugging from there, but Microsoft offers a quick and easy solution for this: Package Support Framework.
I’ve covered other articles where I described what you can do with Package Support Framework like Adding a PowerShell script to run at application startup, Adding shortcut arguments or Adding file redirections. In this article we are going to have a look on how you can use the Trace Fixup functionality of Package Support Framework to debug your MSIX application.
So let’s say I have an application with a single button:
Now when i click the “Create File” button, it crashes…why? To investigate this, we must do the following:
Get Package Support Framework
The simplest way (from my point of view) to get the PSF is to go through Nuget.
Navigate to this link and select “Direct Download”. Once Downloaded, extract the .nupkg with 7Zip or other archive tool.
That’s it, all the required files can be found in the bin folder.
Get DebugView
DebugView is an application that lets you monitor debug output on your local system, or any computer on the network that you can reach via TCP/IP. This will be the tool we are going to use to see what the TraceFixup will show during the debugging process.
The tool can be downloaded from the Microsoft Website here.
Add PSF into your MSIX
With all the PSF files downloaded, open up the package with MSIX Packaging tool.
The following files must be added in the ROOT of the package:
- PsfLauncher32.exe
- PsfLauncher64.exe
- PsfRunDll32.exe
- PsfRunDll64.exe
- PsfRuntime32.dll
- PsfRuntime64.dll
- TraceFixup32.dll
- TraceFixup64.dll
- WaitForDebuggerFixup32.dll
- WaitForDebuggerFixup64.dll
At the end, the package should look something like this:
Edit MSIX Manifest File
In the MSIX Packaging Tool from Microsoft, in the Package Information Tab (on the left) scroll down until you see “Manifest File” and click “Open File”.
This will open up the MSIX manifest file with Notepad.
In here, navigate to your “Applications” element and look for your “Application”. In this example, we have:
<Application Id="SAMPLEREDIRECT" Executable="VFS/AppVPackageDrive/Sample Redirect.exe" EntryPoint="Windows.FullTrustApplication">
This must be changed to open the PSFLauncher64.exe. We are using the 64 bit version of PSF Launcher because our application is 64 bit. In case you don’t know the application architecture, use the 32bit one and see if it works. If now, change it to the 64 bit.
In the end, it should look something like this:
<Application Id="SAMPLEREDIRECT" Executable="PsfLauncher64.exe" EntryPoint="Windows.FullTrustApplication">
Create and Add a Config.json file in the MSIX
Now that we got the PSF in our MSIX Package and we modified the App to start the PSF during launch, we need to create a config.json file. The config.json file is the one who tells the PSF what to do.
Remember we modified the target of our application to PSFLauncher64.exe right? We now need to tell PSF to run our Sample Redirect.exe, so the first thing we need to do in the config.json is define this. The config.json will initially look like this:
{
"applications": [
{
"id": "SAMPLEREDIRECT",
"executable": "VFS/AppVPackageDrive/Sample Redirect.exe"
}
]
}
Cool, now the Trace Fixup must be loaded as a final fixup for the application. To do this, we must do the following in our config.json file:
{
"applications": [
{
"id": "SAMPLEREDIRECT",
"executable": "VFS/AppVPackageDrive/Sample Redirect.exe"
}
],
"processes":[
{
"executable" : ".*",
"fixups":[
{
"dll": "TraceFixup.dll",
"config": {
"traceMethod": "outputDebugString",
"traceLevels": {
"default": "allFailures"
}
}
}
]
}
]
}
So what we did is tell PSF to run our executable, and for all the executables that are running from the package to load the TraceFixup.DLL.
Now, the TraceFixup has some configuration that you must consider. The trace method we are using in this case is outputDebugString is the default method for TraceFixup. You can also use printf or eventlog which Uses Event Trace for Windows to output events that may be consumed using PSFShimMonitor.
In terms of traceLevels, Microsoft recommends to start with default and only if you don’t find anything to set it to allFailures.In this case we are going to go with allFailures.
For more information about configuring the TraceFixup check out this link from Microsoft GIThub page.
Once the config.json is created, we must add it in the MSIX package at the root of the package:
Install and debug the application
Now that everything is set, we can finally start debugging. So first open up the installed application and then open up DebugView. When we click the Create File in our application, the DebugView automatically detected the issue. Now, because we said to use the allFailures, we must scroll a bit to see the issue. But in our case, it was because the app was not able to create a file:
The application was trying to create a file near the executable, called SAMPLEFILE.TXT. In MSIX, you don’t have rights to modify the installation directory, so in this case we must apply a file redirection fixup in order for our application to work.
Now, keep in mind that although it’s called TraceFixup, it doesn’t actually fix issues inside your MSIX package. This DLL only captures everything that is happening in the container and outputs errors based on the configuration. So it is up to you to investigate what is wrong and how you can fix it.
