ptg 1574 CHAPTER 35 Deploying ASP.NET Web Applications applications along with all their configuration, dependencies, and prerequisites. These packages can be deployed to IIS servers by developers, administrators, or command-line scripts and dramatically ease the burden of deploying web applications. In addition, we also have the ability to create one-click publication profiles that enable us to take these web packages and deploy them on-demand just by clicking a button inside Visual Studio. When you have gotten over the joy of building your new ASP.NET 4 application, it’s going to get even more fun when you see how easy it is to deploy and manage these applications. From the Library of Wow! eBook ptg CHAPTER 36 Building Custom Controls IN THIS CHAPTER . Overview of Custom Control Building . View State and Control State . Processing Postback Data and Events . Working with Control Property Collections . Creating a Better Designer Experience . Summary In this chapter, you learn how to extend ASP.NET Framework by building custom controls. You learn how to create controls in exactly the same way that Microsoft devel- oped the standard ASP.NET controls, such as the TextBox and Button controls. Although the standard toolbox of controls available to developers is full of useful controls, you might need something more specific for your application, or you might intend to build controls available throughout your organization or for resale to other developers. Overview of Custom Control Building Answer two questions before writing a custom control: . What type of control do I want to write? . From what class do I inherit? The two basic types of controls are fully rendered and composite controls. When you build a fully rendered control, you start from scratch. You specify all the HTML content that the control renders to the browser. When you create a composite control, on the other hand, you build a new control from existing controls. For example, you can create a composite AddressForm control from existing TextBox and RequiredFieldValidator controls. When you create a composite control, you bundle together existing controls as a new control and potentially add new behaviors and properties. From the Library of Wow! eBook ptg 1576 CHAPTER 36 Building Custom Controls The second question that you must address is the choice of the base control for your new control. You can inherit a new control from any existing ASP.NET control. For example, if you want to create a better GridView control, you can inherit a new control from the GridView control and add additional properties and methods to your custom GridView control. Typically, when building a basic control, you inherit your new control from one of the following base classes (or from a control that derives from one of these): . System.Web.UI.Control . System.Web.UI.WebControls.WebControl . System.Web.UI.WebControls.CompositeControl The CompositeControl class inherits from the WebControl class, which inherits from the Control class. Each of these base classes adds additional functionality. The base class for all controls in ASP.NET Framework is the System.Web.UI.Control class. Every control, including the TextBox and GridView controls, ultimately derives from this control. This means that all the properties, methods, and events of the System.Web.UI.Control class are shared by all controls in the Framework. All Web controls inherit from the base System.Web.UI.WebControls.WebControl class. The difference between the Control class and WebControl class is that controls that derive from the WebControl class always have opening and closing tags. Because a WebControl has an opening and closing tag, you also get more formatting options. For example, the WebControl class includes BackColor, Font, and ForeColor properties. For example, the ASP.NET Literal control inherits from the base Control class, whereas the Label control inherits from the base WebControl class. The Repeater control inherits from the base Control class, whereas the GridView control (ultimately) inherits from the WebControl class. Finally, the System.Web.UI.WebControls.CompositeControl should be used as the base class for any composite control. The CompositeControl automatically creates a naming container for its child controls. It also includes an overridden Controls property that forces child controls to appear in Design view. Building Fully Rendered Controls Let’s start by creating a simple fully rendered control. When you create a fully rendered control, you take on the responsibility of specifying all the HTML content that the control renders to the browser. The file in Listing 36.1 contains a fully rendered control that derives from the base Control class. From the Library of Wow! eBook ptg 1577 Overview of Custom Control Building LISTING 36.1 FullyRenderedControl.cs using System.Web.UI; namespace myControls { public class FullyRenderedControl : Control { private string _Text; public string Text { get { return _Text; } set { _Text = value; } } protected override void Render(HtmlTextWriter writer) { writer.Write(_Text); } } } NOTE Add the control in Listing 36.1 to your App_Code folder. Any code added to the App_Code folder is compiled dynamically. The control in Listing 36.1 inherits from the base Control class, overriding the base class Render() method. The control simply displays whatever value that you assign to its Text property. The value of the Text property is written to the browser with the HtmlTextWriter class’s Write() method. The file in Listing 36.2 illustrates how you can use the new control in a page. LISTING 36.2 ShowFullyRenderedControl.aspx <%@ Page Language=”C#” %> <%@ Register TagPrefix=”custom” Namespace=”myControls” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” ➥ “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml” > <head id=”Head1” runat=”server”> 36 From the Library of Wow! eBook ptg 1578 CHAPTER 36 Building Custom Controls <title>Show Fully Rendered Control</title> </head> <body> <form id=”form1” runat=”server”> <div> <custom:FullyRenderedControl ID=”FullyRenderedControl1” Text=”Hello World!” runat=”Server” /> </div> </form> </body> </html> NOTE In Listing 36.2, the custom control is registered in the page through use of the <%@ Register %> directive. Alternatively, you can register the control for an entire website by registering the control in the <pages> section of the web configuration file. If you open the page in Listing 36.2 in a browser and select View Source, you can see the HTML rendered by the control. The control simply renders the string ”Hello World!”. Rather than inherit from the base Control class, you can create a fully rendered control by inheriting a new control from the base WebControl class. When inheriting from the WebControl class, you override the RenderContents() method instead of the Render() method. For example, the control in Listing 36.3 contains a simple, fully rendered control that inherits from the WebControl class. LISTING 36.3 FullyRenderedWebControl.cs using System.Web.UI; using System.Web.UI.WebControls; namespace myControls { public class FullyRenderedWebControl : WebControl { private string _Text; public string Text From the Library of Wow! eBook ptg 1579 Overview of Custom Control Building { get { return _Text; } set { _Text = value; } } protected override void RenderContents(HtmlTextWriter writer) { writer.Write(_Text); } } } The page in Listing 36.4 illustrates how you can use the new control (see Figure 36.1). The BackColor, BorderStyle, and Font properties are set. Because the control in Listing 36.3 derives from the base WebControl class, you get these properties for free. 36 FIGURE 36.1 Displaying a fully rendered WebControl. LISTING 36.4 ShowFullyRenderedWebControl.aspx <%@ Page Language=”C#” %> <%@ Register TagPrefix=”custom” Namespace=”myControls” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” ➥ “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml” > From the Library of Wow! eBook ptg 1580 CHAPTER 36 Building Custom Controls <head id=”Head1” runat=”server”> <title>Show Fully Rendered WebControl</title> </head> <body> <form id=”form1” runat=”server”> <div> <custom:FullyRenderedWebControl ID=”FullyrenderedWebControl1” Text=”Hello World” BackColor=”Yellow” BorderStyle=”Dashed” Font-Size=”32px” Runat=”Server” /> </div> </form> </body> </html> After opening the page in Listing 36.4, if you select View Source in your browser, you can see the rendered output of the control. It looks like this: <span id=”FullyrenderedWebControl1” style=”display:inline-block; ➥ background-color:Yellow;border-style:Dashed; ➥ font-size:32px;”>Hello World</span> A WebControl, unlike a control, renders an enclosing <span> tag by default. Understanding the HtmlTextWriter Class When you create a fully rendered control, you use the HtmlTextWriter class to write the HTML content to the browser. The HtmlTextWriter class was specifically designed to make it easier to render HTML. Here is a partial list of the methods supported by this class: . AddAttribute()—Adds an HTML attribute to. the tag rendered by calling RenderBeginTag(). . AddStyleAttribute()—Adds a CSS attribute to the tag rendered by a call to RenderBeginTag(). . RenderBeginTag()—Renders an opening HTML tag. . RenderEndTag()—Renders a closing HTML tag. . Write()—Renders a string to the browser. . WriteBreak()—Renders a <br /> tag to the browser. From the Library of Wow! eBook ptg 1581 Overview of Custom Control Building You can call the AddAttribute() or the AddStyleAttribute() method as many times as you please before calling RenderBeginTag(). When you call RenderBeginTag(), all the attributes are added to the opening HTML tag. The methods of the HtmlTextWriter class can use the following enumerations: . HtmlTextWriterTag—Contains a list of the most common HTML tags. . HtmlTextWriterAttribute—Contains a list of the most common HTML attributes. . HtmlTextWriterStyle—Contains a list of the most Cascading Style Sheet attributes. When using the methods of the HtmlTextWriter class, you should strive to use these enumerations to represent HTML tags and attributes. If a particular tag or attribute is missing from one of the enumerations, you can pass a string value instead. For example, the control in Listing 36.5 renders a table of HTML colors by using an HTML table (see Figure 36.2). The RenderContents() method takes advantage of the methods of the HtmlTextWriter class to render the HTML table. 36 FIGURE 36.2 Displaying a table of HTML colors. LISTING 36.5 ColorTable.cs using System; using System.Web.UI; using System.Web.UI.WebControls; using System.Drawing; From the Library of Wow! eBook ptg 1582 CHAPTER 36 Building Custom Controls namespace myControls { public class ColorTable : WebControl { protected override void RenderContents(HtmlTextWriter writer) { // Get list of colors KnownColor[] colors = (KnownColor[])Enum.GetValues(typeof(KnownColor)); // Render opening table tag writer.AddAttribute(HtmlTextWriterAttribute.Border, “1”); writer.RenderBeginTag(HtmlTextWriterTag.Table); // Render table body foreach (KnownColor colorName in colors) { writer.RenderBeginTag(HtmlTextWriterTag.Tr); // Render first column writer.RenderBeginTag(HtmlTextWriterTag.Td); writer.Write(colorName); writer.RenderEndTag(); // Render second column writer.AddAttribute(HtmlTextWriterAttribute.Width, “50px”); writer.AddAttribute(HtmlTextWriterAttribute.Bgcolor, colorName.ToString()); writer.RenderBeginTag(HtmlTextWriterTag.Td); writer.Write(“ ”); writer.RenderEndTag(); writer.RenderEndTag(); } // close table writer.RenderEndTag(); } } } You should notice a number of things about the control in Listing 36.5. First, the AddAttribute() method is called to add the table border attribute. When the RenderBeginTag() method is called, the table border attribute is added to the opening table tag. From the Library of Wow! eBook ptg 1583 Overview of Custom Control Building 36 Furthermore, you do not specify the tag when calling the RenderEndTag() method. This method automatically closes the last tag opened with the RenderBeginTag() method. NOTE The downloadable code on the website that accompanies this book includes a ShowColorTable.aspx page that you can open in your browser to view the rendered output of the ColorTable control. The control in Listing 36.6, the DropShadow control, illustrates how you can use the AddStyleAttribute() method of the HtmlTextWriter class to add Cascading Style Sheet (CSS) attributes to an HTML tag. LISTING 36.6 DropShadow.cs using System.Web.UI; using System.Web.UI.WebControls; namespace myControls { public class DropShadow : WebControl { private string _Text; public string Text { get { return _Text; } set { _Text = value; } } protected override void RenderContents(HtmlTextWriter writer) { writer.AddStyleAttribute( HtmlTextWriterStyle.Filter, “dropShadow(color=#AAAAAA,offX=3,offY=3);width:500px”); writer.RenderBeginTag(HtmlTextWriterTag.Div); writer.Write(_Text); writer.RenderEndTag(); } } } From the Library of Wow! eBook . ptg 15 74 CHAPTER 35 Deploying ASP. NET Web Applications applications along with all their configuration, dependencies, and prerequisites. These packages can be deployed to IIS. developers, administrators, or command-line scripts and dramatically ease the burden of deploying web applications. In addition, we also have the ability to create one-click publication profiles. us to take these web packages and deploy them on-demand just by clicking a button inside Visual Studio. When you have gotten over the joy of building your new ASP. NET 4 application, it’s going