Implementing a Simple Web Forms Control Designer

Article
10/17/2014

A Web Forms designer class controls the design-time appearance of a control by providing design-time HTML to a designer host. The .NET Framework provides a base designer class, System.Web.UI.ControlDesigner, that provides base functionality for a server control designer. ControlDesigner defines the following key methods for rendering design-time HTML.

Public Class ControlDesigner
   Inherits HtmlControlDesigner
   Public Overridable Function GetDesignTimeHtml() As String
      ...
   End Function
    
   Protected Overridable Function GetEmptyDesignTimeHtml() As String
      ...
   End Function

   Protected Overridable Function GetErrorDesignTimeHtml(e As Exception) As String
      ...
   End Function
   
   ' The helper method that provides default placeholder HTML
   ' cannot be overridden. Invoke this method when it is not possible to 
   ' render a meaningful representation of the control at design time.
   Protected Function CreatePlaceHolderDesignTimeHtml(s As String) As String
      ...
   End Function 
End Class
[C#]
public class ControlDesigner : HtmlControlDesigner {
    public virtual string GetDesignTimeHtml() {...}
    protected virtual string GetEmptyDesignTimeHtml() {...}
    protected virtual string GetErrorDesignTimeHtml(Exception e) {...}

    // The helper method that provides default placeholder HTML
    // cannot be overridden. Invoke this method when it is not possible to 
    // render a meaningful representation of the control at design time.
    protected string CreatePlaceHolderDesignTimeHtml(string s) {...}
}

The GetDesignTimeHtml method returns design-time HTML for a control. The base implementation of GetDesignTimeHtml invokes the Render method of the control, thereby rendering the same HTML at design time as at run time. The task of the designer is to override GetDesignTimeHtml so as to render HTML that is more appropriate at design time.

The GetEmptyDesignTimeHtml method supplies an HTML string to render at design time if the run-time HTML string rendered by the control is empty, such as when properties are not set. The base implementation of the GetEmptyDesignTimeHtml method returns the fully qualified name and ID of the control. A designer can override this method and invoke CreatePlaceHolderDesignTimeHtml, or it can return alternate HTML.

The GetErrorDesignTimeHtml method provides the HTML to be used for the design-time representation of the control when an error is encountered.

To implement a simple Web Forms control designer

Define a class that derives directly or indirectly from System.Web.UI.ControlDesigner.
(Optional) Override the GetDesignTimeHtml method inherited from ControlDesigner.
(Optional) Override the GetEmptyDesignTimeHtml method inherited from ControlDesigner.
(Optional) Override the GetErrorDesignTimeHtml method inherited from ControlDesigner.

The Web Forms Templated Data-Bound Control Designer Sample contains an example of a nontrivial designer that overrides these methods.

The following code sample shows a trivial designer (SimpleDesigner) for a simple ASP.NET server control (Simple), which is defined at the end of this topic. Simple has a Text property that it renders at run time as a text string. SimpleDesigner performs one simple task — it renders the Text property of Simple as a hyperlink at design time, thus making the design-time representation different from the run-time representation.

Imports System
Imports System.IO
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.Design
Imports System.Web.UI.WebControls
Imports CustomControls

Namespace CustomControls.Design
   Public Class SimpleDesigner
      Inherits System.Web.UI.Design.ControlDesigner
      
      
      Public Overrides Function GetDesignTimeHtml() As String
         ' Component is the instance of the component or control that
         ' this designer object is associated with. This property is 
         ' inherited from System.ComponentModel.ComponentDesigner.
         Dim simple As Simple = CType(Component, Simple)
         
         If simple.Text.Length > 0 Then
            Dim sw As New StringWriter()
            Dim tw As New HtmlTextWriter(sw)
            
            Dim placeholderLink As New HyperLink()
            
            ' Put simple.Text into the link's Text.
            placeholderLink.Text = simple.Text
            placeholderLink.NavigateURL = simple.Text
            placeholderLink.RenderControl(tw)
            
            Return sw.ToString()
         Else
            Return GetEmptyDesignTimeHtml()
         End If
      End Function
   End Class
End Namespace
[C#]
using System;
using System.IO;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.Design;
using CustomControls;

namespace CustomControls.Design {
   public class SimpleDesigner : System.Web.UI.Design.ControlDesigner {
      
   public override string GetDesignTimeHtml() {
         // Component is the instance of the component or control that
         // this designer object is associated with. This property is 
         // inherited from System.ComponentModel.ComponentDesigner.
         Simple simple = (Simple) Component;

         if (simple.Text.Length > 0) {
            StringWriter sw = new StringWriter();
            HtmlTextWriter tw = new HtmlTextWriter(sw);

            HyperLink placeholderLink = new HyperLink();
            
            // Put simple.Text into the link's Text.
            placeholderLink.Text = simple.Text;
            placeholderLink.NavigateURL = simple.Text;
            placeholderLink.RenderControl(tw);

            return sw.ToString();
         }
         else
            return GetEmptyDesignTimeHtml();
      }
   }
}

The code for Simple follows. The DesignerAttribute is shown in bold.

Imports System
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.ComponentModel

Namespace CustomControls
   <Designer("CustomControls.Design.SimpleDesigner, CustomControls.Design")> _
   Public Class Simple
      Inherits WebControl
      
      Private _text As String
      
      Public Property [Text]() As String
         Get
            Return _text
         End Get
         Set
            _text = value
         End Set
      End Property
       
      Protected Overrides Sub RenderContents(writer As HtmlTextWriter)
         writer.Write([Text])
      End Sub
   End Class
End Namespace
[C#]
using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.ComponentModel;

namespace CustomControls {

    [     Designer("CustomControls.Design.SimpleDesigner, CustomControls.Design")    ]
    public class Simple : WebControl {

        private string text;
        public string Text {
            get { return text; }
            set { text = value; }
        }

        protected override void RenderContents(HtmlTextWriter writer) {
                writer.Write(Text);
        }
    }
}

Implementing a Simple Web Forms Control Designer

See Also

Additional resources