How to: Create Custom Options Pages

Visual Studio add-ins are deprecated in Visual Studio 2013. You should upgrade your add-ins to VSPackage extensions. For more information about upgrading, see FAQ: Converting Add-ins to VSPackage Extensions.

The Options dialog box displays a variety of 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 let users change settings for your add-ins or other programs.

To create your own custom Options page, you do not have to use an add-in because the page definition is stored in an XML file instead of registry keys. Consequently, you can create Options pages that are accessible in the Visual Studio integrated development environment (IDE) and also in the Macros IDE.

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

To create a custom Options page

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

2. Add the controls and functionality you want.

   This user control will become the custom Options page. Resize the control to fill the 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 Options page named Add-in/Macros Security defines a set of tokens for file paths of .addin files. The following tokens are included:

   • %ALLUSERSPROFILE%

   • %APPDATA%

   • %USERPROFILE%

   • %VSAPPDATA%

   • %VSCOMMONAPPDATA%

   When Visual Studio starts searching for .addin files, it replaces these tokens by using the following path strings:

   Token	Path
   %ALLUSERSPROFILE%	..\Documents and Settings\All Users\Application Data\Microsoft\MSEnvShared\Addins\
   %APPDATA%	..\Documents and Settings\username\Microsoft\MSEnvShared\Addins\
   %USERPROFILE%	..\Documents and Settings\username\My Documents\Visual Studio 2010\Addins\
   %VSAPPDATA%	..\Documents and Settings\username\Addins\
   %VSCOMMONAPPDATA%	..\Documents and Settings\All Users\Addins

   For more information about how to register add-ins, see Add-In Security.

4. In one of the directories listed earlier, create an .addin file to reference the new Options page.

   You can use the following code 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>10.0</Version>
       </HostApplication>
       <HostApplication>
           <Name>Microsoft Visual Studio</Name>
           <Version>10.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>
   

5. In the <Assembly></Assembly> tag, replace <dll location> by using the path of ToolsOptionsLibrary.dll.

6. 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 Options DLL is located. The Category Name is the node in the Options dialog box where you want to locate your custom page, for example, Environment, Debugging, or Projects.

   If you specify a name that does not exist, a node that has that name is created. The SubCategory is the name that appears under the node. Notice that the maximum number of levels is two. You cannot add a third-level node.

7. Save the file as a text file that has the .addin file name extension, in one of the add-in file folders that are described earlier. The default directory is ..\Documents and Settings\username\Application Data\Microsoft\MSEnvShared\Addins\.

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

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

   Your new Options page is displayed.

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