Criar uma página de opções

Artigo
01/12/2024

Este passo a passo cria uma página Ferramentas/Opções simples que usa uma grade de propriedades para examinar e definir propriedades.

Para salvar essas propriedades e restaurá-las de um arquivo de configurações, siga estas etapas e consulte Criar uma categoria de configurações.

O MPF fornece duas classes para ajudá-lo a criar páginas de Opções de Ferramentas, a classe e a Package DialogPage classe. Você cria um VSPackage para fornecer um contêiner para essas páginas subclassificando a Package classe. Você cria cada página de opções de ferramentas derivando da DialogPage classe.

Criar uma página de grade Opções de Ferramentas

Nesta seção, você cria uma grade de propriedades Opções de Ferramentas simples. Use essa grade para exibir e alterar o valor de uma propriedade.

Para criar o projeto VSIX e adicionar um VSPackage

Cada extensão do Visual Studio começa com um projeto de implantação VSIX, que conterá os ativos de extensão. Crie um projeto VSIX do Visual Studio chamado MyToolsOptionsExtension. Você pode encontrar o modelo de projeto VSIX na caixa de diálogo Novo projeto pesquisando por "vsix".
Adicione um VSPackage adicionando um modelo de item de pacote do Visual Studio chamado MyToolsOptionsPackage. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar>Novo Item. Na caixa de diálogo Adicionar Novo Item, vá para Extensibilidade de Itens>do Visual C# e selecione Pacote do Visual Studio. No campo Nome na parte inferior da caixa de diálogo, altere o nome do arquivo para MyToolsOptionsPackage.cs. Para obter mais informações sobre como criar um VSPackage, consulte Criar uma extensão com um VSPackage.

Para criar a grade de propriedades Opções de Ferramentas

Abra o arquivo MyToolsOptionsPackage no editor de códigos.
Adicione a seguinte instrução using.
```
using System.ComponentModel;
```
Declare uma OptionPageGrid classe e derive-a de DialogPage.
```
public class OptionPageGrid : DialogPage
{  }
```

Aplique um à classe para atribuir à VSPackage classe uma categoria de opções e um ProvideOptionPageAttribute nome de página de opções para o OptionPageGrid. O resultado deverá ter a seguinte aparência:

