|
Context Menu Bridge
This plug-in provided command wraps a desired number of legacy IContextMenu handlers inside its own IExplorerCommand implementation to ensure the availability of your menu items at the top level of the new right-click menu, without your end-users having to go through the Show more options menu item.
Runtime Bridge Behavior
At runtime, the bridge created by this plug-in will faithfully replicate your native IContextMenu menu captions, including their shortcuts. It will also invoke your native IContextMenu menu actions, exactly as they would be invoked by your own IContextMenu interfaces.
Where your IContextMenu interfaces do not create any menus, nor will this bridge. Finally, this bridge will display its menu items only for the file (and folder) types that your native interface has been registered for.
Wrapping Multiple Menus
You may invoke this plug-in as many times as desired to create multiple top-level entries in the new context menu, one per each invocation.
Invoking the plug-in just once with a list of legacy IContextMenu CLSIDs is also fully supported. Such an invocation collates all your provided legacy menu items underneath a single, combined top-level menu item in the new context menu.
Limitations
While there are no internal limits in the bridge regarding the number of IContextMenu interfaces you may wrap, inherent limitations in IExplorerCommand may result in truncated menus. If you experience this issue, simply invoke this plug-in additional times, splitting the menus you are wrapping amongst your invocations.
The bridge will also automatically "flatten" any submenus found in your IContextMenu instances which are at or more than 2 levels deep, as IExplorerCommand does not support nesting more than one sublevel.
Requirements
You must normally install and register the COM servers for all your wrapped IContextMenu interfaces (together with any of their dependencies) on the target system, paying attention to platform architecture as follows:
- When installing on an edition of , register a 32 bit (x86) version of your COM server.
- When installing on an edition of , register a 64 bit (x64) version of your COM server.
This plug-in does not support bridging IContextMenu interfaces which have been natively implemented as binaries.
Build Time Plug-In Behavior
At build time, this plug-in creates the physical bridge files, together with the package necessary for their installation, as part of building your main setup.
It also code signs these assets automatically using your existing project code signing settings.
The deliverables thus produced by this plug-in shall be accessible at installation time, and need to be further processed as follows.
Bridge COM DLLs
Two bridge binaries (COM object DLLs) implementing IExplorerCommand are built. You must install the appropriate bridge binary matching your deployment architecture:
- When installing on an edition of , use: InstallAwareContextMenuBridgeARM64.dll
- When installing on an edition of , use: InstallAwareContextMenuBridgeAMD64.dll
Both DLLs are fully self-contained and have no additional dependencies. Only one DLL file is required per platform.
You may use the Copy/Move Local Files command at install time to install the appropriate edition of the DLL targeting your specific platform, renaming it to InstallAwareContextMenuBridge.dll irrespective of your target platform (thus removing any bitness from the DLL name).
InstallAware recommends you install the DLL inside a subfolder of the %LOCALAPPDATA% folder on the target system.
Bridge Installation Package
The plug-in also builds the sparse MSIX package which is necessary for the actual activation of the bridge, past the point of copying the physical bridge DLL file:
- InstallAwareContextMenuBridge.msix
This sparse MSIX package does not need to be copied (or otherwise cached) on the target system, but it must be installed using the (Un)Install Sparse MSIX Package plug-in command.
While installing your sparse MSIX package, you must also register the full path to the folder where you installed your bridge COM DLLs above. The (Un)Install Sparse MSIX Package plug-in command contains a field for this purpose as well.
Plug-In Parameters
Please populate the plug-in fields as described below.
Name (letters and numbers only)
Enter a unique name for your menu.
Especially if you are invoking this plug-in multiple times, each entry in this field must be unique.
GUID 1 - GUID 2 - GUID 3
Click the button to regenerate all three GUIDs at once, or paste your own GUIDs into each field.
The values in these fields must be unique for each unique menu bridge.
Default Menu Caption
Type the desired human readable default caption for your menu.
This caption will not be used if all of the IContextMenu instances you are bridging already have their own unified parent menu item, or when you are bridging a single menu item. In both cases, the native (parent) menu item caption will be used instead.
Variable to receive package uninstallation identifier
This plug-in builds a sparse MSIX package which needs to be removed as part of your main uninstallation using the (Un)Install Sparse MSIX Package plug-in provided command.
Enter a variable in this field to receive the versioned string you will need to pass verbatim in the field of the (Un)Install Sparse MSIX Package plug-in, at the time your bridge is being uninstalled (before or after Apply Uninstall in your setup script).
You may define a custom variable using the Set Variable command with the box checked for this field.
IContextMenu CLSIDs to Bridge
Enter all of the GUIDs for each of the IContextMenu instances you intend to wrap with this plug-in, one on each line. Ensure to include the curly braces for all of the GUIDs you enter in this field.
Press CTRL+ENTER to begin a new line for a new GUID representing a new IContextMenu instance.
Variable to receive runtime location of bridge
This plug-in builds a sparse MSIX package and two runtime bridge COM DLLs when your setup is compiled. These files will be accessible at installation time in a setup staging folder, ready for further processing.
Enter the name of the variable to receive the full path to this staging folder at runtime.
At the time your bridge is being installed (before or after Apply Install in your setup script), you must copy one of the COM DLLs found in this folder to its final destination on the target system, and also install the sparse MSIX package from this folder to activate the COM DLL you just copied.
Please see the section above for further details.
You may also refer to the application runtime script for the context menu bridge application runtime for an example implementation: First add the runtime to your project, then switch to the tab in the IDE, and open/review the include script SetupContextMenuBridge.mia from the Project Manager window.