Suporte em tempo de design do Visual Studio para controles personalizados

Como você notou ao interagir com o designer do Windows Forms, há muitos recursos diferentes de tempo de design oferecidos pelos controles do Windows Forms. Alguns dos recursos oferecidos pelo Designer do Visual Studio incluem linhas de ajuste, itens de ação e a grade de propriedades. Todos esses recursos oferecem uma maneira mais fácil de interagir e personalizar um controle durante o tempo de design. Este artigo é uma visão geral sobre que tipo de suporte você pode adicionar aos seus controles personalizados, para melhorar a experiência de design dos consumidores de seus controles.

O que é diferente do .NET Framework

Muitos elementos de design básicos de controles personalizados permaneceram os mesmos do .NET Framework. No entanto, se você usar recursos de personalização de designer mais avançados, como listas de ações, conversores de tipo, caixas de diálogo personalizadas, você terá alguns cenários exclusivos para lidar.

O Visual Studio é um aplicativo baseado no .NET Framework e, como tal, o Visual Designer que você vê para o Windows Forms também se baseia no .NET Framework. Com um projeto do .NET Framework, o ambiente do Visual Studio e o aplicativo Windows Forms que está sendo projetado são executados no mesmo processo, devenv.exe. Isso representa um problema quando você está trabalhando com um aplicativo Windows Forms .NET (não .NET Framework). O .NET e o .NET Framework não podem funcionar no mesmo processo. Como resultado, o Windows Forms .NET usa um designer diferente, o designer "fora do processo".

O designer fora do processo é um processo chamado DesignToolsServer.exe, e é executado junto com o processo devenv.exe do Visual Studio. O processo DesignToolsServer.exe é executado na mesma versão e plataforma, como .NET 9 e x64, do .NET para o qual seu aplicativo está destinado. Quando o controle personalizado precisa exibir a interface do usuário no Visual Studio, seu controle personalizado deve implementar uma arquitetura cliente-servidor para facilitar a comunicação de e para devenv.exe. Para mais informações, consulte As alterações no designer desde o .NET Framework.

Janela de Propriedades

A janela Propriedades do Visual Studio exibe as propriedades e os eventos do controle ou formulário selecionado. Esse geralmente é o primeiro ponto de personalização que você executa em um controle ou componente personalizado.

A imagem a seguir mostra um Button controle selecionado no Designer Visual e a grade de propriedades mostrando as propriedades do botão:

Você pode controlar alguns aspectos de como as informações sobre seu controle personalizado são exibidas na grade de propriedades. Os atributos são aplicados à classe de controle personalizada ou às propriedades de classe.

Atributos para classes

A tabela a seguir mostra os atributos que você pode aplicar para especificar o comportamento de seus controles e componentes personalizados em tempo de design.

Atributo	Descrição
DefaultEventAttribute	Especifica o evento padrão para um componente.
DefaultPropertyAttribute	Especifica a propriedade padrão para um componente.
DesignerAttribute	Especifica a classe usada para implementar serviços de tempo de design para um componente.
DesignerCategoryAttribute	Especifica que o designer de uma classe pertence a uma determinada categoria.
ToolboxItemAttribute	Representa um atributo de um item de caixa de ferramentas.
ToolboxItemFilterAttribute	Especifica a cadeia de caracteres de filtro e o tipo de filtro a ser usado para um item da Caixa de Ferramentas.

Atributos para propriedades

A tabela a seguir mostra os atributos que você pode aplicar às propriedades ou a outros membros de seus controles e componentes personalizados.

Atributo	Descrição
AmbientValueAttribute	Especifica o valor a ser passado para uma propriedade para fazer com que a propriedade obtenha seu valor de outra fonte. Isso é chamado de ambiente.
BrowsableAttribute	Especifica se uma propriedade ou evento deve ser exibido em uma janela Propriedades .
CategoryAttribute	Especifica o nome da categoria para a qual a propriedade ou o evento serão agrupados quando exibidos em um PropertyGrid controle definido no modo Categorized.
DefaultValueAttribute	Especifica o valor padrão de uma propriedade.
DescriptionAttribute	Especifica uma descrição de uma propriedade ou evento.
DisplayNameAttribute	Especifica o nome de exibição de uma propriedade, evento ou um método público que não retorna um valor e não usa argumentos.
EditorAttribute	Especifica o editor a ser usado para alterar uma propriedade.
EditorBrowsableAttribute	Especifica que uma propriedade ou método pode ser exibido em um editor.
HelpKeywordAttribute	Especifica a palavra-chave de contexto para uma classe ou membro.
LocalizableAttribute	Especifica se uma propriedade deve ser localizada.
PasswordPropertyTextAttribute	Indica que a representação de texto de um objeto está oculta por caracteres como asteriscos.
ReadOnlyAttribute	Especifica se a propriedade à qual esse atributo está associado é somente leitura ou leitura/gravação em tempo de projeto.
RefreshPropertiesAttribute	Indica que a grade de propriedades deve ser atualizada quando o valor da propriedade associada for alterado.
TypeConverterAttribute	Especifica a qual tipo usar como conversor para o objeto ao qual esse atributo está associado.

