Create a Windows Forms Toolbox Control

Article
3/16/2019

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

The Windows Forms Toolbox Control item template that is included in the Visual Studio Extensibility Tools (VS SDK), lets you create a Toolbox control that is automatically added when the extension is installed. This walkthrough shows how to use the template to create a simple counter control that you can distribute to other users.

Prerequisites

Starting in Visual Studio 2015, you do not install the Visual Studio SDK from the download center. It is included as an optional feature in Visual Studio setup. You can also install the VS SDK later on. For more information, see Install the Visual Studio SDK.

Create the Toolbox Control

The Windows Forms Toolbox Control template creates an undefined user control and provides all of the functionality that is required to add the control to the Toolbox.

Create an extension with a Windows Forms Toolbox Control

Create a VSIX project named MyWinFormsControl. You can find the VSIX project template in the New Project dialog, by searching for "vsix".
When the project opens, add a Windows Forms Toolbox Control item template named Counter. In the Solution Explorer, right-click the project node and select Add > New Item. In the Add New Item dialog, go to Visual C# > Extensibility and select Windows Forms Toolbox Control
This adds a user control, a ProvideToolboxControlAttribute RegistrationAttribute to place the control in the Toolbox, and a Microsoft.VisualStudio.ToolboxControl Asset entry in the VSIX manifest for deployment.

Build a user interface for the control

The Counter control requires two child controls: a Label to display the current count, and a Button to reset the count to 0. No other child controls are required because callers will increment the counter programmatically.

To build the user interface

In Solution Explorer, double-click Counter.cs to open it in the designer.
Remove the Click Here ! button that is included by default when you add the Windows Forms Toolbox Control item template.
From the Toolbox, drag a Label control and then a Button control below it to the design surface.
Resize the overall user control to 150, 50 pixels, and resize the button control to 50, 20 pixels.
In the Properties window, set the following values for the controls on the design surface.

Control Property Value

Label1 Text ""

Button1 Name btnReset

Button1 Text Reset

Control	Property	Value
`Label1`	Text	""
`Button1`	Name	btnReset
`Button1`	Text	Reset

Code the user control

The Counter control will expose a method to increment the counter, an event to be raised whenever the counter is incremented, a Reset button, and three properties to store the current count, the display text, and whether to show or hide the Reset button. The ProvideToolboxControl attribute determines where in the Toolbox the Counter control will appear.

To code the user control

Double-click the form to open its load event handler in the code window.
Above the event handler method, in the control class create an integer to store the counter value and a string to store the display text as shown in the following example.
```
int currentValue;
string displayText;
```
Create the following public property declarations.
```
public int Value {
    get { return currentValue; }
}

public string Message {
    get { return displayText; }
    set { displayText = value; }
}

public bool ShowReset {
    get { return btnReset.Visible; }
    set { btnReset.Visible = value; }
}
```
Callers can access these properties to get and set the display text of the counter and to show or hide the Reset button. Callers can obtain the current value of the read-only Value property, but they cannot set the value directly.
Put the following code in the Load event for the control.
```
private void Counter_Load(object sender, EventArgs e)
{
    currentValue = 0;
    label1.Text = Message + Value;
}
```
Setting the Label text in the Load event enables the target properties to load before their values are applied. Setting the Label text in the constructor would result in an empty Label.

Create the following public method to increment the counter.

public void Increment()
{
    currentValue++;
    label1.Text = displayText + Value;
    Incremented(this, EventArgs.Empty);
}

Add a declaration for the Incremented event to the control class.
```
public event EventHandler Incremented;
```
Callers can add handlers to this event to respond to changes in the value of the counter.
Return to design view and double-click the Reset button to generate the btnReset_Click event handler. Then, fill it in as shown in the following example.
```
private void btnReset_Click(object sender, EventArgs e)
{
    currentValue = 0;
    label1.Text = displayText + Value;
}
```
Immediately above the class definition, in the ProvideToolboxControl attribute declaration, change the value of the first parameter from "MyWinFormsControl.Counter" to "General". This sets the name of the item group that will host the control in the Toolbox.

The following example shows the ProvideToolboxControl attribute and the adjusted class definition.
```
[ProvideToolboxControl("General", false)]
public partial class Counter : UserControl
```

Test the control

To test a Toolbox control, first test it in the development environment and then test it in a compiled application.

To test the control

Press F5 to Start Debugging.

This command builds the project and opens a second Experimental instance of Visual Studio that has the control installed.
In the Experimental instance of Visual Studio, create a Windows Forms Application project.
In Solution Explorer, double-click Form1.cs to open it in the designer if it is not already open.
In the Toolbox, the Counter control should be displayed in the General section.
Drag a Counter control to your form, and then select it. The Value, Message, and ShowReset properties will be displayed in the Properties window, together with the properties that are inherited from UserControl.
Set the Message property to Count:.
Drag a Button control to the form, and then set the name and text properties of the button to Test.
Double-click the button to open Form1.cs in code view and create a click handler.
In the click handler, call counter1.Increment().
In the constructor function, after the call to InitializeComponent, type counter1``.``Incremented += and then press Tab twice.

Visual Studio generates a form-level handler for the counter1.Incremented event.
Highlight the Throw statement in the event handler, type mbox, and then press Tab twice to generate a message box from the mbox code snippet.
On the next line, add the following if/else block to set the visibility of the Reset button.
```
if (counter1.Value < 5) counter1.ShowReset = false;
else counter1.ShowReset = true;
```
Press F5.

The form opens. The Counter control displays the following text.

Count: 0
Select Test.

The counter increments and Visual Studio displays a message box.
Close the message box.

The Reset button disappears.
Select Test until the counter reaches 5 closing the message boxes each time.

The Reset button reappears.
Select Reset.

The counter resets to 0.

Next steps

When you build a Toolbox control, Visual Studio creates a file named ProjectName.vsix in the \bin\debug\ folder of your project. You can deploy the control by uploading the .vsix file to a network or to a Web site. When a user opens the .vsix file, the control is installed and added to the Visual Studio Toolbox on the user's computer. Alternatively, you can upload the .vsix file to Visual Studio Marketplace so that users can find it by browsing in the Tools > Extensions and Updates dialog.