Verbs and File Associations

  • Article

File associations use verbs as shorthand for actions that are invoked on items in the Shell namespace, including files and folders. Verbs are closely related to the Shell shortcut menus, where each menu item is associated with a verb. IContextMenu and ShellExecute support canonical names for verbs; canonical verb names remain constant regardless of platform or language, which makes it possible for developers to invoke known canonical verbs without knowing the details about a Shell namespace item. For example, ShellExecute can invoke the Print verb on a Microsoft Word document, which requests that the installed handler print the document, without knowing whether Word, Microsoft WordPad, or some other application does the printing.

  • Standard Canonical Verbs and Their Behaviors
  • How the Shell Invokes Verbs
  • Supplemental Verbs
  • Static vs. Dynamic Verbs
  • Registering Verbs for Backward Compatibility
  • Related Topics

Standard Canonical Verbs and Their Behaviors

A file association generally has a preferred action that is taken when the user double-clicks a file of this type. This preferred action is linked to a verb referred to as the primary verb. The primary verb is specified by the default value of the shell key, or the open key if the shell key has no default value. The most common primary verb is open. However, in media files, the most common primary verb is play. The primary verb is also referred to as the default verb.

Some common standard canonical verbs and their expected behaviors are listed below.

  • open. A typical primary verb that launches the associated application and uses it to open the invoked file.
  • opennew. Equivalent to open, but launches the content in a new window.
  • openas. Presents a dialog that allows the user to choose an application with which to open the file.
  • edit. Works the same way as open, but typically enables the user to edit the contents of the file.
  • play. Similar to open, but is typically invoked on media file types. This verb indicates that the associated application immediately begin, playing the contents of the file, rather than just opening the file and waiting for user direction.
  • print. The application prints the contents of the file and exits, displaying as little as necessary to complete the task.
  • preview. A quick, simple response that allows the user to rapidly preview and dismiss items.

The Shell also supports special verbs. The Shell uses these verbs, but generally they do not appear in shortcut menus. Some of the special verbs are listed here.

  • printto. Used by the Shell to support drag-and-drop to printers.
  • runas. Used by the Shell to expose the contents of a file in the context of a specific user. The Shell uses this verb to give the user a higher level of system privileges while executing a certain task.

How the Shell Invokes Verbs

There are three ways that the Shell can invoke a verb.

  • Through COM and IDropTarget, by using a DropTarget key. This is the preferred method for Microsoft Windows XP and later systems.
  • As a command line call, as specified in a command key.
  • Through Dynamic Data Exchange (DDE), by using a ddeexec key.

Invoking a verb can launch the application specified by the verb's command subkey using CreateProcess. However, command-line verbs are limited by the maximum command-line length, so they are not useful for invoking verbs on multiple items. Command-line verbs are also restricted to working with items that can be represented as a string, such as a file system path.

Applications are responsible for implementing single-instance or multiple-instance support, potentially connecting a new instance of the process with an already running instance.

If your application supports DDE, you can have the Shell initiate a DDE conversation instead of launching a command line.

Note  The DDE method is being deprecated; use the DropTarget method instead. The DropTarget method is more robust and has better activation support since it uses Component Object Model (COM) activation of the handler. In the case of multiple item selection, it is not subject to the buffer size restrictions found in both DDE and CreateProcess. Also, items are passed to the application as a data object that can be converted to an item array by using SHCreateShellItemArrayFromDataObject. This provides an easier programming model for the items and does not lose namespace information as happens when the item is converted to a path for command-line or DDE protocols.

To specify that invoking a verb should initiate a DDE conversation, add a ddeexec subkey to the verb's key. Set the default value of ddeexec to the DDE command string that is sent with the WM_DDE_EXECUTE message. The ddeexec key has these optional subkeys that provide some control over the DDE process.

  • application. Set the default value of this subkey to the application name to be used to establish the DDE conversation. When the Shell calls DdeConnect to establish the DDE connection, a handle to this string is passed in the hszService parameter. If there is no application subkey, the default value of the verb's command subkey is used as the application name.

  • topic. Set the default value of this subkey to the topic name of the DDE conversation. When the Shell calls DdeConnect to establish the DDE connection, a handle to this string is passed in the hszTopic parameter. If there is no topic subkey, System is used as the topic name.

  • ifexec. Set the default value of this subkey to the DDE command to be used if DDE conversation cannot be initiated. When initiation fails, the application specified by the default value of the verb's command subkey is launched. If an ifexec key exists, its default value will then be used as the DDE command. If there is no ifexec subkey, the default value of the ddeexec key is used again as the DDE command.

  • windowclassname. Windows Vista or later. The class name of the window in which the Shell establishes a DDE connection. This limits the Shell to querying only this class of window rather than all classes, improving performance.

    This class or class atom is registered through an earlier call to RegisterClass or RegisterClassEx. The atom must be in the low-order word of the class name; the high-order word must be zero. If the data associated with this subkey is a string, it specifies the window class name, which can be any registered name or any of the predefined control-class names.

  • windowname. Windows Vista or later. The name (title) of the window in which the Shell will establish a DDE connection. This limits the Shell to querying only this particular DDE window rather than all windows, improving performance.

The following example specifies that invoking the open verb for MyProgram.1 initiates a DDE conversation with a DDE command of Open("%1") and an application name of MyProgram.

