Export (0) Print
Expand All

Registering Shell Extension Handlers

A Shell extension handler object must be registered before the Shell can use it. This topic is a general discussion of how to register a Shell extension handler.

Any time you create or change a Shell extension handler, it is important to notify the system that you have made a change. Do so by calling SHChangeNotify, specifying the SHCNE_ASSOCCHANGED event. If you do not call SHChangeNotify, the change might not be recognized until the system is rebooted.

There are some additional factors that apply to Windows 2000 systems. For details, see the Registering Shell Extension Handlers on Windows 2000 Systems section.

As with all Component Object Model (COM) objects, you must create a GUID for the handler using a tool such as Guidgen.exe, which is provided with the Windows Software Development Kit (SDK). Create a subkey under HKEY_CLASSES_ROOT\CLSID whose name is the string form of that GUID. Because Shell extension handlers are in-process servers, you also must create an InprocServer32 subkey under that GUID subkey with the (Default) value set to the path of the handler's DLL. Use the apartment threading model. An example is shown here:

HKEY_CLASSES_ROOT
   CLSID
      {00021500-0000-0000-C000-000000000046}
         InprocServer32
            (Default) = %windir%\System32\Example.dll
            ThreadingModel = Apartment

Any time the Shell takes an action that can involve a Shell extension handler, it checks the appropriate registry subkey. The subkey under which an extension handler is registered controls when it will be called. For instance, it is a common practice to have a shortcut menu handler called when the Shell displays a shortcut menu for a member of a file type. In this case, the handler must be registered under the file type's ProgID subkey.

This topic discusses the following subjects:

Handler Names

To enable a Shell extension handler, create a subkey with the handler subkey name (see below) under the ShellEx subkey of either the ProgID (for file types) or the Shell object type name (for predefined_shell_objects).

For example, if you wanted to register a shortcut menu extension handler for MyProgram.1, you begin by creating the following subkey:

HKEY_CLASSES_ROOT
   MyProgram.1
      ShellEx
         ContextMenuHandlers

For the following handlers, create a subkey underneath the "Handler Subkey name" subkey named as the string version of the class identifier (CLSID) of the Shell extension. Multiple extensions can be registered under the handler subkey name by creating multiple subkeys.

HandlerInterfaceHandler Subkey Name
Column provider handlerIColumnProviderColumnHandlers
Shortcut menu handlerIContextMenuContextMenuHandlers
Copyhook handlerICopyHookCopyHookHandlers
Drag-and-drop handlerIContextMenuDragDropHandlers
Property sheet handlerIShellPropSheetExtPropertySheetHandlers

 

For the following handlers, the default value of the "Handler Subkey Name" key is the string version of the CLSID of the Shell extension. Only one extension can be registered for these handlers.

HandlerInterfaceHandler Subkey Name
Data handlerIDataObjectDataHandler
Drop handlerIDropTargetDropHandler
Icon handlerIExtractIconA/WIconHandler
Thumbnail image handlerIThumbnailProvider{E357FCCD-A995-4576-B01F-234630154E96}
Infotip handlerIQueryInfo{00021500-0000-0000-C000-000000000046}
Shell link (ANSI)IShellLinkA{000214EE-0000-0000-C000-000000000046}
Shell link (UNICODE)IShellLinkW{000214F9-0000-0000-C000-000000000046}
Structured storageIStorage{0000000B-0000-0000-C000-000000000046}
MetadataIPropertySetStoragePropertyHandler
Pin to Start MenuIStartMenuPinnedList{a2a9545d-a0c2-42b4-9708-a0b2badd77c8}
Pin to Taskbar{90AA3A4E-1CBA-4233-B8BB-535773D48449}

 

The subkeys specified to add Pin to Start Menu and Pin to Taskbar to an item's shortcut menu are only required for file types that include the IsShortCut entry.

Predefined Shell Objects

The Shell defines additional objects under HKEY_CLASSES_ROOT which can be extended in the same way as file types. For example, to add a property sheet handler for all files, you can register under the PropertySheetHandlers subkey.

HKEY_CLASSES_ROOT
   *
      shellex
         PropertySheetHandlers

The following table gives the various subkeys of HKEY_CLASSES_ROOT under which extension handlers can be registered. Note that many extension handlers cannot be registered under all of the listed subkeys. For further details, see the specific handler's documentation.

