Fixup: PsfTraceFixup

PsfTraceFixup is a dll that may be injected into an application process for the purpose of debug tracing of certain Windows API calls. This fixup is used in the absence of other fixups as it targets those intercept APIs those fixups use.

The Fixup target (most) all of the APIs used by fixups like the FileRedirectionFixup and RegLegacyFixup in order to show the requests made by the application and result coming out of the API when running into the container. The intent is to understand what the application is actually requesting, prior to any interference by the MSIX Runtime, and what isn't working. With this information it becomes possible to target those issues with the regular fixups.

Adding the PSF with PsfTraceFixup is one option for such debugging, but alternative methods also exist:

• Process Monitor - adds coverage to additional Windows API calls whether there are existing PsfFixups or not, but captures below the MSIX Runtime
• "API Spy" tools - a generic name for more general-purpose 3rd-party tools that monitor Windows API calls.

PsfTraceFixup provides for some small control over what will be monitored, but generally you request the full capabilities. The results may be output in one of three ways, which is controlled in the config.json file in a PsfTraceFixup configuration field called traceMethod:

1. outputDebugString - The tool can emit output to the Windows Debug Port. Debugger tools like SysInternals DebugView can monitor and capture this output. This mode is extremely verbose, with a single API call resulting in up to 20 lines of text. While great if you already know what you are looking for, it makes this mode difficult to use for general diagnosis of an unknown problem.
2. printf - The tool can emit output to the application process stdout port. This output is the same as outputDebugString mode.
3. eventLog - The tool can emit output to a special Event Log using Event Tracing for Windows. In this mode, a single event will capture a single API call. In addition to using the Windows Event Viewer to view the emitted events, the PSF also has a special purpose GUI viewer called PsfMonitor that provides a user interface that mimics that of Process Monitor. This mode is the default and recommended mode as it consolidates event output and does a good job of separating inputs from the application call from output results of the call.

While PsfTraceFixup has a number of additional configuration controls on what to trace and controls for working with a code debugger, we generally use a defaulted configuration for the process section of the config.json file for this dll that just logs everything into the eventlog:

{
    "dll": "TraceFixup.dll",
    "config": {
        "traceMethod": "eventlog",
        "traceLevels": {
            "default": "allFailures"
        }
    }
}

Dependencies

PsfTraceFixup and PsfMonitor have several dependent dlls that are required to also be part of the package.

More Information

More information on PsfTrace may be found in the PsfTraceFixup Developer Documentation page.