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.

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.

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.

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

using System;
using Microsoft.VisualStudio.Shell;

namespace Company.UIUserSettingsToolsOptionsPages
{
    class HelloWorldOptions : DialogPage
    {
        bool helloWorld = true;
        public bool HelloWorld
        {
            get { return helloWorld; }
            set { helloWorld = value; }
        }
    }
}

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

[ProvideOptionPage(typeof(HelloWorldOptions), 
    "Hello World Category", "Hello World Page", 
    1000, 1001, false)]

<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 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.");
}

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

See Also

Extending User Settings and Options
Automation Support for Options Pages