How to: Create Custom Tools Options Pages

The Options dialog box on the Tools menu displays a variety of option pages for different parts of Visual Studio. You can control the existing options pages, as outlined in Controlling Options Settings, and you can also create your own custom pages. You can use custom pages to allow users to change settings for your add-ins or other programs.

Creating your own custom Tools Options pages is easier than ever before. You no longer need to use an add-in to create a new Tools Options page because the page definitions are now stored in separate XML files rather than in registry keys. Consequently, you can now create Tools Options pages that are accessible in the Macros integrated development environment (IDE) as well as the main Visual Studio IDE.

The following procedure demonstrates how to create a custom user control that will act as a custom Tools Options page, and then modify a .Addin file to reference it.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. These procedures were developed with the General Development Settings active. To change your settings, choose Import and ExportSettings on the Tools menu. For more information, see Visual Studio Settings.

To create a custom Tools Options page

1. Create a new Windows Control Library project. Name it ToolsOptionsLibrary.dll.

2. Add the controls and functionality you desire to the user control.

   This user control will become the custom Tools Option page. You should resize the control to fill the Tools Options dialog box client area.

3. Build the project.

   Visual Studio looks for all shared .Addin files when it starts and loads those that are present. The Tools Options page named Add-in/Macros Security defines a set of tokens for file paths for .Addin files. The following tokens are included:

   • %ALLUSERSPROFILE%

   • %APPDATA%

   • %USERPROFILE%

   • %VSAPPDATA%

   • %VSCOMMONAPPDATA%

   When Visual Studio begins searching for .Addin files, it replaces these tokens with the following path strings:

Token	Path
%ALLUSERSPROFILE%	<drive>:\Documents and Settings\All Users\Application Data\Microsoft\MSEnvShared\Addins
%APPDATA%	<drive>:\Documents and Settings\<username>\Microsoft\MSEnvShared\Addins
%USERPROFILE%	<drive>:\Documents and Settings\<username>\My Documents\Visual Studio 2005\Addins
%VSAPPDATA%	<drive>:\Documents and Settings\<username>\Addins
%VSCOMMONAPPDATA%	<drive>:\Documents and Settings\All Users\Addins

For more information about registering add-ins, see Add-in Security.

1. Create a new .Addin file to reference the new Tools Option page in one of the directories listed above.

   You can use the following as a template:

   <?xml version="1.0" encoding="UTF-16" standalone="no"?>
   <Extensibility xmlns="https://schemas.microsoft.com/AutomationExtensibility">
       <HostApplication>
           <Name>Microsoft Visual Studio Macros</Name>
           <Version>8.0</Version>
       </HostApplication>
       <HostApplication>
           <Name>Microsoft Visual Studio</Name>
           <Version>8.0</Version>
       </HostApplication>
       <ToolsOptionsPage>
           <Category Name="Environment">
               <SubCategory Name="My Tools Options Page">
                   <Assembly><dll location></Assembly>
                   <FullClassName>ToolsOptionsLibrary.UserControl1
                   </FullClassName>
               </SubCategory>
           </Category>
       </ToolsOptionsPage>
   </Extensibility>
   

2. In the <Assembly></Assembly> tag, replace <dll location> with the path to the ToolsOptionsLibrary.dll.

3. Change the <ToolsOptionsPage> settings (Category Name, SubCategory Name, and so on) to reflect the specifics of your user control.

   For example, if your user control is named "NewPage" and its project is "MyTOLib," then the FullClassName tag would be MyTOLib.NewPage. The Assembly is where the Tools Options DLL is located. The Category Name is the node in the Tools Options dialog box where you want to locate your custom page, such as Environment, Debugging, Projects, and so forth.

   If you specify a name that does not exist, a new node with that name is created. The SubCategory is the name that appears under the node. Note that the maximum number of levels is two. That means that you cannot add a third-level node, such as under the Text Editor node.

4. Save the above file in a text file with the extension, .Addin, in one of the .Addin file folders described in step three(3). The default directory is <drive>:\Documents and Settings\<your username>\Application Data\Microsoft\MSEnvShared\Addins.

   When Visual Studio starts, it looks in this directory for custom Tools Options page definitions and loads those that it finds. You can change or add .Addin directories by using the Add-in / Macros Security page under the Environment node.

5. Start Visual Studio and click Options on the Tools menu.

   You see your new Tools Options page.

In addition to this example, you can download a full-featured Tools Option page from the Visual Studio Automation Samples Web site. See the RegExplore sample on the Automation Samples site. This example, however, shows how to create a Tools Options page using a COM control.

See Also

Tasks

How to: Change Window Characteristics

Concepts

Controlling Options Settings

Add-in Registration

Automation Object Model Chart

Other Resources

Creating and Controlling Environment Windows

Automation and Extensibility Reference