@ Page

The @ Page directive, which is allowed in .aspx files only, defines page-specific attributes used by ASP.NET language compilers and the runtime to determine how the page will behave. The default values for a few of these attributes are set in the Pages configuration section in machine.config. Some of the attributes, including AutoEventWireup, are set or overridden in pages created by Microsoft Visual Studio .NET. The attributes available for the @ Page directive are listed in Table 7-2.

Enabling Debug Information

By default, ASP.NET pages created as a part of a Visual Studio .NET Web application project are compiled with debug symbols. This is good for development, since it offers much richer error information than was available in classic ASP, as shown in the following illustration.

This functionality, however, exacts a performance penalty, so you should usually turn this option off when you deploy your application. Debug symbols are enabled in two specific places in Visual Studio .NET: in Web.config (which enables debug symbols for .aspx pages) and in the Configuration Manager properties for the project/solution (which enables debug symbols for code- behind classes and other compiled classes in the project). The following procedures describe how to turn off debug symbols in both places.

Disable debug symbols in Web.config

1. Open the Web.config for the desired project in Visual Studio .NET.

2. Change the debug attribute of the <compilation> element to false:

   <compilation defaultLanguage="c#" debug="false" />

3. Save and close the file.

Now if you encounter an unhandled error in code contained within the .aspx page, ASP.NET will provide you with an error page without the specific error information made possible by the use of debug symbols, as shown in the following illustration.

Disable debug symbols using the Configuration Manager

1. Right-click the solution containing the desired project in Solution Explorer, and select Configuration Manager. The dialog box shown in the following illustration is displayed.

   

2. To disable debug symbols for a single project, select that project in the dialog box and change the value in the Configuration drop-down list from Debug to Release, as shown in the following illustration.

   

3. To disable debug symbols for all projects, change the Active Solution Configuration from Debug to Release, as shown in the illustration on the next page.

   

4. Click Close.

Enabling Tracing

By default, the trace functionality is not enabled for ASP.NET pages. As with the debug attribute, disabling tracing in production applications is good for performance, since there is overhead associated with tracing. Disabling tracing in production applications is also important for security because tracing provides a large amount of information about each request, information that could potentially assist a malicious user in attacking your site, if tracing isn’t configured properly. Tracing enables you to view information about the current request, including the collections (cookies, forms, headers, querystrings, and server variables) associated with the request.

Enable tracing

1. Open the desired page in Visual Studio .NET and switch to HTML view.

2. Add the trace attribute to the @ Page directive, with a value of true.

   <%@ Page trace="true" %>

3. Save the file. When you request the file from a browser, you’ll be able to see the trace information appended to the page output, as shown in the illustration on the following page.

   

For more information on tracing and its uses in debugging ASP.NET applications, refer to Chapter 14.

@ Control

The @ Control directive, which is allowed in .ascx files only, performs the same function as the @ Page directive. However, instead of setting attributes for pages, it sets the attributes for user controls, which are reusable snippets of code named with the .ascx file extension. The attributes exposed by the @ Control directive are a subset of the attributes exposed by the @ Page directive, and their purpose and values are the same as in the table of @ Page attributes table beginning on page 195. The following attributes are available for the @ Control directive:

• AutoEventWireup

• ClassName

• Codebehind

• CompilerOptions

• Debug

• Description

• EnableViewState

• Explicit

• Inherits

• Language

• Strict

• Src

• WarningLevel

@ Import

The @ Import directive is used to import either a Microsoft .NET Framework namespace or a custom namespace into a page. Importing a namespace allows you to write code against the members of that namespace without explicitly specifying the namespace each time. The @ Import directive has only one attribute, Namespace, which specifies the namespace to import. Each @ Import directive can have only one Namespace attribute, so you must use a separate @ Import directive for each namespace you want to import. For example, to use the .NET Framework SmtpMail and MailMessage classes to send e-mail from an ASP.NET page, you need to add the System.Web.Mail namespace to your page, as follows:

<%@ Import namespace="System.Web.Mail" %>

Then, to create an instance of the MailMessage class, you use the following:

MailMessage myMail = new MailMessage();

Without the @ Import directive, you need to use the following:

MailMessage myMail = new System.Web.Mail.MailMessage();

@ Implements

