Rendering an ASP.NET Server Control

Rendering refers to the process of creating a visual representation on a display surface. In the case of Web requests, the actual rendering is performed by a client's Web browser or other viewing device. The task of the ASP.NET page framework is to send HTML (or text in another markup language such as XML or WML) in response to a Web request. The task of a page (and its child controls) is to write the markup content to an output stream. For this purpose, the base class System.Web.UI.Control provides the Render method, which has the following signature.

protected virtual void Render(HtmlTextWriter writer);
[Visual Basic]
Overridable Protected Sub Render(ByVal writer As HtmlTextWriter)

The System.Web.UI.HtmlTextWriter class encapsulates an output stream for writing markup content. In the simplest case, a control author can override Render to pass HTML (or other markup content) as a string argument to the Write method of an instance of HtmlTextWriter.

protected override void Render(HtmlTextWriter output) {
    output.Write ("<h3> Hello </h3>");
}
[Visual Basic]
Protected Overrides Sub Render(output As HtmlTextWriter)
    output.Write("<h3> Hello </h3>")
End Sub

HtmlTextWriter provides many utility methods that simplify HTML writing. You should use these methods instead of directly passing text strings to Write because they make code more readable and reusable (and do not require a developer to be proficient in the details of HTML syntax). See the HtmlTextWriter class for examples of these utility methods. HtmlTextWriter also provides automatic conversions between different versions of HTML for uplevel or downlevel rendering.

It is more efficient to make multiple calls to HtmlTextWriter.Write than to concatenate strings and pass one single string argument to the Write method.

**Note   **For simplicity, several samples in the documentation pass text strings directly to HtmlTextWriter.Write. However, in your controls, you should use the utility methods of HtmlTextWriter.

The base Control class provides a RenderChildren method for rendering content from its child controls (if any).

protected virtual void RenderChildren(HtmlTextWriter writer);
[Visual Basic]
Overridable Protected Sub RenderChildren(ByVal writer As HtmlTextWriter)

A composite control can render content in addition to that rendered by its child controls by rendering that content before or after invoking the RenderChildren method. The following code fragment shows an example.

public class Composite : Control {
    ...
    protected override void Render(HtmlTextWriter writer) {
       writer.Write ("My child controls are rendered below.");
       RenderChildren(writer);
       writer.Write ("My child controls are rendered above.");
    }
}
[Visual Basic]
Public Class Composite
   Inherits Control
   ...
   Protected Overrides Sub Render(writer As HtmlTextWriter)
      writer.Write("My child controls are rendered below.")
      RenderChildren(writer)
      writer.Write("My child controls are rendered above.")
   End Sub
End Class

The base Control class's implementation of Render always invokes RenderChildren. If you do not want a control's child controls to be rendered, override RenderChildren to do nothing, as shown in the following code fragment.

protected override void RenderChildren(HtmlTextWriter writer) {
    // Do nothing so that child controls are not rendered.
}
[Visual Basic]
Protected Overrides Sub RenderChildren(writer As HtmlTextWriter)
    ' Do nothing so that child controls are not rendered.
End Sub

Rendering Methods in WebControl

In addition to the rendering methods provided by the base class Control, the System.Web.UI.WebControls.WebControl class provides several other methods to facilitate rendering.

The AddAttributesToRender method allows a control that derives from WebControl to specify additional HTML attributes and cascading style-sheet styles to be rendered. The following example shows how a button control can write its attributes to the output stream. Note the call to base.AddAttributestoRender, which ensures that the attributes rendered by the base class are preserved.

protected override void AddAttributesToRender(HtmlTextWriter writer) {
    writer.AddAttribute(HtmlTextWriterAttribute.Type, "submit");
    writer.AddAttribute(HtmlTextWriterAttribute.Name, UniqueID);
    writer.AddAttribute(HtmlTextWriterAttribute.Value, Text);
    base.AddAttributesToRender(writer);
}
[Visual Basic]
Protected Overrides Sub AddAttributesToRender(writer As HtmlTextWriter)
    writer.AddAttribute(HtmlTextWriterAttribute.Type, "submit")
    writer.AddAttribute(HtmlTextWriterAttribute.Name, UniqueID)
    writer.AddAttribute(HtmlTextWriterAttribute.Value, [Text])
    MyBase.AddAttributesToRender(writer)
End Sub

The RenderBeginTag and RenderEndTag methods enable a control that derives from WebControl to override the beginning and ending HTML element tags. The RenderContents method enables a control to specify the content within the tags.

Note   To write text to the output stream of a Web server control (a class that derives from WebControl), you should override the RenderContents method rather than overriding the Render method directly. This ensures that the rendering functionality implemented by WebControl (such as emitting attributes) is preserved. For details, see Rendering a Server Control Samples.

See Also

Maintaining State in a Control | Rendering a Server Control Samples