[PackageRegistration(UseManagedResourcesOnly = true)]
[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
[ProvideMenuResource("Menus.ctmenu", 1)]
[Guid(GuidList.guidMyToolsOptionsPkgString)]
[ProvideOptionPage(typeof(OptionPageGrid),
    "My Category", "My Grid Page", 0, 0, true)]
public sealed class MyToolsOptionsPackage : Package

Adicione uma OptionInteger propriedade à OptionPageGrid classe.
- Aplique um System.ComponentModel.CategoryAttribute para atribuir à propriedade uma categoria de grade de propriedades.
- Aplique um para atribuir um System.ComponentModel.DisplayNameAttribute nome à propriedade.
- Aplique um System.ComponentModel.DescriptionAttribute para atribuir à propriedade uma descrição.
```
public class OptionPageGrid : DialogPage
{
    private int optionInt = 256;

    [Category("My Category")]
    [DisplayName("My Integer Option")]
    [Description("My integer option")]
    public int OptionInteger
    {
        get { return optionInt; }
        set { optionInt = value; }
    }
}
```
Observação

A implementação padrão de DialogPage oferece suporte a propriedades que têm conversores apropriados ou que são estruturas ou matrizes que podem ser expandidas em propriedades que têm conversores apropriados. Para obter uma lista de conversores, consulte o System.ComponentModel namespace.
Compile o projeto e comece a depuração.
Na instância experimental do Visual Studio, no menu Ferramentas , clique em Opções .

No painel esquerdo, você deve ver Minha Categoria. (As categorias de opções são listadas em ordem alfabética, portanto, devem aparecer na metade da lista.) Abra Minha Categoria e clique em Minha Página de Grade. A grade de opções aparece no painel direito. A categoria da propriedade é My Options e o nome da propriedade é My Integer Option. A descrição da propriedade, opção Meu inteiro, aparece na parte inferior do painel. Altere o valor de seu valor inicial de 256 para outra coisa. Clique em OK e, em seguida, reabra Minha Página de Grade. Você pode ver que o novo valor persiste.

Sua página de opções também está disponível por meio da caixa de pesquisa do Visual Studio. Na caixa de pesquisa próxima à parte superior do IDE, digite Minha Categoria e você verá Minha Categoria -> Minha Página de Grade listada nos resultados.

Criar uma página personalizada Opções de Ferramentas

Nesta seção, você cria uma página Opções de Ferramentas com uma interface do usuário personalizada. Use esta página para exibir e alterar o valor de uma propriedade.

Abra o arquivo MyToolsOptionsPackage no editor de códigos.
Adicione a seguinte instrução using.
```
using System.Windows.Forms;
```

Adicione uma OptionPageCustom classe, logo antes da OptionPageGrid aula. Derive a nova classe de DialogPage.

public class OptionPageCustom : DialogPage
{
    private string optionValue = "alpha";

    public string OptionString
    {
        get { return optionValue; }
        set { optionValue = value; }
    }
}

Adicione um atributo GUID. Adicione uma propriedade OptionString:

[Guid("00000000-0000-0000-0000-000000000000")]
public class OptionPageCustom : DialogPage
{
    private string optionValue = "alpha";

    public string OptionString
    {
        get { return optionValue; }
        set { optionValue = value; }
    }
}

Aplique um segundo ProvideOptionPageAttribute à classe VSPackage. Esse atributo atribui à classe uma categoria de opções e um nome de página de opções.

[PackageRegistration(UseManagedResourcesOnly = true)]
[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
[ProvideMenuResource("Menus.ctmenu", 1)]
[Guid(GuidList.guidMyToolsOptionsPkgString)]
[ProvideOptionPage(typeof(OptionPageGrid),
    "My Category", "My Grid Page", 0, 0, true)]
[ProvideOptionPage(typeof(OptionPageCustom),
    "My Category", "My Custom Page", 0, 0, true)]
public sealed class MyToolsOptionsPackage : Package

Adicione um novo controle de usuário chamado MyUserControl ao projeto.
Adicione um controle TextBox ao controle de usuário.

Na janela Propriedades, na barra de ferramentas, clique no botão Eventos e clique duas vezes no evento Sair. O novo manipulador de eventos aparece no código MyUserControl.cs
Adicione um campo público OptionsPage , um Initialize método à classe de controle e atualize o manipulador de eventos para definir o valor da opção para o conteúdo da caixa de texto:
```
public partial class MyUserControl : UserControl
{
    public MyUserControl()
    {
        InitializeComponent();
    }

    internal OptionPageCustom optionsPage;

    public void Initialize()
    {
        textBox1.Text = optionsPage.OptionString;
    }

    private void textBox1_Leave(object sender, EventArgs e)
    {
        optionsPage.OptionString = textBox1.Text;
    }
}
```
O optionsPage campo contém uma referência à instância pai OptionPageCustom . O Initialize método é exibido OptionString na TextBox. O manipulador de eventos grava o valor atual do TextBox no quando o OptionString foco sai do TextBox.

No arquivo de código do pacote, adicione uma substituição para a OptionPageCustom.Window propriedade à OptionPageCustom classe para criar, inicializar e retornar uma instância do MyUserControl. A classe deverá se parecer agora com o seguinte:

[Guid("00000000-0000-0000-0000-000000000000")]
public class OptionPageCustom : DialogPage
{
    private string optionValue = "alpha";

    public string OptionString
    {
        get { return optionValue; }
        set { optionValue = value; }
    }

    protected override IWin32Window Window
    {
        get
        {
            MyUserControl page = new MyUserControl();
            page.optionsPage = this;
            page.Initialize();
            return page;
        }
    }
}

Compile e execute o projeto.
Na instância experimental, clique em Opções de Ferramentas>.
Encontre Minha Categoria e, em seguida, Minha Página Personalizada.
Altere o valor de OptionString. Clique em OK e reabra Minha Página Personalizada. Você pode ver que o novo valor persistiu.

Opções de acesso

Nesta seção, você obtém o valor de uma opção do VSPackage que hospeda a página Opções de Ferramentas associada. A mesma técnica pode ser usada para obter o valor de qualquer bem público.

No arquivo de código do pacote, adicione uma propriedade pública chamada OptionInteger à classe MyToolsOptionsPackage .
```
public int OptionInteger
{
    get
    {
        OptionPageGrid page = (OptionPageGrid)GetDialogPage(typeof(OptionPageGrid));
        return page.OptionInteger;
    }
}
```
Esse código chama GetDialogPage para criar ou recuperar uma OptionPageGrid instância. OptionPageGrid chama LoadSettingsFromStorage para carregar suas opções, que são propriedades públicas.
Agora adicione um modelo de item de comando personalizado chamado MyToolsOptionsCommand para exibir o valor. Na caixa de diálogo Adicionar Novo Item, vá para Visual C#>Extensibility e selecione Comando Personalizado. No campo Nome na parte inferior da janela, altere o nome do arquivo de comando para MyToolsOptionsCommand.cs.

No arquivo MyToolsOptionsCommand, substitua o corpo do método do ShowMessageBox comando com o seguinte:

private void ShowMessageBox(object sender, EventArgs e)
{
    MyToolsOptionsPackage myToolsOptionsPackage = this.package as MyToolsOptionsPackage;
    System.Windows.Forms.MessageBox.Show(string.Format(CultureInfo.CurrentCulture, "OptionInteger: {0}", myToolsOptionsPackage.OptionInteger));
}

Compile o projeto e comece a depuração.
Na instância experimental, no menu Ferramentas , clique em Invoke MyToolsOptionsCommand.

Uma caixa de mensagem exibe o valor atual de OptionInteger.

Abrir página de opções

Nesta seção, você adicionará um Comando e um evento para que o botão abra a página de opções

Primeiro, adicione um arquivo chamado OpenPageCommand.cs.

Em seguida, abra OpenPageCommand.cs e altere o método Execute.

private void Execute(object sender, EventArgs e)
{
    ThreadHelper.ThrowIfNotOnUIThread();
    Type optionsPageType = typeof(OptionPageCustom);
    Instance.package.ShowOptionPage(optionsPageType);
}

Execute o projeto e, em seguida, clique no botão Invocar (está na opção Ferramenta por padrão), então você pode ver sua página de opções está aberta.
Mais detalhes sobre a página de opções de abertura podem consultar os seguintes documentos

Abrindo uma página de opções

Páginas de opções e opções