Desenvolvedores de controles personalizados

A experiência de design para controles personalizados pode ser aprimorada ao criar um designer personalizado associado. Por padrão, o controle personalizado é exibido na superfície de design do host e tem a mesma aparência durante o tempo de execução. Com um designer personalizado, você pode aprimorar a visualização durante o design do controle, adicionar itens de ação, linhas de alinhamento e outros itens, o que pode ajudar o usuário a definir e configurar o controle. Por exemplo, em tempo de design, o ToolStrip designer adiciona controles extras para o usuário adicionar, remover e configurar os itens individuais, conforme demonstrado na imagem a seguir:

Você pode criar seus próprios designers personalizados executando as seguintes etapas:

1. Adicionando uma referência ao pacote NuGet Microsoft.WinForms.Designer.SDK.
2. Crie um tipo que herde da classe Microsoft.DotNet.DesignTools.Designers.ControlDesigner.
3. Na classe de controle do usuário, marque a classe com o System.ComponentModel.DesignerAttribute atributo de classe, passando o tipo que você criou na etapa anterior.

Para obter mais informações, consulte a seção O que é diferente do .NET Framework .

Itens de ação

As ações do designer são menus sensíveis ao contexto que permitem ao usuário executar tarefas comuns rapidamente. Por exemplo, se você adicionar um TabControl a um formulário, você adicionará e removerá guias de e para o controle. As guias são gerenciadas na janela Propriedades , por meio da TabPages propriedade, que exibe um editor de coleção de guias. Em vez de forçar o usuário a sempre examinar a lista Propriedades procurando a TabPages propriedade, o TabControl fornece um botão de etiqueta inteligente que só fica visível quando o controle é selecionado, como mostrado nas imagens a seguir.

Quando a etiqueta inteligente é selecionada, exibe-se a lista de ações:

Ao adicionar as ações Adicionar Guia e Remover Guia , o designer do controle o torna para que você possa adicionar ou remover rapidamente uma guia.

Criando uma lista de itens de ação

As listas de itens de ação são fornecidas pelo ControlDesigner tipo que você cria. As etapas a seguir são um guia básico para criar sua própria lista de ações:

1. Adicionando uma referência ao pacote NuGet Microsoft.WinForms.Designer.SDK.
2. Crie uma nova classe de lista de ações que herda de Microsoft.DotNet.DesignTools.Designers.Actions.DesignerActionList.
3. Adicione as propriedades à lista de ações que você deseja que o usuário acesse. Por exemplo, adicionar uma bool propriedade ou Boolean (no Visual Basic) à classe cria um CheckBox controle na lista de ações.
4. Siga as etapas na seção Designers de controle personalizados para criar um novo designer.
5. Na classe designer, sobrescreva a propriedade ActionLists, que retorna um tipo Microsoft.DotNet.DesignTools.Designers.Actions.DesignerActionListCollection.
6. Adicione sua lista de ações a uma DesignerActionListCollection instância e retorne-a.

Para obter um exemplo de uma lista de ações, consulte o repositório GitHub de Documentos e Exemplos de Extensibilidade do Designer de Formulários do Windows Forms, especificamente a pasta TileRepeater.Designer.Server/ControlDesigner.

Editores de tipo de caixa de diálogo modal

Na janela Propriedades, a maioria das propriedades é facilmente editada na grade, como quando o tipo subjacente da propriedade é uma enumeração, booleano ou número.

Às vezes, uma propriedade é mais complexa e requer uma caixa de diálogo personalizada que o usuário pode usar para alterar a propriedade. Por exemplo, a Font propriedade é um tipo System.Drawing.Font , que contém muitas propriedades que alteram a aparência da fonte. Isso não é facilmente apresentável na janela Propriedades , portanto, essa propriedade usa uma caixa de diálogo personalizada para editar a fonte:

Se suas propriedades de controle personalizadas estiverem usando os editores de tipos internos fornecidos pelo Windows Forms, você poderá usar o EditorAttribute para marcar suas propriedades com o editor do .NET Framework correspondente que você deseja que o Visual Studio use. Usando os editores integrados, você evita a necessidade de replicar a comunicação cliente-servidor do objeto proxy fornecida pelo designer externo ao processo.

Ao referenciar um editor de tipo interno, use o tipo .NET Framework, não o tipo .NET:

[Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a",
        "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")]
public string? Filename { get; set; }

<Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")>
Public Property Filename As String