This documentation is archived and is not being maintained.

Walkthrough: Inheriting from a Windows Forms Control with Visual C#

Visual C# .NET provides you with the ability to create powerful custom controls through inheritance. Through inheritance you are able to create controls that retain all of the inherent functionality of standard Windows Forms controls but also incorporate custom functionality. In this walkthrough, you will create a simple inherited control called ValueButton. This button will inherit functionality from the standard Windows Forms button, and will expose a custom property called ButtonValue.

Creating the Project

When you create a new project, you specify its name in order to set the root namespace, assembly name, and project name, and to ensure that the default component will be in the correct namespace.

To create the ValueButtonLib control library and the ValueButton control

  1. On the File menu, point to New and then click Project to open the New Project dialog box.
  2. Select the Windows Control Library project template from the list of C# Projects, and type ValueButtonLib in the Name box.
    Note   The Windows Control Library template is not available in the Standard Edition of Visual C# .NET. For more information, see Visual C# Standard Edition Features.

    The project name, ValueButtonLib, is also assigned to the root namespace by default. The root namespace is used to qualify the names of components in the assembly. For example, if two assemblies provide components named ValueButton, you can specify your ValueButton component using ValueButtonLib.ValueButton. For more information, see Components and Assemblies.

  3. In Solution Explorer, right-click UserControl1.cs and select View Code from the shortcut menu.
  4. Locate the class statement, public class UserControl1, and change UserControl1 to ValueButton to change the name of the component.
  5. Locate the Constructor, public UserControl1() and change it to public ValueButton().
  6. In the Class statement, change the type from which this control inherits from System.Windows.Forms.UserControl to System.Windows.Forms.Button. This allows your inherited control to inherit all the functionality of the Button control.
  7. In Solution Explorer, click UserControl1.cs and in the Properties window, change the FileName property to ValueButton.cs.
  8. From the File menu, choose Save All to save the project.

    Note that a designer is no longer available. Because the Button control does its own painting, you are unable to modify its appearance in the designer. Its visual representation will be exactly the same as that of the class it inherits from (that is, Button) unless modified in the code.

Adding a Property to Your Inherited Control

One possible use of inherited Windows Forms controls is the creation of controls that are identical in look and feel of standard Windows Forms controls, but expose custom properties. In this section, you will add a property called ButtonValue to your control.

To add the Value property

  1. In Solution Explorer, right-click ValueButton.cs, and then click View Code from the shortcut menu.
  2. Locate the class statement. Immediately after the {, type the following code:
    // Creates the private variable that will store the value of your 
    // property.
    private int varValue;
    // Declares the property.
    public int ButtonValue
       // Sets the method for retrieving the value of your property.
          return varValue;
       // Sets the method for setting the value of your property.
          varValue = value;

    This code sets the methods by which the ButtonValue property is stored and retrieved. The get statement sets the value returned to the value that is stored in the private variable varValue, and the set statement sets the value of the private variable by use of the value keyword.

  3. From the File menu, choose Save All to save the project.

Testing Your Control

Controls are not stand-alone projects; they must be hosted in a container. In order to test your control, you must provide a test project for it to run in. You must also make your control accessible to the test project by building (compiling) it. In this section, you will build your control and test it in a Windows Form.

To build your control

  • On the Build menu, click Build.

    The build should be successful with no compiler errors or warnings.

To create a test project

  1. On the File menu, point to Add Project and then click New Project to open the Add New Project dialog box.
  2. Select the Visual C# projects node, and click Windows Application.
  3. In the Name box, type Test.
  4. In Solution Explorer, right-click the References node for your test project, then select Add Reference from the shortcut menu to display the Add Reference dialog box.
  5. Click the tab labeled Projects.
  6. Double-click the ValueButtonLib project, and note that it now appears in the Selected Components pane.

    After you have added your reference, you should add your new control to the toolbox. If your control already appears in the toolbox, you should skip the next section.

To add your control to the toolbox

  1. Right-click the Toolbox and choose Add/Remove Items from the shortcut menu.

    The Customize Toolbox dialog box opens.

  2. Choose the .NET Framework Components tab and click Browse. Browse to the ValueButtonLib\bin\debug folder and select ValueButton.dll.

    ValueButton appears in the list of components in the Customize Toolbox dialog box.

  3. In the Customize Toolbox dialog box, check the box next to ValueButton and close the window.

    The ValueButton is added to the tab of the Toolbox that was selected.

To add your control to the form

  1. In Solution Explorer, right-click Form1.cs and choose View Designer from the shortcut menu.
  2. In Toolbox, scroll down until you come to the icon labeled ValueButton. Double-click this icon.

    A ValueButton appears on the form.

  3. Right-click the ValueButton and select Properties from the shortcut menu.
  4. In the Properties window, examine the properties of this control. Note that they are identical to the properties exposed by a standard button, except that there is an additional property, ButtonValue.
  5. Set the ButtonValue property to 5.
  6. In the Windows Forms tab of the Toolbox, double-click Label to add a Label control to your form.
  7. Relocate the label to the center of the form.
  8. Double-click valueButton1.

    The Code Editor opens to the valueButton1_Click event.

  9. Type the following line of code.
    label1.Text = valueButton1.ButtonValue.ToString();
  10. In Solution Explorer, right-click Test, and choose Set as Startup Project from the shortcut menu.
  11. From the Debug menu, select Start.

    Form1 appears.

  12. Click valueButton1.

The numeral '5' is displayed in Label1, demonstrating that the ButtonValue property of your inherited control has been passed to Label1 via the ValueButton1_Click method. Thus your ValueButton control inherits all the functionality of the standard Windows Forms button, but exposes an additional, custom property.

See Also

Programming with Components | Component Authoring Walkthroughs | Displaying Your Control in the Customize Toolbox Dialog Box | Walkthrough: Authoring a User Control with Visual C#