Config.JSON and Config.XML

The Package Support Framework uses the Config.Json file inside the package in order to configure the Psflauncher and Fixup components.

The choice of using json inside the package appears to have nothing to do with traditional json usages. There are no web servers or rest interfaces in use. It is just a structured file with configuration items and values.

One important rule you must follow in json is that item names (not values) are always in camelCase, which means it starts with a lowercase letter and uses an uppercase letter only when it would be a new word if spoken out loud (e.g. “workingDirectory”).

The config files make a heavy use of RegEx in the configuration values. RegEx is a pattern matching syntax, that instructs the reader to use a configured value string as a pattern to match against. The RegEx syntax is different from the pattern matching syntax used by the Windows command processor. If you need to further understand the RegEx syntax, you can start with the information available here and look for the Ecml variation of RegEx.

In addition to the Json format, Microsoft defines an xml version of the file that may be used externally by tools responsible for producing the package. Those tools would transform the xml format into Json as part of the packaging process. To many, xml may be a better choice as it is self describing and makes it easier to implement validators against a schema. This is the main reason Microsoft specifically defined it to be used by these tools, even if the PSF doesn’t use this form itself.

The config file format consists of two major sections, Applications and Processes:

Config Applications Section

The Applications section is used to configure the launcher. The launcher is usually configured elsewhere to become the target of an entry point into the container. Generally, we consider this the replacement target of a shortcut, but it can also be the target of other modified registrations in the AppXManifest, such as file type associations or URL protocol handlers.

The Applications section consists of an array of application items.

The identification of the application is performed by matching the name of the launcher process against the id field of the application item “id".

When using the Microsoft MSIX Packaging Tool with PsfTooling to add the PsfLauncher as defined on GitHub, the launcher uses an undocumented algorithm against the process name to perform this comparison. Generally speaking, it drops the “.exe”, turns it into uppercase, and changes any numeric character into the alphabetic English language equivalent (in Pascal Case). For example, the process name “PsfLauncher1.exe” would match the id “PSFLAUNCHEROne”.

When there is a match found, the rest of the fields of the application item will be implemented by the launcher process.

This includes the following items:

• monitor - An item with subitems to specify a monitor program, like PsfMonitor, to launch first.
• scripts - An item with subitems to specify a start script to run before launching the target application, and an end script to run when the target application ends.
• executable - The package relative path to the ultimate target application file. This may be an .exe file, but any other file type that has a local file type association may be used.
• workingDirectory - A full or package relative folder to use as the working directory for the ultimate target application. If specified as an empty string, it will use the path containing the target application.
• arguments - Additional command line arguments to be appended to the command line when launching the ultimate target application.

Config Processes Section

The Applications section is used to configure PSF Fixups on a per-process basis. The section consists of an array of process entries, with two subitems:

• executable - The value is a RegEx pattern string to match against process names.
• fixups - The value is an array of fixups. Each fixup has additional subitems:
  • dll - The value of this item is the name (without path) of the dll fixup to be injected. If not found by that name, it will attempt to add a 32 or 64 (depending on the bitness of the running process) to the base name and try again. Thus “FileRedirectionFixup.dll” can match “FileRedirectionFixup64.dll”.
  • Config - The value is a collection of further subitems, dependent on the needs of the particular fixup.

The best way to begin to understand the syntax further might be to look at some example config files of existing packages.