Windows Application Registration Guide

Extensions

Key location:

  • HKEY_LOCAL_MACHINE\Software\Classes - for global registration.
  • HKEY_CURRENT_USER\Software\Classes (view of HKEY_CLASSES_ROOT) - for per-user registration.

Add there a key with extension name (as is, i.e. ".test") and following structure:

  • (default value) - name of ProgID which is related to this file type. Required.
  • Content Type (string value) - file MIME-type. Optional.
  • OpenWithProgIds (subkey) - add to this subkey list ProgIDs for open-with list. Each value type is empty string or null value. Each value name is ProgID. Optional.

Note: this registration should NOT be deleted during uninstall.

Protocols

Key location:

  • HKEY_LOCAL_MACHINE\Software\Classes - for global registration.
  • HKEY_CURRENT_USER\Software\Classes (view of HKEY_CLASSES_ROOT) - for per-user registration.

Add there a key with protocol name (as is, i.e. "http") and following structure:

  • (default value) - scheme description, which looks like "URL:Hyper-Text Protocol". "URL:" prefix is required.
  • EditFlags (DWORD value) - protocol flags. Refer to MSDN. Optional.
  • FriendlyTypeName (string value) - localized protocol description. May be PE resource reference or direct string. Refer to MSDN for resource reference syntax. Optional.
  • URL Protocol (empty string value or null value) - protocol marker. Required.
  • DefaultIcon (subkey) - default protocol icon. Optional.
    • (default value) - icon reference. Refer to MSDN for icon reference syntax.
  • shell (subkey) - root for verbs.

Note: this registration should NOT be deleted during uninstall.

ProgID

Key location:

  • HKEY_LOCAL_MACHINE\Software\Classes - for global registration.
  • HKEY_CURRENT_USER\Software\Classes (view of HKEY_CLASSES_ROOT) - for per-user registration.

Add there a key with ProgID name (for example, MyApp.JPEG). Note that multiple file extensions can use same ProgID if they are the same. For example, ".jpg" and ".jpeg" extensions are just different names for the same file type and, thus, should use same ProgID "MyApp.JPEG". Structure:

  • (default value) - extension description. Optional.
  • IsShortcut (empty string value or null value) - undocumented shortcut marker. Optional.
  • NeverShowExt (empty string value or null value) - undodumented marker. Optional. This marker forces shell to hide the extension even if the "hide extensions for known file types" is off. This is used for .lnk files.
  • FriendlyTypeName (string value) - localized extension description. May be PE resource reference or direct string. Refer to MSDN for resource reference syntax. Optional.
  • DefaultIcon (subkey) - default file extension icon. Optional. If not set, the application icon will be used.
    • (default value) - icon reference. Refer to MSDN for icon reference syntax.
  • EditFlags (DWORD value) - file type flags. Refer to MSDN. Optional.
  • InfoTip (string value) - shell tooltip text. May be PE resource reference or direct string. Refer to MSDN for resource reference syntax. Optional.
  • Application (subkey) - this thing is used in Windows 8.1/10 default applications UI. Recommended.
    • ApplicationCompany (string value) - publisher company name.
    • ApplicationDescription (string value) - application description.
  • shell (subkey) - root for verbs.

Note: this registration SHOULD be deleted during uninstall.

Verbs

Verb is action which could be performed with file by shell. The mostly used verb is open for opening files, but you can add custom, even unique verbs for specified actions.

Verbs are used in different parts of registry and always have same structure:

  • shell (subkey) - root for verbs.
    • verb name (subkey) - name of verb. There may be a few different verbs in root shell key.
      • (default value) - verb description to show in shell context menu. Recommended.
      • command (subkey) - root of execution command for this verb.
        • (default value) - commandline for execution. Required.

The commandline is used when opening files with ShellExec. Value uses arguments substitution where "%1" is the target file path. In common case the commandline looks like:

"C:\Program Files\MyApp\MyApp.exe" "%1"

Quotes are highly recommended as path can contain whitespaces which could break the arguments parsing. Along with target file (%1), you may add any commandline arguments for your application here.

Microsoft also highly recommends to use variable substitution as much as it is possible. So use %SYSTEMROOT% instead of hardcoding "C:\Windows".

Known verbs are:

  • open - default file open.
  • print - print file.
  • explore - open directory in another Explorer window. Directory specific.
  • find - open search in directory. Directory specific.
  • openas - open file in special way.
  • properties - display file properties.
  • printto - not displayed in context menu. It allows the user to print a file by dragging it to a printer object.
  • runas - open file with user rights elevation. Not used in context menu.
  • edit - edit file. In some case this action is different from just open.
  • new - create new file.

