Creating Reusable Controls for Web Parts or Application Pages

In Visual Studio, you can create custom, reusable controls that can be consumed by application pages and Web Parts that run in SharePoint. These controls are called user controls. For more information about user controls, see ASP.NET User Controls.

Creating a User Control

To create a user control, add a User Control to an Empty SharePoint Project. For more information, see How to: Create a User Control for a SharePoint Application Page or Web Part.

When you add a User Control item, Visual Studio creates a folder in your project, and then adds several files to the folder. The following table describes each file.

File	Description
User control file	Defines the user control. Design the user control by adding controls and markup to this file.
Code file	Contains code behind the user control. Add code to handle events to this file.
Designer code file	Contains code generated by the designer and should not be directly edited.

Designing the User Control

Design the user control by using the Visual Web Developer designer in Visual Studio. This designer appears when you open the user control file in your project and choose the Design tab. For more information about using this designer, see Working with Visual Web Developer.

Consuming the User Control

User controls do not appear in SharePoint until you include them in an application page or a Web Part.

To include a user control in an application page add an @ Register directive to the application page, and then declare the user control inside of one or more content placeholders in the page. For an example of how to accomplish this task in a standard ASP.NET Web page, see How to: Include a User Control in an ASP.NET Web Page.

To include a user control in a Web Part, add the user control to the Web Part Controls collection in the Web Part code file. The following example adds a user control to the Controls collection of a Web Part.

<ToolboxItemAttribute(false)> _
Public Class VisualWebPart1
    Inherits WebPart

    Private Const _ascxPath As String = "~/_CONTROLTEMPLATES/VB/VisualWebPart1/VisualWebPart1UserControl.ascx" 

    Public Sub New()
    End Sub 

    Protected Overrides Sub CreateChildControls()
        Dim control As Control = Page.LoadControl(_ascxPath)
        Controls.Add(control)
        MyBase.CreateChildControls()
    End Sub 

    Protected Overrides Sub RenderContents(ByVal writer As HtmlTextWriter)
        MyBase.RenderContents(writer)
    End Sub 

End Class

[ToolboxItemAttribute(false)]
public class VisualWebPart1 : WebPart
{
    private const string _ascxPath = @"~/_CONTROLTEMPLATES/CS/VisualWebPart1/VisualWebPart1UserControl.ascx";

    public VisualWebPart1()
    {
    }

    protected override void CreateChildControls()
    {
        Control control = this.Page.LoadControl(_ascxPath);
        Controls.Add(control);
        base.CreateChildControls();
    }

    protected override void RenderContents(HtmlTextWriter writer)
    {
        base.RenderContents(writer);
    }

}

Debugging a User Control

To debug a user control, ensure that the user control is included in an application page or Web Part in your SharePoint project. You can then debug code in the user control just as you would debug code in any Visual Studio Project.

When you start the Visual Studio debugger, Visual Studio opens the SharePoint site.

In SharePoint, open the application page that includes the user control. If the user control is included in a Web Part, add the Web Part to a Web Part page in SharePoint.

For more information about debugging SharePoint projects, see Troubleshooting SharePoint Solutions.

Related Topics

Title	Description
How to: Create a User Control for a SharePoint Application Page or Web Part	Shows you how to create custom, reusable controls that can be consumed by application pages and Web Parts that run in SharePoint.
Working with Visual Web Developer	Describes how to use the designer that appears when you open a Web page in your project.