Walkthrough: Creating a Tools Options Page (C#)

[アーティクル]
11/21/2007

This walkthrough creates two Tools Options pages, a simple page and a custom page. The simple page uses a property grid to examine and set properties, and the custom page provides its own user interface (UI). The managed package framework (MPF) supports both scenarios, with very little additional code.

The MPF provides two classes to help you create Tools Options pages, the Package class and the DialogPage class. You create a VSPackage to provide a container for these pages by subclassing the Package class. You create the Tools Options pages themselves by deriving from the DialogPage class.

In this walkthrough, you create the Tools Options pages and use them to display and change application options. You retrieve the option values from the hosting VSPackage. You retrieve them programmatically from another VSPackage by using Automation.

Creating a Tools Options Grid Page

In this section, you use the Visual Studio Integration Package wizard to create a simple Tools Options property grid. You use this grid to display and change the value of a property.

To create a Tools Options property grid

Create a new Visual Studio Integration Package project named MyToolsOptions.

For more information about how to create a managed VSPackage, see How to: Create VSPackages (C# and VB).

The Package Wizard starts.
In the Select a Programming Language page, select Visual C#.
In the Select VSPackage Options page, select Menu Command.
In the Command Options page, change the Command name to "Get internal option", and then click Finish.

The wizard creates the managed project, MyToolsOptions.
Open the file, VsPkg.cs, and add the new class OptionsPageGrid to the namespace, just before the MyToolsOptions class. Derive the new class from DialogPage.
```
namespace Company.MyToolsOptions
{
   public class OptionPageGrid : DialogPage   {   }
```
Add a System.Runtime.InteropServices.ClassInterfaceAttribute to the OptionPageGrid class:
```
 
[ClassInterface(ClassInterfaceType.AutoDual)]
public class OptionPageGrid : DialogPage
```
This creates a COM dual interface that lets Visual Studio Automation use GetAutomationObject to access the public members of the class programmatically.
Add a ProvideOptionPageAttribute to the MyToolsOptions class, and give it the CategoryName "My Category", give it the PageName "My Grid Page", and set SupportAutomation to true:
```
 
[ProvideOptionPage(typeof(OptionPageGrid), "My Category", "My Grid Page", 0, 0, true)]
[Guid(GuidList.guidMyToolsOptionsPkgString)]
public sealed class MyToolsOptions : Package
```
注意

You can localize the category and page name by assigning resource IDs to the attribute properties, CategoryResourceID, and PageNameResourceID(), respectively.
Add this line to the using statements at the top of the file to make the following step easier to read:
```
 
using System.ComponentModel;
```
Add the OptionInteger property to the OptionPageGrid class. Use System.ComponentModel.CategoryAttribute to give it the category "My Options" and System.ComponentModel.DescriptionAttribute to give it the description "My integer option":
```
public class OptionPageGrid : DialogPage
{
   private int _optionInt = 256;   [Category("My Options")]   [Description("My integer option")]   public int OptionInteger   {      get { return _optionInt; }      set { _optionInt = value; }   }
}
```
注意

The default implementation of DialogPage supports properties that have appropriate converters or that are structures or arrays that can be expanded into properties that have appropriate converters. For a list of converters, see the System.ComponentModel namespace. The OptionsPage Sample (C#) manages int, string, and System.Drawing.Size properties.
Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

注意

Both versions of Visual Studio are open now.
In Visual Studio Exp, on the Tools menu click Options.

The Options dialog opens.
In the tree view, expand My Category and then click My Grid Page.

The options grid appears in the right pane. The property category is My Options, and the property name is "OptionInteger". The property description, My integer option, appears at the bottom of the pane.

Change the value of "OptionInteger" from its initial value, 256, to something else. Click OK, and then reopen My Grid Page. You can see that the new value persists.

Creating a Tools Options Custom Page

In this section, you create a Tools Options page with a custom user interface (UI). You use this page to display and change the value of a property.

To create a Tools Options custom page

Exit Visual Studio Exp.
In the file, VsPkg.cs, add the OptionPageCustom class to the namespace, just before the OptionPageGrid class. Derive the new class from DialogPage.
```
namespace Company.MyToolsOptions
{
   public class OptionPageCustom : DialogPage   {   }
```

On the Tools menu, click Create GUID to copy and paste a new GUID with registry format into the code, removing the braces. Add a System.Runtime.InteropServices.ClassInterfaceAttribute. Add the string property, OptionString. Following is an example, but your GUID will differ:

namespace Company.MyToolsOptions
{
   [ClassInterface(ClassInterfaceType.AutoDual)]   [Guid("1D9ECCF3-5D2F-4112-9B25-264596873DC9")]
   public class OptionPageCustom : DialogPage
   {
      private string _optionString = "alpha";      public string OptionString      {         get { return _optionString; }         set { _optionString = value; }      }
   }

Add a ProvideOptionPageAttribute to the MyToolsOptions class, and give it the CategoryName "My Category", give it the PageName "My Custom Page", and set SupportAutomation to true:

 
[ProvideOptionPage(typeof(OptionPageCustom), "My Category", "My Custom Page", 0, 0, true)]
[Guid(GuidList.guidMyToolsOptionsPkgString)]
public sealed class MyToolsOptions : Package

Right-click the MyToolOptions project node, point to Add, and then click New Item.
Add a user control named MyUserControl to the project.

The user control opens in Design view.

注意

If you see a warning, rebuild the solution and reopen MyUserControl.cs. This is a known issue.
Add a TextBox control to the user control. In the Properties window, click the Events (lightning bolt) icon, and then double-click the Leave event.

The code editor opens to show the new event handler.

Add a public OptionsPage field, an Initialize method, and the body of the event handler to the MyUserControl class. Following is an example:

public partial class MyUserControl : UserControl
{
   public MyUserControl()
   {
      InitializeComponent();
   }
   public OptionPageCustom OptionsPage;   public void Initialize()   {      textBox1.Text = OptionsPage.OptionString;   }   private void textBox1_Leave(object sender, EventArgs e)
   {
      OptionsPage.OptionString = textBox1.Text;   }
}

The OptionsPage field holds a reference to the parent OptionPageCustom instance. The Initialize method displays OptionString in the TextBox. The event handler writes the current value of the TextBox to the OptionString when focus leaves the TextBox.

Add this line to the using statements at the beginning of the VsPkg.cs file to make the following step easier to read:
```
 
using System.Windows.Forms;
```

In the VsPkg file, add an override for the OptionPageCustom.Window property to create, initialize, and return an instance of MyUserControl. Following is an example:

public string OptionString
{
   get { return _optionString; }
   set { _optionString = value; }
}
[Browsable(false), DesignerSerializationVisibility(   DesignerSerializationVisibility.Hidden)]protected override IWin32Window Window{   get   {      MyUserControl page = new MyUserControl();      page.OptionsPage = this;      page.Initialize();      return page;   }}

Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

注意

Both versions of Visual Studio are open at this point.
In Visual Studio Exp, on the Tools menu and then click Options.

The Options dialog opens.
In the tree view in the left pane, expand My Category and then click My Custom Page.
Change the value of OptionString from its initial value, alpha, to something else. Click OK, and then reopen My Custom Page. You can see that the new value has persisted.

Accessing Options from the Hosting VSPackage

In this section, you obtain the value of an option from the VSPackage that hosts the associated Tools Options page. The same technique can be used to obtain the value of any public property.

To access an option from the hosting VSPackage

Exit Visual Studio Exp.
In the VsPkg.cs file, replace the body of the MyToolsOptions.MenuItemCallback method with the following lines:
```
private void MenuItemCallback(object sender, EventArgs e)
{
   OptionPageGrid page = (OptionPageGrid)       GetDialogPage(typeof(OptionPageGrid));   MessageBox.Show(      string.Format("OptionInteger: {0}", page.OptionInteger));
}
```
This code calls GetDialogPage to create or retrieve an OptionPageGrid instance. OptionPageGrid in turn invokes LoadSettingsFromStorage to load its options, which are public properties.
Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

注意

Both versions of Visual Studio are open at this point.
On the Tools menu, click Get internal option.

A message box displays the current value of OptionInteger.

Accessing Options by using Automation

In this section, you use Automation to obtain the value of an option from any VSPackage or add-in. The same technique can be used to obtain the value of any public property.

To access an option using Automation

Exit Visual Studio Exp.
Right-click the MyToolsOptions solution in Solution Explorer and add a new Visual Studio Integration Package project named AnotherPackage.

For more information about how to create a managed VSPackage, see How to: Create VSPackages (C# and VB).

The Package Wizard starts.
In the Select a Programming Language page, select Visual C#.
In the Select VSPackage Options page, select Menu Command.
In the Command Options page, change the Command Name to "Get external option", and then click Finish.

The wizard creates the managed project, AnotherPackage.
Right-click the AnotherPackage project node and then click Set as StartUp Project.
Right-click the References node of the AnotherPackage project and then click Add Reference.
Make sure the .NET tab is selected. Select EnvDTE (not envdte), and then click OK.
Add these lines to the using statements at the beginning of the VsPkg.cs file in the AnotherPackage project to make the following step easier to read:
```
 
using EnvDTE;using System.Windows.Forms;
```
Replace the body of the AnotherPackage.MenuItemCallback method with the following lines:
```
private void MenuItemCallback(object sender, EventArgs e)
{
   DTE dte = (DTE)GetService(typeof(DTE));   EnvDTE.Properties props =      dte.get_Properties("My Category", "My Grid Page");   int n = (int) props.Item("OptionInteger").Value;   MessageBox.Show("OptionInteger: " + n);
}
```
This code calls a service to obtain the DTE object, the root object of the Visual Studio Automation model. Properties(String, String) returns the properties collection for My Category.MyGridPage, which includes all public properties. The Item method selects OptionInteger from the collection.
Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

注意

Both versions of Visual Studio are open at this point.
On the Tools menu, click Get external option.

A message box displays the current value of OptionInteger.

次の方法で共有