This documentation is archived and is not being maintained.

ControlAdapter Class

Customizes rendering for the derived control to which the adapter is attached, to modify the default markup or behavior for specific browsers, and is the base class from which all control adapters inherit.

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

Public MustInherit Class ControlAdapter

The ControlAdapter type exposes the following members.

Protected methodControlAdapterInfrastructure. Initializes a new instance of the ControlAdapter class.

Protected propertyBrowserGets a reference to the browser capabilities of the client making the current HTTP request.
Protected propertyControlGets a reference to the control to which this control adapter is attached.
Protected propertyPageGets a reference to the page where the control associated with this adapter resides.
Protected propertyPageAdapterGets a reference to the page adapter for the page where the associated control resides.

Protected methodBeginRenderCalled prior to the rendering of a control. In a derived adapter class, generates opening tags that are required by a specific target but not needed by HTML browsers.
Protected methodCreateChildControlsCreates the target-specific child controls for a composite control.
Protected methodEndRenderCalled after the rendering of a control. In a derived adapter class, generates closing tags that are required by a specific target but not needed by HTML browsers.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodLoadAdapterControlStateLoads adapter control state information that was saved by SaveAdapterControlState during a previous request to the page where the control associated with this control adapter resides.
Protected methodLoadAdapterViewStateLoads adapter view state information that was saved by SaveAdapterViewState during a previous request to the page where the control associated with this control adapter resides.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnInitOverrides the OnInit method for the associated control.
Protected methodOnLoadOverrides the OnLoad method for the associated control.
Protected methodOnPreRenderOverrides the OnPreRender method for the associated control.
Protected methodOnUnloadOverrides the OnUnload method for the associated control.
Protected methodRenderGenerates the target-specific markup for the control to which the control adapter is attached.
Protected methodRenderChildrenGenerates the target-specific markup for the child controls in a composite control to which the control adapter is attached.
Protected methodSaveAdapterControlStateSaves control state information for the control adapter.
Protected methodSaveAdapterViewStateSaves view state information for the control adapter.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

Control adapters are components that override certain Control class methods and events in its execution lifecycle to allow browser or markup-specific handling. The .NET Framework maps a single derived control adapter to a Control object for each client request.

An adapter modifies a control for a specific browser or class of browsers or acts as an arbitrary filter on some capability. Typically the adapter is defined by the markup language that the browser uses (for example, XHTML or HTML 3.2). Much of the adaptability in rendering behavior can be encapsulated in the specialized classes that derive from the HtmlTextWriter class. Therefore, it is likely that a single adapter can be used for a number of browser class behaviors or that inclusion of the adaptability in the HtmlTextWriter classes could make the use of a control adapter unnecessary.

An adapter for a control class applies to all controls that inherit from that class, unless more specialized adapters are present. For example, an adapter for the BaseValidator class can be used for all Validator objects.

Adapters typically do not inherit directly from the ControlAdapter class, but from one of the target-specific adapter base classes that provide additional functionality specific to the control type and target browser or the particular rendering required.

Controls themselves do not necessarily require an adapter. If controls are extended through composition, generally the child control adapters are sufficient.

Each control has explicit mappings to adapters through the .browser definition files. Thus, any access to the Control.Adapter property uses the HttpBrowserCapabilities object extracted from the browser definition files to perform the lookup for the mapping of the adapter to control.

During processing, the .NET Framework intercepts calls to the overridable methods of a control that could be target-specific. If a control adapter is attached, the .NET Framework calls the associated adapter methods.

The adapter performs rendering for the control through the Render method. If overridden, Render potentially should not call the base class implementation because that performs a call back on the Control.Render method. This might cause the rendering to occur twice, once by the adapter and once by the control.

The Render base method calls back on the Control.Render method of the control. Thus, if you override Render, you should not call the base class implementation unless the rendering you implement is in addition to that provided by Control.Render of the control.

You must ensure that the .NET Framework performs interception for adapters of the child controls. You can do this by calling the RenderChildren base method, which calls the Control.RenderChildren method of the control, from your Render override.

The BeginRender and EndRender methods are called by the control immediately before and after (respectively) the control calls the Render method. If pre- and post-rendering are the only browser-specific processing tasks required, using BeginRender and EndRender might make it unnecessary to override Render. The default behavior of the BeginRender and EndRender methods is to call the corresponding methods of the HtmlTextWriter.

To maintain its own state information, a control adapter can override the SaveAdapterControlState, LoadAdapterControlState, SaveAdapterViewState, and LoadAdapterViewState methods. SaveAdapterControlState, SaveAdapterViewState, LoadAdapterControlState, and LoadAdapterViewState are called when the private control and view states are saved and loaded, respectively.

The OnInit, OnLoad, OnPreRender, and OnUnload base methods call back on the corresponding Control class methods. Thus, any of these ControlAdapter methods that are overridden must call their base methods; otherwise, the event associated with the Control class method will not be raised.

Controls and adapters optionally implement the IPostBackDataHandler and IPostBackEventHandler interfaces. The .NET Framework determines whether an adapter exists and whether the adapter implements these interfaces. If it does, the adapter should override the LoadPostData, RaisePostDataChangedEvent, and RaisePostBackEvent methods, as necessary. If the postback data is not recognized in the adapter, it must call back on the control to process it. Subsequent event handlers also must call back on the control.

Notes to Inheritors

When you inherit from the ControlAdapter class, a control that requires general adapter functionality should have a corresponding adapter base class, named in the pattern ControlTypeAdapter (for example, TextBoxAdapter). The adapter should at a minimum return a strongly-typed instance of the control through its Control property.

  1. Control adapters for a given control type and markup language should be named in the pattern MarkupControlTypeAdapter (for example, XhtmlTextBoxAdapter). Adapters for a control should be implemented in an Adapters subnamespace.

Control adapters should inherit from the appropriate base class and follow the same inheritance model as the control. For example, an adapter for a control inheriting from the Control base class should inherit from either the ControlAdapter class or the relevant ControlTypeAdapter class.

Any specialized adapters should be defined for the specialized control under all of the device nodes in configuration .browser files.

A properly implemented control should not assume that an adapter is attached, or that the attached adapter implements a specific interface. Instead, it should check for these before calling.

It is possible to simulate overriding protected event methods in the control, such as the OnClick method of the LinkButton. First, create an adapter class with an OnClick method. Then create a new control derived from LinkButton and override the OnClick method. The overriden OnClick method calls the OnClick method of the adapter. The adapter object is available through the protected Adapter property of the Control class. The Adapter property of the control is Nothing when there is no associated adapter, so any code should check for that condition before calling methods of the adapter.

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.