Creating Options Pages By Using Managed Package Framework Classes
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.
Registering as a Tools Options Page Provider
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. For more information, see Using Options Pages.
Persisting Tools Options Page State
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. For more information, see Using Options Pages.
A VSPackage can manage its own persistence by using ProvideProfileAttribute. Only one or the other method of persistence should be used.
Implementing DialogPage Class
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 true for 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.
Example
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
using System;
using Microsoft.VisualStudio.Shell;
namespace Company.UIUserSettingsToolsOptionsPages
{
class HelloWorldOptions : DialogPage
{
bool helloWorld = true;
public bool HelloWorld
{
get { return helloWorld; }
set { helloWorld = value; }
}
}
}
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
[ProvideOptionPage(typeof(HelloWorldOptions),
"Hello World Category", "Hello World Page",
1000, 1001, false)]
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
private void ShowHelloWorld(object sender, EventArgs e)
{
var hw = GetDialogPage(typeof(HelloWorldOptions))
as HelloWorldOptions;
if (hw.HelloWorld == true)
{
MessageBox.Show("Hello World!");
}
else MessageBox.Show("Goodbye.");
}
See Also
Concepts
Automation Support for Options Pages
Registering Custom Options Pages
Creating Options Pages By Using Automation
Creating Options Pages By Using Interop Assemblies