Composite Control vs. User Control

The following table summarizes the differences between composite controls and user controls. For details about authoring a user control, see Web Forms User Controls.

Composite Control User Control
Minimal design-time support for authoring. Full design-time support for authoring. Authoring a user control in a visual designer is no different from authoring an ASP.NET page (Web Forms page).
Authored programmatically in an object-oriented programming language that targets the common language runtime, such as C# or Visual Basic .NET. Authored declaratively using ASP.NET page syntax and script blocks (or code-behind pages).
Note   The languages used for authoring the script blocks are object-oriented languages that target the common language runtime, such as C#, Visual Basic .NET, and JScript .NET; however, the ASP.NET page framework hides many programming details from the developer.
Compiled and persisted as an assembly (.dll). Saved as a text file with an .ascx extension (with an optional code-behind file).
Well suited to authoring generic redistributable controls. Geared toward application-specific functionality.
Full design-time support when used in a design-time host. A composite control can be added to the toolbox of a visual designer and dragged and dropped onto a page. Minimal support for use in a designer.

Note   If you want to extend the functionality of a single control, for instance Label, do not create a composite control or a user control. In that case, you should derive from Label (to get the benefits of inheritance and polymorphism) and add or override members. If you create a user control (or composite control) that contains only one control, Label, your new control no longer has the object model of Label. You should create a user control (or a composite control) only when you want to combine multiple existing controls.

The following sample shows a user control that is equivalent to the composite control developed in the Composite Server Control Sample. The user control raises a custom event named Check. The event delegate CheckEventHandler and the event data class CheckEventArgs, which are used by the Check event, are defined in the Composite Server Control Sample.

<%-- UserControl.ascx. --%>
<%-- The namespace CustomControls has to be imported because it contains
 CheckEventArgs and CheckEventHandler.  --%>
<%@Import Namespace = "CustomControls" %> 
<script language="VB" runat=server>
   Private ReadOnly Property Sum() As Integer
      Get
         EnsureChildControls()
         Return Int32.Parse(box1.Text) + Int32.Parse(box2.Text)
      End Get
   End Property

   Public Number As Integer = 100

   Public Property Text() As String
      Get
         EnsureChildControls()
         Return label.Text
      End Get
      Set
         EnsureChildControls()
         label.Text = value
      End Set
   End Property

   Public Event Check As CheckEventHandler

   Protected Overridable Sub OnCheck(e As CheckEventArgs)
      RaiseEvent Check(Me, e)
   End Sub

   Private Sub Button_Clicked(sender As Object, e As EventArgs)
      OnCheck(New CheckEventArgs(Sum - Number))
   End Sub 
</script>
<h3>Enter a number :

<asp:TextBox id = box1 text = "0" runat = server />
</h3> <br>
<h3>Enter another number :
<asp:TextBox id = box2 text = "0" runat = server />
</h3> <br>       
<asp:Button id = button text = "Submit" OnClick = "Button_Clicked" runat = server />
<br> <br>
<asp:Label id = label text = "Click sumbit to  see if you won." 
height = 100 width = 400 runat = server />                     

Using a User Control on a Page

The following page uses the user control UserControl.ascx on an ASP.NET page. For more details, see Including a User Control in a Web Forms Page.

<%@Import Namespace = "CustomControls" %>
<%@ Register TagPrefix="MyUserControl"  TagName = "MyControl" Src = "UserControl.ascx" %>
<script language="VB" runat=server>
   Private Sub Sum_Checked(sender As Object, e As CheckEventArgs)
      If e.Match = True Then
         control.Text = "<h2> You won a million dollars!!!! </h2>"
      Else
         control.Text = "Sorry, try again. The numbers you entered don't add up to" & _
               " the hidden number."
      End If
   End Sub 
</script>

<html>            
<body>
<h1> The mystery sum game </h1><br>             
<form runat=server>                        
<MyUserControl:MyControl id = "control" OnCheck = "Sum_Checked" Number = "10" runat = server/>                                                   
</form>                                               
</body>                                         
</html>

See Also

Composite Server Control Sample | Composition vs. Rendering