Fixup: DynamicLibraryFixup

The DynamicLibraryFixup allows for specifying dlls that should be loaded from specified locations, typically within the package.

Applications typically use the Windows API 'LoadLibrary' to load dlls into their process by using the name of the dll without information specifying the path to the dll. This API will use a variety of techniques to locate a dll with this name, including the working directory of the process, App Paths registration of per-application folders, and the folders contained in the Path variable. There is also a dynamic folder registration method available to .Net based applications.

This fixup will intercept the 'LoadLibrary' calls made by the application to first consult for registration of dll paths in the config.json file and loading them using the full path.

There are several reasons that an application running from inside a MSIX package might not find dlls where the original application had no such problem. This includes a difference in the application working directory, App Paths registration not being transferred to the AppXManifest, and changes to the Path environment variable not being transferred. This fixup provides a simple way to ensure that dlls in the package are located (potentially with less overhead than even the original application running outside of the container).

While this fixup was originally the only available solution to dlls not being found in the MSIX package outside of rewriting the application, since then extensions to the PSF and the MSIX AppXManifest have been added. The PsfLauncher has an expanded configuration that may be used to restore the working directory. More recently the AppXManifest extension uap6:LoaderSearchPathOverride can be used to define additional folders that will be used in the LoadLibrary call, although as this is applied at the package level, packages with multiple dlls with the same name and different bitness may still have issues and this extension is not available on older versions of Windows 10.

It is possible to specify the configuration of this fixup to address a single dll that is causing a problem, however it is reasonable for tooling that creates packages with the PSF to automatically find and add all dlls in the package into this configuration.

The configuration for this fixup includes a boolean field, forcePackageDllUse, that is used to determine if these paths should be checked from this configuration path before passing through the original call or after. The normal use is to set this directive to true.

The configuration for the fixup also has a list of the dlls in a field called called relativeDllPaths. Each member of that list has a name, filepath, and optional architecture field.

The matching of the name field is done as case insensitive, to match that of the LoadLibrary function. Know that in most cases, applications attempt the load without any folder information, so entries in the name field should normally not contain path information. Should the application include any path information, this will be ignored for the purpose of checking for a match.

Below is an example of a configuration which might be appropriate for a package that contains both 32 and 64 bit processes including a dll that is provided in 32 and 64 bit instances in different folders.

{
   "dll": "DynamicLibraryFixup.dll",
   "config": {
      "forcePackageDllUse": true,
      "relativeDllPaths": [
         {
            "name": "File1.dll",
            "filepath": "VFS\\ProgramFilesX64\\Vendor\\PrimaryApp\\File1.dll",
            "architecture": "x64"
         },
         {
            "name": "File1.dll",
            "filepath": "VFS\\ProgramFilesX64\\Vendor\\SecondaryApp\\File1.dll"
            "architecture": "x86"
         },
         {
            "name": "File2.dll",
            "filepath": "VFS\\ProgramFilesX64\\Vendor\\Common\\File2.dll"
            "architecture": "AnyCPU"
         },
         {
            "name": "file3.dll",
            "filepath": "VFS\\ProgramFilesX64\\Vendor\\lib\\File2.dll"
         },
         {
            "name": "vcruntime140d.dll",
            "filepath": "VFS\\SystemX64\\vcruntime140d.dll"
         },
         {
            "name": "ucrtbased.dll",
            "filepath": "VFS\\SystemX64\\ucrtbased.dll"
         }
      ]
   }
},

More Information

The configuration if further defined on the developer description for DynamicLibraryFixup page.