User Control Basics
To get started, let’s build a simple User Control, MyControl.ascx, and an ASP.NET page that consumes it, MyPage.aspx.
MyControl
Most of the time, User Controls will contain dynamic elements, but that’s not always the case. For instance, you might create a User Control to display copyright information at the bottom of each page in your web application. Likewise, the User Control MyControl will start off with just static content. Right now, you’ll be concerned with the issues surrounding the basic plumbing of User Controls, as you can see in Listing 11.1.
Listing 11.1. MyControl— Basics
<%@ Control Language="C#" %> This is MyControl. |
MyPage
Now that you have a simple User Control built, you can implement it in an ASP.NET page. First, Listing 11.2 shows the correct implementation code.
Listing 11.2. MyPage—Basics
<%@ Page Language="C#" %>
<%@ Register TagPrefix="Chapter11" TagName="MyControl"
Src="MyControl.ascx" %>
<html>
<head><title>MyPage</title></head>
<body>
<Chapter11:MyControl runat="server" />
</body>
</html> |
Basic Gotchas
The code in Listings 11.1 and 11.2 will yield the simple message displayed in the browser “This is MyControl.” Did you get any errors? Here’s what might have gone wrong.
Missing End Tag or End-Tag Marker
All ASP.NET server controls require an end tag. User Controls are a form of server control that you custom-create, so the same rules apply. Forgetting to include either an end tag </Chapter11:MyControl> or and end-tag marker /> will generate an error like this:
Parser Error Message: Literal content (</body> </html>') is not allowed within a
'ASP.MyControl_ascx'
Of course, the exact syntax of the error will vary, depending on what literal content is present directly after your User Control reference. In this case, it was the </body></html> HTML tags.
Missing Runat Attribute
What if your User Control doesn’t show up at all? This almost always means that that you forgot to include the runat="server" attribute on your User Control. This is a requirement, as it is with all other ASP.NET server controls. A quick way to verify this is to right-click the screen in Internet Explorer and select View Source. You’ll most likely see that your User Control tag was mistaken for plain-old HTML tags and was sent directly to the browser. Without the runat attribute, the ASP.NET engine does not know that it is supposed to do anything with it, so it completely ignores it.
Unknown Server Tag
Occasionally, you’ll get a message that doesn’t make any sense at first glance. For instance, you might get this error:
Parser Error Message: Unknown server tag 'Chapter11:MyControl'.
It doesn’t seem to make any sense because that is the TagPrefix and TagName that you specified. Or is it? Take another look at your @Register tag at the top of your ASP.NET page. Odds are, you misspelled either the TagPrefix or the TagName attribute. If the situation were reversed, it would have been easier to spot the issue because the ASP.NET sourcecode surrounding the error is shown. If the error resides in the @Register tag, the solution is not always so obvious.