SubkeyDescriptionPossible Handlers
*All filesShortcut Menu, Property Sheet, Verbs (see below)
AllFileSystemObjectsAll files and file foldersShortcut Menu, Property Sheet, Verbs
FolderAll foldersShortcut Menu, Property Sheet, Verbs
DirectoryFile foldersShortcut Menu, Property Sheet, Verbs
Directory\BackgroundFile folder backgroundShortcut Menu only
DriveAll drives in MyComputer, such as "C:\"Shortcut Menu, Property Sheet, Verbs
NetworkEntire network (under My Network Places)Shortcut Menu, Property Sheet, Verbs
Network\Type\#All objects of type # (see below)Shortcut menu, Property Sheet, Verbs
NetShareAll network sharesShortcut menu, Property Sheet, Verbs
NetServerAll network serversShortcut menu, Property Sheet, Verbs
network_provider_nameAll objects provided by network provider "network_provider_name"Shortcut menu, Property Sheet, Verbs
PrintersAll printersShortcut Menu, Property Sheet
AudioCDAudio CD in CD driveVerbs only
DVDDVD drive (Windows 2000)Shortcut Menu, Property Sheet, Verbs

 

Notes

  • The file folder background shortcut menu is accessed by right-clicking within a file folder, but not over any of the folder's contents.
  • "Verbs" are special commands registered under HKEY_CLASSES_ROOT\Subkey\Shell\Verb.
  • For Network\Type\#, "#" is a network provider type code in decimal. The network provider type code is the high word of a network type. The list of network types is given in the Winnetwk.h header file (WNNC_NET_* values). For example, WNNC_NET_SHIVA is 0x00330000, so the corresponding type subkey would be HKEY_CLASSES_ROOT\Network\Type\51.
  • "network_provider_name" is a network provider name as specified by WNetGetProviderName, with the spaces converted into underscores. For example, if the Microsoft Networking network provider is installed, its provider name is "Microsoft Windows Network", and the corresponding network_provider_name is Microsoft_Windows_Network.

Example of an Extension Handler Registration

To enable a particular handler, create a subkey under the extension handler type subkey with the name of the handler. The Shell does not use the handler's name, but it must be different from all other names under that type subkey. Set the default value of the name subkey to the string form of the handler's GUID.

The following example illustrates registry entries that enable shortcut menu and property sheet extension handlers, using an example .myp file type.

HKEY_CLASSES_ROOT
   .myp
      (Default) = MyProgram.1
   CLSID
      {00000000-1111-2222-3333-444444444444}
         InProcServer32
            (Default) = C:\MyDir\MyCommand.dll
            ThreadingModel = Apartment
      {11111111-2222-3333-4444-555555555555}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet.dll
            ThreadingModel = Apartment
   MyProgram.1
      (Default) = MyProgram Application
      Shellex
         ContextMenuHandler
            MyCommand
               (Default) = {00000000-1111-2222-3333-444444444444}
         PropertySheetHandlers
            MyPropSheet
               (Default) = {11111111-2222-3333-4444-555555555555}

Registering Shell Extension Handlers

The registration procedure discussed in this section must be followed for all Windows systems. However, with later systems, an additional step might be necessary. Because these later versions of Windows are designed to be used in a managed environment, access to the registry could be administratively restricted, requiring a somewhat different approach to installation than described in the previous section.

Note  Setup programs should generally not write directly to the registry. Instead, setup should be accomplished with Windows Installer packages. These tools ensure that software runs well and provides access to capabilities such as per-user class registration.

Shell extension handlers run in the Shell process. Because it is a system process, the administrator of a system can limit Shell extension handlers to those on an approved list by setting the EnforceShellExtensionSecurity value of the Explorer key to 1 as shown here:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Policies
                  Explorer
                     EnforceShellExtensionSecurity = 1

To place a Shell extension handler on the approved list, create a REG_SZ value whose name is the string form of the handler's GUID under the Approved subkey.

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Shell Extensions
                  Approved

For example, the following example adds the MyCommand and MyPropSheet handlers to the approved list.

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Shell Extensions
                  Approved
                     {00000000-1111-2222-3333-444444444444} = MyCommand
                     {11111111-2222-3333-4444-555555555555} = MyPropSheet

The Shell does not use the value that is assigned to the GUID, but it should be set to make inspecting the registry easier.

Your setup application can add values to the Approved subkey only if the person installing the application has sufficient privileges. If the attempt to add an extension handler fails, you should inform the user that administrative privileges are required to fully install the application. If the handler is essential to the application, you should fail the setup and notify the user to contact an administrator.

Related topics

Initializing Shell Extension Handlers

 

 

Community Additions

ADD
Show:
© 2014 Microsoft