In most cases support of open verb is required.

Paths Registration

Key location:

  • HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\App Paths - for global registration.
  • HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\App Paths - for per-user registration.

Add there a key with the application executable name (MyApp.exe) with following structure:

  • (default value) - absolute path to the executable. Required.
  • Path (string value) - list of paths to be added to PATH environment variable for the executable process. Paths are separated with comma. Optional.
  • UseURL (DWORD value with value 0x1) - should be added if the application can open URLs directly from command line. Optional.
  • SupportedProtocols (string value) - list of supported protocols separated by colon. Didn't found any usage of this. Optional. If used, the MSDN recommends to add there a file protocol. Example: scheme1:scheme2:....
  • UseShortName (empty string value or null value) - unknown for me.

Executable

Key location:

  • HKEY_LOCAL_MACHINE\Software\Classes\Applications - for global registration.
  • HKEY_CURRENT_USER\Software\Classes\Applications - for per-user registration.

Add there a key with the application executable name (MyApp.exe) with following structure:

  • shell (subkey) - root for verbs of unknown purpose.
  • DefaultIcon (subkey) - used to override the default application icon. Optional.
    • (default value) - icon reference. Refer to MSDN for icon reference syntax.
  • FriendlyTypeName (string value) - localized description of some purpose. May be PE resource reference or direct string. Refer to MSDN for resource reference syntax. Optional.
  • SupportedTypes (subkey) - list of extensions which could be opened by the application. Used in Windows 8.1/10 default applications dialog. Recommended.
    • (extension name) (empty string value of null value) - name of extension as it is, for example: .jpg
  • NoOpenWith (empty string value or null value) - tries to remove the application from open-menu. Optional. The the application is referenced in open-with list of some existing file extensions, it will still appear there.
  • NoStartPage (empty string value or null value) - forbids application from appearing in Start Menu title page. Recommended for uninstallers and other tools.
  • UseExecutableForTaskbarGroupIcon (empty string value or null value) - forces taskbar to use default application icon instead of icon of first encountered window. Optional.
  • TaskbarGroupIcon - overrides the taskbar icon. Optional.
    • (default value) - icon reference. Refer to MSDN for icon reference syntax.

Windows 8.1/10 Default Programs

For your application appear in Windows 8.1/10 default programs windows, you should also register it in Registered Applications.

Key location:

  • HKEY_LOCAL_MACHINE\SOFTWARE\RegisteredApplications - for global registration.
  • HKEY_CURRENT_USER\SOFTWARE\RegisteredApplications - for per-user registration.

Add there a string value named as your application. The value should be path to the Capabilities key in same root. The 'Capabilities' can be stored in some random location or in Clients.

For example:

Name: BrokenURL

Value: Software\BrokenEvent\BrokenURL\Capabilities

Clients

Clients are used as applications for well-known services such as browser or mail program.

Key location:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Clients - for global registration.
  • HKEY_CURRENT_USER\SOFTWARE\Clients - for per-user registration.

There are keys with types of clients. Well-known types are:

  • Calendar
  • Contacts
  • EnvelopeHost
  • Mail - mail program.
  • Media
  • News
  • StartMenuInternet - browser.

In client type key add a subkey with name of your application (full name or executable name) with following structure:

  • (default value) - application name.
  • DefaultIcon (subkey) - client icon. Optional.
    • (default value) - icon reference. Refer to MSDN for icon reference syntax.
  • shell (subkey) - root for verbs. At least open verb is required. Required.
  • Capabilities - root for Capabilities.
  • Protocols - list of protocols supported. Optional.
    • protocol name - protocol definition. See "Protocols" section.

Capabilities

Capabilities can be located in one of Clients or in random key. If the application is not client, it is recommended to store capabilities in Software\%companyName%\%appName%\Capabilities key. Be aware to store it in same root as used in RegisteredApplications (see "Windows 8.1/10 Default Programs" section).

Structure:

  • FileAssociations (subkey) - list of supported file extensions. Each value in this key string value is named as supported extension (for example ".jpg") and its value is ProgId name for this extension.
  • URLAssociations (subkey) - list of supported protocols. Each value in this key string value is named as supported extension (for example "http") and its value is ProgId name for this protocol. ProgID for protocol registration in HKCR is not required, but it is used here. The protocol ProgID structure is the same as described in "ProgId" section.
  • ApplicationDescription (string value) - the application description, may be long.
  • ApplicationIcon (string value) - the application icon reference. Refer to MSDN for icon reference syntax.
  • ApplicationName (string value) - the application name.