Creating Reusable Controls for Web Parts or Application Pages

Visual Studio enables you to 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.

Designing the User Control

Design the user control by using the Visual Web Developer designer in Visual Studio. This designer appears when you double-click the user control file in your project. For more information about using this designer, see Visual Web Developer Content Map.

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