The @ Implements directive is used to implement a defined interface from within an ASP.NET page. An interface provides an abstract definition of a set of methods and properties. When you implement an interface, you commit to supporting the methods and properties defined by the interface, and you must create matching method and property definitions in your .aspx file, using <script> blocks. The @ Implements directive can’t be used to implement interfaces in a code-behind file. It has one attribute, interface, which specifies the interface being implemented.

@ Register

The @ Register directive is used with both user controls and custom server controls to register them for use within a page. The @ Register directive’s attributes are listed in Table 7-3.

For examples of the use of the @ Register directive, see “Creating and Using User Controls” on page 213 and “Using Server Controls” in Chapter 8.

@ Assembly

The @ Assembly directive is used to link an assembly into a page at compilation time. This allows developers to use all of the classes, methods, and so forth exposed by the assembly as if they were part of the page. The @ Assembly directive’s attributes are listed in Table 7-4. Only one of the Name and Src attributes of the @ Assembly directive can be used at a time.

Note that it is not necessary to use the @ Assembly directive to link in assemblies residing in the bin subdirectory of your application. These assemblies are automatically linked in by default, based on the <assemblies> subsection of the <compilation> section of the machine.config configuration file, which contains the following tag:

<add assembly="*"/>

This specifies that ASP.NET should link in any assemblies in the bin subdirectory. Note also that any other assemblies specified by an <add> tag in the <assemblies> subsection do not require linking with the @ Assembly directive.

@ OutputCache

The @ OutputCache directive is used to specify that the rendered output of the page or user control in which it appears should be cached. This directive also specifies the attributes that determine the duration of caching, the location of the cached output, and the attributes that determine when a client will receive freshly rendered content rather than the cached content. Output caching in user controls can be especially useful when some of the content in a page is relatively static, but other content is frequently updated, making it a poor candidate for caching. In a case like this, you could move the static content into a user control and use the @ OutputCache directive to cache its content, while leaving the rest of the page to be dynamically generated with each request.

The @ OutputCache directive’s attributes are listed in Table 7-5.

Enabling Output Caching

For pages or user controls whose content does not change frequently, output caching can provide a simple and powerful way to improve the performance of your application. With output caching enabled, requests that match the parameters of the cached pages will be served from the cache, which is much faster than rendering the page again.

Enable output caching on a Web Forms page

1. Open the desired Web Forms page in Visual Studio .NET. Switch to HTML view.

2. Add the @ OutputCache directive with, minimally, the required Duration and VaryByParam attributes. This directive should go at the top of the .aspx page, just below the @ Page directive.

   <%@ OutputCache duration="60" location="Any" VaryByParam="*" %>
   

3. Save the file. With these values for the attributes, the output of the page will be cached for 60 seconds. Any GET/POST requests with parameters that do not match an existing cached version of the page will be served a freshly rendered version of the page, which will then be cached.

For more information on output caching and using the ASP.NET cache engine to store arbitrary data, see Chapter 12.

@ Reference

The @ Reference directive allows you to dynamically load user controls by referencing the filename of the desired control and then using the Page.LoadControl method to load the control at runtime. The @ Reference directive directs the ASP.NET runtime to compile and link the specified control to the page in which it is declared. You’ll see an example of using the @ Reference directive in the section on user controls later in this chapter.

Using <script> Code Declaration Blocks

As I mentioned, in classic ASP you could write pretty much any code you wanted (property and method definitions, arbitrary code, and so on) in a <script> block using the runat=“server” attribute. The problem was that you couldn’t be sure when any arbitrary code in the <script> block would execute, relative to the code in the rest of the page. For this reason, ASP.NET does not allow you to use arbitrary code within <script> blocks—now referred to as code declaration blocks— to emphasize their purpose of declaring properties and methods.

In ASP.NET, if you want to call Response.Write within a code declaration block, you need to wrap that call within a method declaration. The following code will work:

