Creating Options Pages
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Creating Options Pages.
In the Visual Studio managed package framework, classes derived from DialogPage extend the Visual Studio IDE by adding Options pages under the Tools menu.
An object implementing a given Tools Option page is associated with specific VSPackages by the ProvideOptionPageAttribute object.
Because the environment instantiates the object implementing a particular Tools Options page when that particular page is displayed by the IDE:
A Tools Option page should be implemented on its own object, and not on the object implementing a VSPackage.
An object cannot implement multiple Tools Options pages.
A VSPackage supporting user configuration through Tools Options pages indicates the objects providing these Tools Options pages by applying instances of ProvideOptionPageAttribute applied to the Package implementation.
There must be one instance of ProvideOptionPageAttribute for every DialogPage-derived type that implements a Tools Options page.
Each instance of ProvideOptionPageAttribute uses the type that implements the Tools Options page, strings that contain the category and sub-category used to identify a Tools Options page, and resource information to register the type as providing a Tools Options page.
If a Tools Options page implementation is registered with automation support enabled, the IDE persists the page's state along with all other Tools Options pages.
A VSPackage can manage its own persistence by using ProvideProfileAttribute. Only one or the other method of persistence should be used.
An object providing a VSPackage's implementation of a DialogPage-derived type can take advantage of the following inherited features:
A default user interface window.
A default persistence mechanism available either if ProvideProfileAttribute is applied to the class, or if the SupportsProfiles property is set to
truefor the ProvideOptionPageAttribute that is applied to the class.Automation support.
The minimum requirement for an object implementing a Tools Options page using DialogPage is the addition of public properties.
If the class properly registered as a Tools Options page provider, then its public properties are available on the Options section of the Tools menu in the form of a property grid.
All these default features can be overridden. For example, to create a more sophisticated user interface requires only overriding the default implementation of Window.
What follows is a simple "hello world" implementation of an options page. Adding the following code to a default project created by the Visual Studio Package Template with the Menu Command option selected will adequately demonstrate option page functionality.
Description
The following class defines a minimal "hello world" options page. When opened, the user can set the public HelloWorld property in a property grid.
Code
Imports System Imports Microsoft.VisualStudio.Shell Namespace Company.UIUserSettingsToolsOptionsPages Class HelloWorldOptions Inherits DialogPage Private m_helloWorld As Boolean = True Public Property HelloWorld() As Boolean Get Return m_helloWorld End Get Set(ByVal value As Boolean) m_helloWorld = value End Set End Property End Class End Namespace
Description
Applying the following attribute to the package class makes the options page available when the package loads. The numbers are arbitrary resource IDs for the category and the page, and the Boolean value at the end specifies whether the page supports automation.
Code
<PackageRegistration(UseManagedResourcesOnly:=True)> _ <DefaultRegistryRoot("Software\Microsoft\VisualStudio\9.0")> _ <InstalledProductRegistration(False, "#110", "#112", "1.0", IconResourceID:=400)> _ <ProvideLoadKey("Standard", "1.0", "Package Name", "Company", 1)> _ <ProvideMenuResource(1000, 1)> _ <Guid(GuidList.guidPkgString)> _ <ProvideOptionPage(GetType(HelloWorldOptions), "Hello World Category", "Hello World Page", 1000, 1001, False)> _ Public NotInheritable Class UIUserSettingsToolsOptionsPagesPackage Inherits Package
Description
The following event handler displays a result depending on the value of the property set in the options page. It uses the GetDialogPage method with the result explicitly cast into the custom option page type to access the properties exposed by the page.
In the case of a project generated by the package template, call this function from the MenuItemCallback function to attach it to the default command added to the Tools menu.
Code
Private Sub ShowHelloWorld(ByVal sender As Object, ByVal e As EventArgs)
Dim hw = TryCast(GetDialogPage(GetType(HelloWorldOptions)), HelloWorldOptions)
If hw.HelloWorld = True Then
MessageBox.Show("Hello World!")
Else
MessageBox.Show("Goodbye.")
End If
End Sub
Extending User Settings and Options
Automation Support for Options Pages