Note  In this and subsequent registry examples in this topic, we use HKEY_CLASSES_ROOT . It is also possible to register a verb per-user or per-machine.

  • For a per-user registration, substitute HKEY_CURRENT_USER\Software\Classes for HKEY_CLASSES_ROOT.
  • For a per-machine registration, substitute HKEY_LOCAL_MACHINE\Software\Classes for HKEY_CLASSES_ROOT.

HKEY_CLASSES_ROOT

MyProgram.1

(Default) = MyProgram

shell

edit

  • command

open

  • command
  • ddeexec

On Windows XP and later systems, enhanced support is added for applications that implement drag-and-drop features and expose their IDropTarget interface. With this method, the Shell communicates with the application through the COM subsystem. This method offers a significant performance gain over both the command line method and DDE. This method leverages an application's existing drop target implementation (if one exists), making it easy for applications that already support drag-and-drop through an IDropTarget implementation on their top level window to map that functionality into a verb that ise presented in the explorer.

To use this method, add a DropTarget subkey under a verb's key. Under DropTarget , add a registry string named Clsid and set the value of this string to a valid CLSID Key. For example:

HKEY_CLASSES_ROOT

Paint.Picture

shell

open

  • command
  • DropTarget

printto

  • command

The CLSID for a DropTarget is defined normally, in this case:

HKEY_CLASSES_ROOT

CLSID

{E84FDA7C-1D6A-45F6-B725-CB260C236066}

  • InProcServer32

In the example, only an in-process server is defined, but a class identifier (CLSID) referred to in a DropTarget subkey can specify a local server (LocalServer32), an in-process server (InprocServer32), or both. Local server is the preferred option. By using a local server, it allows the execution of the verb to be easily remoted into a process separate from Windows Explorer, which improves robustness and security.

The DropTarget subkey takes precedence over both the ddeexec and command keys. On systems earlier than Windows XP, the DropTarget key is ignored.

Implementations of IDropTarget::Drop need to return quickly to the caller avoid causing an unresponsive state. There are two ways to accomplish this:

  1. Marshall the input IDropTarget to a new thread.
  2. Take a reference to the data object, set a short timer, and process the drop against that timer. If you use this method, you must ensure that you do not begin processing a second drop while the first is still being processed.

DropTarget verbs are registered statically to provide a better user experience. The alternative, an IContextMenu handler, can cause a delay in the display of a context menu if the handler is poorly implemented.

Supplemental Verbs

Supplemental verbs are any verbs other than the standard canonical verbs, and are most often used to add custom behavior beyond what the default system verbs provide. On Windows XP or later, you can add supplemental verbs to the SystemFileAssociations extension, or to the Shell subkey for the PerceivedType key.

For example, suppose MyTextEditor is a text editor and the developers of MyTextEditor want to add a supplemental verb that displays "Edit with MyTextEditor" when you right-click any file of the perceived type "text." To accomplish this, a key named edit.MyTextEditor is added to the registry as follows:

HKEY_CLASSES_ROOT

SystemFileAssociations

text

shell

edit

  • command

open

  • command

edit.MyTextEditor

(Default) = Edit with MyTextEditor

  • command

The file name is passed as %1. After the edit.MyTextEditor key is added, the shortcut menu displays the new choice for any file belonging to the PerceivedType text as follows:

Supplemental Verb in the Context Menu

Note  Using supplemental verbs on Windows versions earlier than Windows XP is not supported and is not recommended.

Static vs. Dynamic Verbs

The registry typically stores verbs and the Shell uses them to invoke certain actions. These verbs are referred to as static because they vary based on the current selection, that is, they are unconditionally present and have no state. The Shell implements IContextMenu for applications when they register static verbs under the appropriate registry keys. For example, a typical ProgID entry for the file .txt file is as follows:

HKEY_CLASSES_ROOT

txtfile

  • DefaultIcon

Shell

Open

  • Command

Print

  • Command

PrintTo

  • Command

Three static verbs are registered in this ProgID: open, print, and printto. When the user brings up a shortcut menu on this file type, open and print appear in the shortcut menu, while printto does not because it is a special system verb. If the user selects either open or print from the shortcut menu, the command stored in the corresponding command key executes. In this example, %1 represents the file name and %2 the printer name. The %3 and %4 arguments appear for legacy reasons, and represent the driver name and the port name on systems running Windows 3.1. These parameters are not used on systems running Windows 95 or later.

Verbs that you implement using a custom IContextMenu rather than the registry are called dynamic verbs. In some cases, you might want more capabilities than static verbs allow. For example, you might want to present a more dynamic user interface (UI), which requires verbs to have a state, or for verbs to be available only under certain conditions. You can do this by implementing an IContextMenu Shell extension rather than registering static verbs.

Registering Verbs for Backward Compatibility

Some applications may search the registry for verb keys that are no longer used. For that purpose, those keys can be left in the registry with the addition of the LegacyDisable value to the verb's key, which tells the system that the verb is not an actual verb, but exists solely for the purpose of backward compatibility.

Use of the LegacyDisable value is shown here. The value only needs to be present; it can be of any value type (though REG_NONE is most appropriate) and does not require any data to be associated with it. If data is present, it is ignored.

HKEY_CLASSES_ROOT

Application

shell

open

(Default) = &Open
LegacyDisable

  • command