<script language="c#" runat="server"> public void SayHello(  Response.Write("Hello, World!")  </script>

The following code will cause a compiler error, since the compiler expects to see either a variable or method declaration:

<script language="c#" runat="server"> Response.Write("Hello, World!") </script>

Likewise, you can declare a local member variable in a declaration block, but you cannot assign to it outside of a defined method. So the following code will work:

<script language="c#" runat="server"> string Name public void SetName(  Name = "Andrew"  </script>

But the following will cause a compiler error:

<script language="c#" runat="server"> string Name Name = "Andrew" </script>

There is one exception to the variable assignment rule. You can initialize the value of a variable by assigning a value as part of the variable declaration, as follows:

<script language="c#" runat="server"> string Name = "Andrew" </script>

The language attribute of the <script> block is optional. If it is omitted, the value will default to the language specified by the @ Page directive’s language attribute. If no language attribute has been specified for the @ Page directive, the value will default to C# (this value is set in the <compiler> element of the web.config configuration file for C# projects created with Visual Studio .NET).

Using ASP <% %> Code Render Blocks

Like <script> blocks, <% %> render blocks in classic ASP were pretty much “anything goes.” In many cases, this led to sloppy programming habits and hard-to-maintain code. ASP.NET solves these problems by not allowing anything other than inline code and expressions in render blocks. This means that you can no longer place method definitions in a render block. So the following code will cause a compiler error:

< public void SayHello(  Response.Write("Hello, World!")  %>

whereas the following code will work fine:

<    Response.Write("Hello, World!") %>

Compatibility with Classic ASP

Clearly, one of the issues that arises from these changes is that a good deal of code written in classic ASP will not be compatible with the restrictions on the use of code declaration and render blocks. For this reason, it is a good idea to examine any classic ASP code that you are considering migrating to ASP.NET for these incompatibilities, so that you can address them before making the migration (and discovering too late that the code won’t work!).

Create a user control

1. Create a new Web Application project in Visual Studio .NET. Type the name the the project as Chapter_07. (If you’ve installed the practice files, make sure to create the project in a location other than http://localhost/aspnetsbs/Chapter_07 to avoid conflicts.)

2. Add a User Control to the project by right-clicking the project in Solution Explorer, selecting Add, and then selecting Add Web User Control. Type the name of the user control as Compound.ascx.

3. Add six Label controls, three TextBox controls, a DropDownList control, and a Button control to the user control design surface. When you’re finished, the control should look like the following illustration.

   

   Since user controls start out in FlowLayout mode by default, you’ll need to use the Enter key to move a control to a new line. It’s important to name or number the controls in the order in which they appear on the page. (For example, the first label is Label1, the second, Label2, and so on.) This guarantees that the code in later steps will work.

4. Set the properties of the controls as follows:

   Control	Property	Value
   Label1	Text	Compound Interest Calculator
   Label1	Font-Bold	True
   Label1	Font-Size	Large
   Label2	Text	Principal ($):
   Label3	Text	Rate (%):
   Label4	Text	Years:
   Label5	Text	Compounding Frequency:
   Button1	Text	Calculate
   Label6	Text	(blank)

5. Click the DropDownList1 control to select it, and then select the Items property and click the ellipsis (…) button to open the Collection Editor. Add four items, set the following text and values, and then click OK:

   Item	Text	Value
   0	Annually	1
   1	Quarterly	4
   2	Monthly	12
   3	Daily	365

   When you have finished modifying the properties, the design view of Compound.ascx should look like the illustration on the next page.

   

6. Double-click the Calculate button. This will switch to the code- behind for the user control and add the Button1_Click event handler. Add the following code, which calls the function to calculate the compounded interest, to the event handler.

   Label6.Text = "Final Balance: $" +     CalcBalance(Convert.ToInt32(TextBox1.Text),     (Convert.ToInt32(TextBox2.Text) / 100),     Convert.ToInt32(TextBox3.Text),     Convert.ToInt16(DropDownList1.SelectedItem.Value)).ToString();

7. Immediately following the End Sub of the Button1_Click event handler, add the following code, which defines the function for calculating the compound interest:

   private string CalculateBalance(int Principal, double Rate, int Years int Period  double result double NumToBeRaised = (1 + Rate / Period) result=Principal * System.Math.Pow(NumToBeRaised, (Years * Period)) return(result.ToString("C")) }
   

8. Save the control and code-behind module, and then build the Chapter_07 project.

This control takes a dollar amount representing the principal to be invested (or borrowed), an interest rate, a period in years, and a compounding frequency, and uses these values to calculate the ending balance. This control encapsulates all of the controls and methods necessary for doing the calculation, so the only way to access them is through the user interface defined by the control. It is also possible, if desired, to expose the controls and/or their values publicly, so that they can be manipulated at runtime from the containing page.

To use this control, you need to add it to a Web Forms page. You can do this two ways: declaratively and programmatically. The declarative technique is simpler, but the programmatic technique gives you better runtime control.

Adding a User Control to a Page Declaratively

To use a user control in a Web Forms page, you need to make the control available to the page, and then implement the control on the page. As described in “Using Directives” on page 194, user controls can be made available to a page using either the @ Register directive or the @ Reference directive, depending on whether you are adding the control declaratively or programmatically. If you want to add the control declaratively, you need to use the @ Register directive to set up the tag syntax for the control. Fortunately, the Visual Studio .NET environment makes this a simple matter of drag and drop.

Add a control to a Web Form declaratively

1. Open the Chapter_07 project created in the previous example if it is not already open.

2. Add a new Web Forms page to the project and type its name as CompoundContainer.aspx.

3. Drag the Compound.ascx user control from the Solution Explorer onto the design surface of CompoundContainer.aspx. The result should look like the illustration on the next page.

   

4. Save CompoundContainer.aspx, and then browse it using Internet Explorer by right-clicking the file in Solution Explorer and selecting Browse With. Enter amounts for the principal, rate, and years, then choose a compounding frequency, and then click Calculate. The result should look similar to the following illustration. Note that if you enter any non-integer value in the textboxes, an exception will occur when you click Calculate. You could prevent this by adding validator controls to ensure that only integer values are entered.

   

If you take a look at the HTML view for CompoundContainer.aspx, you’ll see that Visual Studio .NET takes care of adding both the @ Register directive that makes the user control available to the page, and the tag that represents the user control. This greatly simplifies the process of adding a user control to the page, and should probably be your preferred method for adding user controls in Visual Studio .NET. You can, however, also add a user control to the page programmatically, as you’ll see in the next section.

Adding a User Control to a Page Programmatically

The steps for adding a control to a page programmatically are somewhat similar to—but a bit more involved than—adding a control declaratively. You still need to make the control available to the page. For controls that are to be added programmatically, you can either use the @ Register directive, as in the previous example, or the @ Reference directive. Since the @ Register directive is more commonly used for declarative controls, use the @ Reference directive.

Add an @ Reference directive

1. Add a new Web Form to the Chapter_07 project. Type the name of the file as CompoundProgrammatic.aspx.

2. Switch to HTML view, and add the following code to the page, just below the @ Page directive:

   <%@ Reference Control="Compound.ascx" %>

3. Save the file, but don’t close it.

The @ Reference directive tells ASP.NET to compile and link the user control Compound.ascx with the page when it is compiled. This makes the control available for you to add to the page. Since you’re not going to be adding a tag within the HTML markup for the control’s output, take advantage of a special server control called the Placeholder control. As the name suggests, this allows you to put a placeholder in the HTML markup to which you can add controls later. In this way, you can decide precisely where you want the output from the control to appear.

Add the Placeholder control

1. Add a PlaceHolder control to CompoundProgrammatic.aspx by editing the <form> element to look like the following code:

   <form id="Form1" method="post" runat="server">    <asp:PlaceHolder ID="CompoundHolder" Runat="server"/> </form>

2. Save the file, but don’t close it yet.

Finally, we need to add the control to the page, and to the Controls collection of the Placeholder control, which will place the output of the control where we want it. Then the control will take care of the rest, just as in the previous example.

Add the user control to the page

1. Switch to Design view and double-click an empty area of the page. This will open the code-behind module for the page and place the cursor in the Page_Load event handler. Add the following code to the event handler:

   Control CalcCompound = LoadControl("Compound.ascx") CompoundHolder.Controls.Add(CalcCompound);

2. Save the page and code-behind module, and then build the Chapter_07 project.

3. Browse CompoundProgrammatic.aspx, using the Browse With dialog box. The output of the page should be the same as in the previous illustration.

Comparing User Controls to Include Files

User controls perform a similar function to server-side includes in classic ASP, but they’re considerably more powerful because of the level of integration with the page model. A user control can have its own controls, and it can save the viewstate of its controls or its own viewstate. This allows the user control to maintain its state across multiple calls without any effort on the part of the page containing the user control. User controls can expose both properties and methods, making them easy to understand for developers who are used to components.

Include files are still available in ASP.NET, mainly for backward compatibility with classic ASP. Given the advantages of user controls, it makes sense to use them for new applications.