Create reusable controls for web parts or application pages

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

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. A user control is a kind of composite control that works much like an ASP.NET Web page—you can add existing Web server controls and markup to a user control, and define properties and methods for the control. You can then embed them in ASP.NET Web pages, where they act as a unit.

Create 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.

Design 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.

Consume 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, open the Web page to which you want to add the ASP.NET user control. Switch to Design view, then select your custom user control file in Solution Explorer, and drag it onto the page. The ASP.NET user control is added to the page, and the designer creates the @ Register directive, which is required for the page to recognize the user control. You can now work with the control's public properties and methods.

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);
    }
    
}

Debug 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 Troubleshoot 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.