TemplateControl.LoadControl Method (String) (System.Web.UI)

Switch View

LoadControl Method (String)

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

TemplateControl..::.LoadControl Method (String)

Loads a Control object from a file based on a specified virtual path.

Namespace: System.Web.UI
Assembly: System.Web (in System.Web.dll)

Syntax

Visual Basic (Declaration)

Public Function LoadControl ( _
    virtualPath As String _
) As Control

Visual Basic (Usage)

Dim instance As TemplateControl
Dim virtualPath As String
Dim returnValue As Control

returnValue = instance.LoadControl(virtualPath)

public Control LoadControl(
    string virtualPath
)

Visual C++

public:
Control^ LoadControl(
    String^ virtualPath
)

JScript

public function LoadControl(
    virtualPath : String
) : Control

Parameters

virtualPath: Type: System..::.String
The virtual path to a control file.

Return Value

Type: System.Web.UI..::.Control
Returns the specified Control.

Exceptions

Exception	Condition
ArgumentNullException	The virtual path is nullNothingnullptra null reference (Nothing in Visual Basic) or empty.

Remarks

If the control supports caching, the object returned from the LoadControl method is not actually a Control object; rather, it is a PartialCachingControl object. If the virtualPath parameter is relative, the path of the loaded control is relative to the path of the TemplateControl.

When you load a control into a container control, the container raises all of the added control's events until it has caught up to the current event. However, the added control does not catch up with postback data processing. For an added control to participate in postback data processing, including validation, the control must be added in the Init event rather than in the Load event.

Examples

The following code example demonstrates how to use the LoadControl method to add a user control to an ASP.NET page.

In the OnInit event method, this page uses the LoadControl method to programmatically create a user control on the page. The method adds the control to the Controls property of a PlaceHolder Web server control named Placeholder1.

For the definition of the MyControl class that is used in this code example, see TemplateControl.

Visual Basic

Sub Page_Load(ByVal Sender As Object, ByVal e As EventArgs)
    ' Obtain a UserControl object MyControl from the
    ' user control file TempControl_Samples1.ascx.vb
    Dim myControl1 As MyControl = CType(LoadControl("TempControl_Samples1.vb.ascx"), MyControl)
    Controls.Add(myControl1)
End Sub

void Page_Init(object sender, System.EventArgs e)
{
    // Instantiate the UserControl object
    MyControl myControl1 =
        (MyControl)LoadControl("TempControl_Samples1.ascx.cs");
    PlaceHolder1.Controls.Add(myControl1);
}

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

Reference

TemplateControl Class

TemplateControl Members

LoadControl Overload

System.Web.UI Namespace

Other Resources

ASP.NET Page Life Cycle Overview