How to Register DLL Control Panel Items

Control Panel items that are implemented in a DLL that exports the CPlApplet function have different registration requirements than .exe files. For Windows XP and later systems, new Control Panel item DLLs should be installed in the associated application's folder under the Program Files folder. Items that are stored in the System32 directory with a .cpl extension do not need to be registered; they are automatically shown in the Control Panel. All other Control Panel items usingCPlApplet must be registered in one of two ways:

• If the Control Panel item is to be available to all users, register the path on a per-computer basis by adding a REG_EXPAND_SZ value to theHKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Control Panel\Cpls subkey, set to the DLL path.
• If the Control Panel item is to be available on a per-user basis, use HKEY_CURRENT_USER as the root key instead of HKEY_LOCAL_MACHINE.

The following two examples register the MyCplApp Control Panel item. The DLL is named MyCpl.cpl and is located in the MyCorp\MyApp application directory. This first example illustrates per-computer registration.

Instructions

Step 1:

Add this information to the registry to register the existence of the .cpl file.

HKEY_LOCAL_MACHINE    Software       Microsoft          Windows             CurrentVersion                Control Panel                   Cpls                      MyCpl = [REG_EXPAND_SZ] %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl

Step 2:

Windows Vista and later: Add this additional information to the registry to provide a GUID for the Control Panel item.

HKEY_LOCAL_MACHINE    Software       Microsoft          Windows             CurrentVersion                Control Panel                   Extended Properties                      System.Software.AppId                         %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = {A newly generated GUID}

By generating a GUID to uniquely identify the Control Panel item, you can add task links to the Control Panel. Without this GUID, there is no way for the task links to be associated with the Control Panel item. See Creating Searchable Task Links for a Control Panel Item.

Step 3:

Windows Vista and later: Add the following information to the registry to create a canonical name for the item.

HKEY_LOCAL_MACHINE    Software       Microsoft          Windows             CurrentVersion                Control Panel                   Extended Properties                      System.ApplicationName                         %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_SZ] MyCorporation.MyCpl

By adding a canonical name, users can launch the Control Panel item from a command line by entering control.exe /name MyCorporation.MyCpl. This also makes it possible to change an implementation from a .cpl file to a .exe file later, without requiring calling programs to make any changes since they can continue opening the item through its canonical name. For more information on canonical names, see Executing Control Panel Items.

Step 4:

Windows Vista and later: Add the following information to the registry to assign a Control Panel item to one or more categories.

HKEY_LOCAL_MACHINE    Software       Microsoft          Windows             CurrentVersion                Control Panel                   Extended Properties                      System.ControlPanel.Category                         %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_DWORD] 3

Windows XP: Add the following information to the registry to assign a Control Panel item to one or more categories.

HKEY_LOCAL_MACHINE    Software       Microsoft          Windows             CurrentVersion                Control Panel                   Extended Properties                      {305CA226-D286-468e-B848-2B2E8E697B74} 2                         %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_DWORD] 3

This example assigns the item to category 3, which is Network and Internet. To add an item to multiple categories, provide the list as a REG_SZ value separated by commas, such as "3,8". Values can be provided as either decimal or hexadecimal. Note that the ability to add an item to multiple categories is only possible in Windows XP Service Pack 2 (SP2) and later. See Assigning Control Panel Categories for all possible values.

Step 5:

Windows Vista and later: Add the following information to the registry to create and point to an XML file to hold task links for the item. The value must be a REG_SZ path as shown here or a module and resource ID (for example, "C:\Program Files\MyCorp\MyApp\MyApp.exe,-31") if it is an embedded resource. The location of the XML file should be fully specified. It cannot use an environment variable such as %ProgramFiles%.

HKEY_LOCAL_MACHINE    Software       Microsoft          Windows             CurrentVersion                Control Panel                   Extended Properties                      System.Software.TasksFileUrl                         %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_SZ] C:\ProgramFiles\MyCorp\MyApp\MyTasks.xml

For more details on task links and how to create the XML file to hold them, see Creating Searchable Task Links for a Control Panel Item.