How to: Convert Web Forms Pages into ASP.NET User Controls

How to: Convert Web Forms Pages into ASP.NET User Controls

If you have developed an ASP.NET Web page and would like to access its functionality throughout your application, you can make some minor alterations to the page to change it to a user control.

To convert a single-file ASP.NET Web page into a user control

1. Rename the control so the file name extension is .ascx.
2. Remove the html, body, and form elements from the page.
3. Change the @ Page directive to an @ Control directive.
4. Remove all attributes of the @ Control directive except Language, AutoEventWireup (if present), CodeFile, and Inherits.
5. Include a className attribute in the @ Control directive. This allows the user control to be strongly typed when it is added to a page.

To convert a code-behind ASP.NET Web page into a user control

1. Rename the .aspx file so the file name extension is .ascx.
2. Rename the code-behind file to have the file name extension .ascx.vb or .ascx.cs, depending on what programming language the code-behind file is in.
3. Open the code-behind file and change the class from which it inherits from Page to UserControl.
4. In the .aspx file, do the following:
   
   a. Remove the html, body, and form elements from the page.
   b. Change the @ Page directive to an @ Control directive.
   c. Remove all attributes of the @ Control directive except Language, AutoEventWireup  (if present), CodeFile, and Inherits.
   d. In the @ Control directive, change the CodeFile attribute to point to the renamed code-behind file.
   
5. Include a className attribute in the @ Control directive. This allows the user control to be strongly typed when it is added to a page.

Example

---

The following example shows a single-file ASP.NET Web page in its original form and the resulting user control after converting the page.

Security Note-This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

C#

<%@ Page Language="C#" %>





 Web Forms Page 

Enter Name: "Name" runat=server/>

C#

<%@ Control Language="C#" ClassName="SampleUserControl" %>



 

 User Control 

Enter Name: "Name" runat=server/>

How to: Create ASP.NET User Controls

How to: Create ASP.NET User Controls

You create ASP.NET user controls in much the same way that you design ASP.NET Web pages. You can use the same HTML elements and controls on a user control that you do on a standard ASP.NET page. However, the user control does not have html, body, and form elements; and the file name extension must be .ascx.

To create an ASP.NET user control

1. Open the Web site project to which you want to add user controls. If you do not already have a Web site project, you can create one. For more information, see Local IIS Web Site Projects or How to: Create File System Web Site Projects.
2. On the Website menu, click Add New Item.
   The Add New Item dialog box appears.
3. In the Add New Item dialog box, under Visual Studio installed templates, click Web User Control.
4. In the Name box, type a name for the control.
   By default, the .ascx file name extension is appended to the control name that you type.
5. From the Language list, select the programming language that you want to use.
6. Optionally, if you want to keep any code for the user control in a separate file, select the Place code in separate file check box.
7. Click Add.
   The new ASP.NET user control is created and then opened in the designer. The markup for this new control is similar to the markup for an ASP.NET Web page, except that it contains an @ Control directive instead of an @ Page directive, and the user control does not have html, body, and form elements.
   Add any markup and controls to the new user control, and add code for any tasks that the user control will perform, such as handling control events or reading data from a data source.

How to: Include a User Control in an ASP.NET Web Page

How to: Include a User Control in an ASP.NET Web Page

To use a user control, you include it in an ASP.NET Web page. When a request arrives for a page and that page contains a user control, the user control goes through all of the processing stages that any ASP.NET server control performs. For more information about these processing stages, see ASP.NET Page Life Cycle Overview.

To include a user control in a Web Forms page

1. In the containing ASP.NET Web page, create an @ Register directive that includes:
   
   
   • A TagPrefix attribute, which associates a prefix with the user control. This prefix will be included in opening tag of the user control element.
   • A TagName attribute, which associates a name with the user control. This name will be included in the opening tag of the user control element.
   • A Src attribute, which defines the virtual path to the user control file that you are including.
     
     

     Note-The Src attribute value can be either a relative or an absolute path to the user control source file from your application's root directory. For flexibility, it is recommended you use a relative path. The tilde (~) character represents the root directory of the application. User controls cannot be located in the App_Code directory.

2. In the body of the Web page, declare the user control element inside the form element.
3. Optionally, if the user control exposes public properties, set the properties declaratively.

Example

---

The following example shows an ASP.NET Web page that contains a user control. The user control is in the file Spinner.ascx in the Controls folder. In the page, the control is registered to use the prefix uc and the tag name Spinner. The user control properties MinValue and MaxValue are set declaratively.

C#

<%@ Page Language="C#" %>
<%@ Register TagPrefix="uc" TagName="Spinner" 
    Src="~/Controls/Spinner.ascx" %>



"server">
    "Spinner1" 
        runat="server" 
        MinValue="1" 
        MaxValue="10" />

ASP.NET User Controls Overview

ASP.NET User Controls Overview

At times, you might need functionality in a control that is not provided by the built-in ASP.NET Web server controls. In those cases, you can create your own controls. You have two options. You can create:

• User controls. User controls are containers into which you can put markup and Web server controls. You can then treat the user control as a unit and define properties and methods for it.
• Custom controls. A custom control is a class that you write that derives from Control or WebControl.

User controls are substantially easier to create than custom controls, because you can reuse existing controls. They make it particularly easy to create controls with complex user interface elements.
This topic provides an overview of working with ASP.NET user controls.

User Control Structure

---

An ASP.NET Web user control is similar to a complete ASP.NET Web page (.aspx file), with both a user interface page and code. You create the user control in much the same way you create an ASP.NET page and then add the markup and child controls that you need. A user control can include code to manipulate its contents like a page can, including performing tasks such as data binding.

A user controls differs from an ASP.NET Web page in these ways:

• The file name extension for the user control is .ascx.
• Instead of an @ Page directive, the user control contains an @ Control directive that defines configuration and other properties.
• User controls cannot run as stand-alone files. Instead, you must add them to ASP.NET pages, as you would any control.
• The user control does not have html, body, or form elements in it. These elements must be in the hosting page.

You can use the same HTML elements (except the html, body, or form elements) and Web controls on a user control that you do on an ASP.NET Web page. For example, if you are creating a user control to use as a toolbar, you can put a series of Button Web server controls onto the control and create event handlers for the buttons.

The following example shows a user control that implements a spinner control where users can click up and down buttons to rotate through a series of choices in a text box.

Security Note-This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

C# Code

<% @ Control Language="C#" ClassName="UserControl1" %>

"textColor" runat="server" 
    ReadOnly="True" />
"True" ID="buttonUp" runat="server" 
    Text="^" OnClick="buttonUp_Click" />
"True" ID="buttonDown" runat="server" 
    Text="v" OnClick="buttonDown_Click" />

Notice that the user control looks much like an ASP.NET page — it contains several controls (a TextBox control and two Button controls) and code that handles the buttons' Click events and the page’s Load event. However, the control contains no markup except for the controls, and instead of an @ Page directive it contains an @ Control directive. 

Adding a User Control to a Page

---

You add a user control to a page by registering it on the host page. When you register it, you specify the .ascx file that contains the user control, a tag prefix, and a tag name that you will use to declare the user control on the page. For details, see How to: Include a User Control in an ASP.NET Web Page.

Defining Properties and Methods for a User Control

---

You can define properties and methods for a user control the same way you do for a page. By defining a property for a user control, you make it possible to set its properties declaratively and in code.

Events in User Controls

---

When a user control contains Web server controls, you can write code in the user control to handle the events raised by the child controls. For example, if your user control contains a Button control, you can create a handler in the user control for the button's Click event.

By default, events raised by child controls in a user control are not available to the host page. However, you can define events for your user control and raise them so that the host page is notified of the event. You do this in the same way that you define events for any class. For more information, see Raising an Event.

Referencing External Resources

---

When a user control runs, references to external resources such as images or anchors to other pages are resolved using the URL of the user control as the base URL. For example, if the user control contains an Image control whose ImageUrl property is set to Images/Button1.gif, the URL of the image is added to the URL of the user control to resolve the complete path to the image. If the user control references a resource that is not in a subfolder of the user control itself, you must provide a path that resolves to the correct folder at run time. For more information on specifying paths for ASP.NET server controls, see ASP.NET Web Project Paths.

Caching and User Controls

---

User controls can support caching directives that are separate from the host page. You can therefore add user controls to pages and to cache portions of a page. For details, see Caching Portions of an ASP.NET Page.

Directives for Asp .Net

Directives for ASP.NET Web Pages

Directives specify settings that are used by the page and user-control compilers when the compilers process ASP.NET Web Forms pages (.aspx files) and user control (.ascx) files.
ASP.NET treats any directive block (<%@ %>) that does not contain an explicit directive name as an @ Page directive (for a page) or as an @ Control directive (for a user control).

@ Assembly

Links an assembly to an ASP.NET application file (such as a Web page, a user control, a master page, or a Global.asax file) during compilation, making all the assembly's classes and interfaces available for use.

<%@ Assembly Name="assemblyname" %>

<%@ Assembly Src="pathname" %>

Attributes

---

Name

A string that represents the name of the assembly to link.

Note-The assembly name does not include a file name extension.

Src

The path to a source file to dynamically compile and link against.

Note

You must include either a Name or a Src attribute in an @ Assembly directive, but you cannot include both within the same directive. If you need to use both of these attributes, you must include multiple @ Assembly directives in the file.

Remarks

---

The compiler references the assembly at compile time, allowing early binding. After compilation of the requested ASP.NET file is complete, the assembly is loaded into the application domain, allowing late binding. The @ Assembly directive can be used in .aspx pages, .ascx files, .master pages and .asax files.
Assemblies that reside in your Web application's \Bin directory are automatically linked to ASP.NET files within that application. Such assemblies do not require the @ Assembly directive. You can disable this functionality by removing the following line from the section of your application's Web.config file:

As an alternative to using the @ Assemblydirective, you can use the Web.config file to link assemblies across an entire application. For more information about the Web.config file and configuring your application, see ASP.NET Configuration Overview and assemblies Element for compilation (ASP.NET Settings Schema).

Example

---

The following code example uses two @ Assembly directives, the first to link to MyAssembly, a user-defined assembly, and the second to MySource.vb, a Visual Basic source file.

<%@ Assembly Name="MyAssembly" %>

<%@ Assembly Src="MySource.vb" %>

@ Control

Defines attributes that are specific to user controls (.ascx files) that are used by the ASP.NET page parser and compiler. This directive can be used only with (whose source code is contained in .ascx files).

<%@ Control attribute="value" [attribute="value" ... ] %>

Attributes

AutoEventWireup

Indicates whether the control's events are autowired. true if event autowiring is enabled; otherwise, false. The default is true. 

ClassName

A string that specifies the class name for the control that will be dynamically compiled when the control is requested. This value can be any valid class name and can include the full namespace of a class (a fully qualified class name). If a value for this attribute is not specified, the class name for the compiled control is based on the control's file name.

Another page or control can reference the class name assigned to the control by using the  

@ Reference directive.

ClientIDMode

Specifies the algorithm to use to generate ClientID values for controls. The default value for a page is AutoID.

The default value for controls is Inherit. Therefore, the default algorithm for controls in a user control is determined by the ClientID setting of the user control. A different default value can be set at the page level in the @ Page directive or in the pages element of the Web.config file. For more information about the algorithms, see ClientIDMode.

CodeBehind

Specifies the name of the compiled file that contains the class associated with the control. This attribute is not used at run time.

Note--This attribute is included for compatibility with previous versions of ASP.NET, to implement the code-behind feature. In ASP.NET version 2.0, you should instead use the CodeFile attribute to specify the name of the source file, along with the Inherits attribute to specify the fully qualified name of the class.

CodeFile

Specifies a path to the referenced code-behind file for the control. This attribute is used together with the Inherits attribute to associate a code-behind source file with a user control. The attribute is valid only for compiled controls.

CodeFileBaseClass

Specifies a path to a base class for a control and its associated code-behind class. This attribute is optional, but when it is used the CodeFile attribute must also be present. Use this attribute when you want to implement a shared scenario, where you define common fields (and optionally, associated events) in a base class to reference the controls declared in a user control. Because of the ASP.NET code generation model, if you defined the fields in a base class without using the this attribute, at compile time new member definitions would be generated for the controls declared in the user control (within a separate partial class stub), and your desired scenario would not work. But if you use the CodeFileBaseClass attribute to associate the base class with the user control, and you make your partial class (its name is assigned to the Inherits attribute and its source file is referenced by the CodeFile attribute) inherit from the base class, then the fields in the base class will be able to reference the controls in the user control after code generation.

CompilationMode

Sets whether the control should be compiled, using a string that specifies one of several enumerated options. The default value is Always, so .aspx controls are compiled by default. For details, see the CompilationMode enumeration.

CompilerOptions

A string containing compiler options used to compile the control. In C# and Visual Basic, this is a sequence of compiler command-line switches.

Debug

Indicates whether the control should be compiled with debug symbols. true if the control should be compiled with debug symbols; otherwise, false. Because this setting affects performance, you should only set the attribute to true during development.

Description

Provides a text description of the control. This value is ignored by the ASP.NET parser.

EnableTheming

Indicates whether themes are used on the control. true if themes are used; otherwise, false. The default is true.

EnableViewState

Indicates whether view state is maintained across control requests. true if view state is maintained; otherwise, false. The default is true.

Explicit

Determines whether the control is compiled using the Visual Basic Option Explicit mode. true indicates that the Visual Basic explicit compile option is enabled and that all variables must be declared using a Dim, Private, Public, or ReDim statement; otherwise, false. The default is false.

Note-This attribute is ignored by languages other than Visual Basic. Also, this option is set to true in the Machine.config configuration file. For more information, see Configuration Files and ASP.NET Configuration Files.

Inherits

Defines a code-behind class for the control to inherit. This can be any class derived from the UserControl class. Used with the CodeFile attribute, which contains the path to the source file for the code-behind class. For more information about code-behind classes, see ASP.NET Web Page Code Model.

Language

Specifies the language used when compiling all inline rendering (<% %> and <%= %>) and code declaration blocks within the control. Values can represent any .NET Framework-supported language, including Visual Basic, C#, or JScript. Only one language can be used and specified per control.

LinePragmas

Determines whether the runtime should generate line pragmas in the source code. These are compiler options that are often used by debugging tools to mark specific locations in a source file. true if line pragmas should be generated; otherwise, false.

Src

Specifies a path to a source file containing code that is linked to the control. In the linked source file, you can choose to include programming logic for your control either in a class or in code declaration blocks.

You can use the Src attribute to link build providers to the control. For more information, see the BuildProvider class. Also, in versions of ASP.NET prior to 2.0, the Src attribute was used as an alternative way to link a code-behind file to a control. In ASP.NET version 2.0, the preferred approach to linking a code-behind source file to a control is to use the Inherits attribute to specify a class, along with the CodeFile attribute to specify the path to the source file for the class.

Strict

Indicates that the control should be compiled using the Visual Basic OptionStrict mode. true if Option Strict is enabled; otherwise, false. The default is false.

Note-This attribute is ignored by languages other than Visual Basic.

TargetSchema

Specifies the name of a schema that validates content on the control. This serves only a descriptive purpose; no actual validation is performed, and the attribute is ignored by the parser.

WarningLevel

Indicates the compiler warning level at which you want the compiler to treat warnings as errors, thus aborting compilation of the control. Possible warning levels are 0 through 4. For more information, see the WarningLevel property.

Remarks

---

This directive can be used only in user controls. User controls are defined in files with the .ascx extension. You can include only one @ Control directive per .ascx file. Further, you can define only one Language attribute per @ Control directive, because only one language can be used per control.

Note-The @ Control directive has a number of attributes in common with other directives that apply to an entire source file, such as the @ Page directive (used in .aspx files for Web pages) and the @ Master directive (used in .master files for master pages).

To define multiple attributes for the @ Control directive, separate each attribute/value pair with a single space. For a specific attribute, do not include a space on either side of the equal sign (=) that connects the attribute with its value. For an example, see the Example section of this topic.

Example

---

The following code example instructs the ASP.NET page compiler to use Visual Basic as the inline code language and disables saving view state across HTTP requests using the EnableViewState attribute.

<%@ Control Language="VB" EnableViewState="false" %>

@ Implements

Indicates that the current ASP.NET application file (Web page, user control, or master page) implements the specified .NET Framework interface.

<%@ Implements interface="ValidInterfaceName" %>

Attributes

interface

The interface to be implemented on the page or user control.

Remarks

---

When you implement an interface in a Web Forms page, you can create its events, methods, and properties between the opening and closing tags of a

"Calendar1" runat="server" />

<%@ Page language="VB" %>

<%@ register tagprefix="uc1" 

    tagname="CalControl" 

    src="~/CalendarUserControl.ascx" %>

PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

"http://www.w3.org/1999/xhtml" >

"Head1" runat="server">

  


"form1" runat="server">



    "manager1" runat="server" />
    "WebPartZone1" runat="server">
      
        "CalControl1" runat="server" 
          title="Personal Calendar" 
          description="My personal calendar for work." />      
      
    
  

@ Import

Explicitly imports a namespace into an ASP.NET application file (such as a Web page, a user control, a master page, or a Global.asax file), making all classes and interfaces of the imported namespace available to the file. The imported namespace can be part of the .NET Framework class library or a user-defined namespace.

<%@ Import namespace="value" %>

Attributes

---

namespace

The fully qualified name of the namespace to import. This can include any of the namespaces included in the .NET Framework or a custom namespace.

Remarks

---

The @ Import directive cannot have more than one namespace attribute. To import multiple namespaces, use multiple @ Import directives.
A set of namespaces can be automatically imported into .aspx pages. The imported namespaces are defined in the machine-level Web.config file, within the section of the element. The following namespaces are automatically imported into all pages:

·         System

·         System.Collections

·         System.Collections.Specialized

·         System.Configuration

·         System.Text

·         System.Text.RegularExpressions

·         System.Web

·         System.Web.Caching

·         System.Web.Profile

·         System.Web.Security

·         System.Web.SessionState

·         System.Web.UI

·         System.Web.UI.HtmlControls

·         System.Web.UI.WebControls

·         System.Web.UI.WebControls.WebParts

Example

---

The following code example imports the .NET Framework base-class namespace System.Net and the user-defined namespace Grocery.

<%@ Import Namespace="System.Net" %>

<%@ Import Namespace="Grocery" %>

@ Master

Defines master page–specific (.master file) attributes that are used by the ASP.NET page parser and compiler.

<%@ Master attribute="value" [attribute="value"...] %>

Attributes

---

Term	Definition
AutoEventWireup	Indicates whether simple event handlers can be defined for specific life cycle stages using the syntax Page without any explicit hookup or event signature. true if event auto-wiring is enabled; otherwise, false. The default is true. For more information, see ASP.NET Web Server Control Event Model.
ClassName	Specifies the class name for the class that is automatically generated from the markup and compiled when the master page is processed. This value can be any valid class name and can include a namespace.
CodeFile	Specifies the name of a separate file that contains a partial class with the event handlers and other master page–specific code. For more information, see ASP.NET Web Page Code Model.
CompilationMode	Specifies whether to compile an ASP.NET master page at run time. Options are Always  to always compile the page; Auto, if ASP.NET is to avoid compiling the page, if possible; and Never, to never compile the page or control. The default is Always.
CompilerOptions	Provides a string containing compiler options to use to compile the page. In C# and Microsoft Visual Basic, this is a sequence of compiler command-line switches.
Debug	Indicates whether to compile the master page with debug symbols. true, to compile with debug symbols; otherwise, false.
Description	Provides a text description of the master page. This value is ignored by the ASP.NET parser.
EnableTheming	Indicates whether the appearance of the master page and of controls on the master page can be modified, if a theme is applied. true if a theme can be applied; otherwise, false. The default is true. Setting the EnableTheming attribute is primarily useful when a page theme is defined in the Web.config file and applies to all pages, by default. For more information, see ASP.NET Themes and Skins.
EnableViewState	Indicates whether view state is maintained across page requests. true to maintain view state; otherwise, false. The default is true.
Explicit	Determines whether the page is compiled using the Visual Basic Option Explicit mode. true indicates that the Visual Basic explicit compile option is enabled and that all variables must be declared using a Dim, Private, Public, or ReDim statement; otherwise, false. The default is false. Note The Explicit attribute is ignored by languages other than Visual Basic. The Explicit attribute is set to true in the Machine.config file. For more information, see Machine Configuration Files.
Inherits	Specifies a code-behind class for the page to inherit. This can be any class derived from the MasterPage class. For information about code-behind classes, see ASP.NET Page Class Overview.
Language	Specifies the language used when compiling all inline rendering (<% %> and <%= %>) and code declaration blocks within the page. Values can represent any language that is supported by the .NET Framework, including VB (Visual Basic), C#, and JScript.
LinePragmas	Determines whether the runtime should generate pragmas in the generated code.
MasterPageFile	Specifies the .master file that acts as a master page for a master page. The   MasterPageFile attribute is used in a master page when defining a child master page in a nested master-page scenario. For details, see Nested ASP.NET Master Pages.
Src	Specifies the source file name of the code-behind class to dynamically compile when the page is requested. You can choose to include programming logic for your page either in a code-behind class or in a Code Declaration Blocks in the .aspx file.
Strict	Specifies whether to compile the page using the Visual Basic Option Strict mode. true if Option Strict is enabled; otherwise, false. The default is false. Note The Strict attribute is ignored by languages other than Visual Basic.
WarningLevel	Specifies the compiler warning level at which you want the compiler to abort compilation for the page. Possible values are from 0 through 4. For more information, see WarningLevel.

Remarks

---

You can use the @ Master directive only in master pages. Master pages are defined in files with the .master extension. You can include only one @ Master directive per .master file.

Example

---

The following code example demonstrates how to instruct the ASP.NET page compiler to use Visual Basic as the inline code language. The event-handling code is defined in a partial class named MasterPageSample. The code for the MasterPageSample class can be found in the MasterPageSample.master.vb file.

<% @ Master Language="VB" CodeFile="MasterPageSample.master.vb" Inherits="MasterPageSample" %>

@ MasterType

Provides a way to create a strongly typed reference to the ASP.NET master page when the master page is accessed from the Master property.

<%@ MasterType attribute="value" [attribute="value"...] %>

Attributes

---

TypeName

Specifies the type name for the master page.

VirtualPath

Specifies the path to the file that generates the strong type.

Remarks

---

Use the @ MasterType directive to set the strong type for the master page, as accessed through the Master property.

Note-if VirtualPath is not defined, the type must exist in one of the currently linked assemblies, such as App_Bin or App_Code.

If both attributes, TypeName and VirtualPath, are defined, the @ MasterType directive will fail.

Example

---

The following code example demonstrates how to set the virtual path to an ASP.NET master page.

<%@ MasterType VirtualPath="~/masters/SourcePage.master”" %>

@ OutputCache

Declaratively controls the output caching policies of an ASP.NET page or a user control contained in a page. For more information about the output cache, see ASP.NET Caching.

<%@ OutputCache Duration="#ofseconds"

   Location="Any | Client | Downstream | Server | None | 

     ServerAndClient "

   Shared="True | False"

   VaryByControl="controlname"

   VaryByCustom="browser | customstring"

   VaryByHeader="headers"

   VaryByParam="parametername" 

   VaryByContentEncoding="encodings"

   CacheProfile="cache profile name | ''"

   NoStore="true | false"

   SqlDependency="database/table name pair | CommandNotification"

   ProviderName="Provider Name"  

%>

Attributes

---

Duration

The time, in seconds, that the page or user control is cached. Setting this attribute on a page or user control establishes an expiration policy for HTTP responses from the object and will automatically cache the page or user control output.

Note-This attribute is required. If you do not include it, a parser error occurs.

Location

One of the OutputCacheLocation enumeration values. The default is Any.

Note-This attribute is not supported for @ OutputCache directives included in user controls (.ascx files).

CacheProfile

The name of the cache settings to associate with the page. This is an optional attribute and defaults to an empty string ("").

Note-This attribute is not supported for @ OutputCache directives included in user controls (.ascx files). When specified on a page, the value must match the names of one of the available entries in the outputCacheProfiles element under the outputCacheSettings section. If the name does not match a profile entry, an exception is thrown.

NoStore

A Boolean value that determines whether to prevent secondary storage of sensitive information.

Note-This attribute is not supported for @ OutputCache directives included in user controls (.ascx files). Setting this attribute to true is equivalent to the following code executed during the request:

            Response.Cache.SetNoStore();

ProviderName

A string value that identifies the custom output-cache provider to used. For more information, see the Remarks section of this topic and the entry Extensible Output Caching with ASP.NET 4 (VS 2010 and .NET 4.0 Series) on Scott Guthrie's blog

Note-This attribute is supported only in user controls (.ascx files). It not supported for @ OutputCache directives that are included in ASP.NET pages (.aspx files).

Shared

A Boolean value that determines whether user control output can be shared with multiple pages. The default is false. For more information, see the Remarks section.

Note-This attribute is not supported for @ OutputCache directives included in ASP.NET pages (.aspx files).

SqlDependency

A string value that identifies a set of database and table name pairs that a page or control's output cache depends on. Note that the SqlCacheDependency class monitors the table in a database that the output cache depends on, so that when items in a table are updated, those items are removed from the cache when using table-based polling. When using notifications (in Microsoft SQL Server 2005) with the value CommandNotification, ultimately a SqlDependency class is used to register for query notifications with the SQL Server 2005 server.

Note-The CommandNotification value for the SqlDependency attribute is valid only on Web (.aspx) pages. User controls can only use table-based polling with the @ OutputCache directive.

VaryByCustom

Any text that represents custom output caching requirements. If this attribute is given a value of browser, the cache is varied by browser name and major version information. If a custom string is entered, you must override the GetVaryByCustomString method in your application's Global.asax file.

VaryByHeader

A semicolon-separated list of HTTP headers used to vary the output cache. When this attribute is set to multiple headers, the output cache contains a different version of the requested document for each combination of specified headers.

Note-Setting the VaryByHeader attribute enables caching items in all HTTP version 1.1 caches, not just the ASP.NET cache. This attribute is not supported for @ OutputCache directives in user controls.

VaryByParam

A semicolon-separated list of strings used to vary the output cache. By default, these strings correspond to a query string value sent with GET method attributes, or a parameter sent using the POST method. When this attribute is set to multiple parameters, the output cache contains a different version of the requested document for each combination of specified parameters. Possible values include none, an asterisk (*), and any valid query string or POST parameter name.

Caution-Either this attribute or the VaryByControl attribute is required when you use the @ OutputCache directive on ASP.NET pages and user controls. A parser error occurs if you fail to include it. If you do not want to specify a parameter to vary cached content, set the value to none. If you want to vary the output cache by all parameter values, set the attribute to an asterisk (*).

VaryByControl

A semicolon-separated list of strings used to vary a user control's output cache. These strings represent the ID property values of ASP.NET server controls declared in the user control. For more information, see Caching Portions of an ASP.NET Page.

Note-Either this attribute or the VaryByParam attribute is required when you use the @ OutputCache directive on ASP.NET pages and user controls.

VaryByContentEncodings

A semicolon-separated list of strings that are used to vary the output cache. The VaryByContentEncodings attribute is used with the Accept-Encoding header to determine how cached responses are served for different content encodings. For more information about how to specify the Accept-Encoding header, see section 14.3 of the Hypertext Transfer Protocol -- HTTP/1.1 specification on the W3C Web site.

Remarks

---

Setting values for the page output cache is the same as manipulating the SetExpires and SetCacheability methods through the Cache property.
If a Web Forms page requires authorization to be viewed by a user, the output cache sets the Cache-Control HTTP header to private. For more information on all these subjects, see Caching ASP.NET Pages.
If you set the Shared attribute to true, cached user control output can be accessed by multiple Web Forms pages. If you do not set it to true, the default behavior is to cache one version of user control output for each page that contains that user control. You can potentially save a significant amount of memory by enabling the Shared attribute. For more information, see Caching Portions of an ASP.NET Page.

Example

---

The following code example demonstrates how you can set the duration for which a page or user control is output cached.

<%@ OutputCache Duration="100" VaryByParam="none" %>

The next code example demonstrates how you can instruct the output cache to cache a page or user control by its location and count form parameters from a form's POST method or from a query string. Each HTTP request that arrives with a different location or count parameter (or both) is cached for ten seconds. Any subsequent requests with the same parameter values are satisfied from the cache until the entry expires.

<%@ OutputCache Duration="10" VaryByParam="location;count" %>

@ Page

Defines page-specific (.aspx file) attributes used by the ASP.NET page parser and compiler.

<%@ Page attribute="value" [attribute="value"...] %>

Attributes

---

Async

Makes the page an asynchronous handler (that is, it causes the page to use an implementation of IHttpAsyncHandler to process requests).

The default is false.

AsyncTimeOut

Defines the time-out interval (in seconds) used when processing asynchronous tasks. The default is 45 seconds.

The value must be an integer.

For more information, see the AsyncTimeout property.

AspCompat

When set to true, allows the page to be executed on a single-threaded apartment (STA) thread. This allows the page to call STA components, such as a component developed with Microsoft Visual Basic 6.0. Setting this attribute to true also allows the page to call COM+ version 1.0 components that require access to unmanaged Active Server Pages (ASP) built-in objects. These are accessible through the ObjectContext object or the OnStartPage method. The default is false.

Note-Setting this attribute to true can cause your page's performance to degrade. For more information, see the Remarks section.

AutoEventWireup

Indicates whether the page's events are autowired. true if event autowiring is enabled; otherwise, false. The default is true. For more information, see ASP.NET Web Server Control Event Model.

Buffer

Determines whether HTTP response buffering is enabled. true if page buffering is enabled; otherwise, false.

The default is true.

ClassName

A string that specifies the name of the page class that will be dynamically compiled when the page is requested. This value can be any valid class name and can include a fully qualified class name. If a value for this attribute is not specified, the class name for the compiled page is based on the page's file name and uses the default namespace ASP. If a value for the ClassName attribute is specified without a full namespace, then the namespace ASP is used, combined with the specified class name to create a fully qualified class name.

Another page can reference the class name assigned to the first page by using the @ Reference directive.

Note-It is possible in the code-behind page class to reference members of the associated .aspx page class using the fully qualified class name for the .aspx page. However, if you precompile your site with source protection enabled, the code-behind page class is not located in the same assembly as the .aspx page class. Therefore the class reference in the code-behind file will not work. For more information on precompilation, see ASP.NET Precompilation Overview.

ClientIDMode

Specifies the algorithm to use to generate ClientID values for controls. The default value is Predictable. The default value for controls is Inherit. Therefore, the default algorithm for controls in a page is determined by the ClientID setting of the page. A different default value can be set in the pages element of the Web.config file. For more information about the algorithms, see the ClientIDMode class.

ClientTarget

Indicates the target user agent (typically, a Web browser such as Microsoft Internet Explorer) for which ASP.NET server controls should render content. This value can be any valid alias as defined within the section of the application's configuration file. For more information, see the ClientTarget property.

CodeBehind

Specifies the name of the compiled file that contains the class associated with the page. This attribute is not used at run time.

This attribute is used for Web application projects. The CodeFile attribute is used for Web site projects. For more information about Web project types in Visual Studio, see Web Application Projects versus Web Site Projects.

CodeFile

Specifies a path to the referenced code-behind file for the page. This attribute is used together with the Inherits attribute to associate a code-behind source file with a Web page. The attribute is valid only for compiled pages.

This attribute is used for Web site projects. The CodeBehind attribute is used for Web application projects. For more information about Web project types in Visual Studio, see Web Application Projects versus Web Site Projects.

CodeFileBaseClass

Specifies the type name of a base class for a page and its associated code-behind class. This attribute is optional, but when it is used the CodeFile attribute must also be present. Use this attribute when you want to implement a shared scenario, where you define common fields (and optionally, associated events) in a base class to reference the controls declared in a Web page. Because of the ASP.NET code generation model, if you defined the fields in a base class without using this attribute, at compile time new member definitions would be generated for the controls declared in the Web page (within a separate partial class stub), and your desired scenario would not work. But if you use the CodeFileBaseClass attribute to associate the base class with the page, and you make your partial class (its name is assigned to the Inherits attribute and its source file is referenced by the CodeFile attribute) inherit from the base class, then the fields in the base class will be able to reference the controls on the page after code generation.

CodePage

Indicates the value of the encoding scheme used for the response. The value is an integer that serves as an ID for the encoding scheme. For a list of possible CodePage IDs, see the Encoding class.

CompilationMode

Sets whether the page should be compiled, using a string that specifies one of several enumerated options. The default value is Always, so .aspx pages are compiled by default. For details, see the CompilationMode enumeration.

CompilerOptions

A string containing compiler options used to compile the page. In C# and Visual Basic, this is a sequence of compiler command-line switches. For more information about compiler options, see C# Compiler Options or Visual Basic Compiler.

ContentType

Defines the HTTP content type of the response as a standard MIME type. Supports any valid HTTP content-type string. For a list of possible values, search for MIME in the MSDN Library.

Culture

Indicates the culture setting for the page. The value of this attribute must be a valid culture ID. Note that the LCID and Culture attributes are mutually exclusive; if you use one of these attributes, you cannot use the other in the same page. For more information about, see the Culture property and the CultureInfo class.

Debug

Indicates whether the page should be compiled with debug symbols. true if the page should be compiled with debug symbols; otherwise, false. Because this setting affects performance, you should only set the attribute to true during development.

Description

Provides a text description of the page. This value is ignored by the ASP.NET parser.

EnableEventValidation

Enables validation of events in postback and callback scenarios. true if events are being validated; otherwise, false. The default is true.

Page event validation reduces the risk of unauthorized postback requests and callbacks. When the enableEventValidation property is set to true, ASP.NET allows only the events that can be raised on the control during a postback request or callback. With this model, a control registers its events during rendering and then validates the events during the post-back or callback handling. All event-driven controls in ASP.NET use this feature by default.

It is strongly recommended that you do not disable event validation. Before disabling event validation, you should be sure that no postback could be constructed that would have an unintended effect on your application.

EnableSessionState

Defines session-state requirements for the page. true if session state is enabled; ReadOnly if session state can be read but not changed; otherwise, false. The default is true. These values are case-insensitive. For more information, see ASP.NET Session State Overview.

EnableTheming

Indicates whether themes are used on the page. true if themes are used; otherwise, false. The default is true.

EnableViewState

Specifies whether view state is maintained across page requests. This value is true if view state is maintained, or false if view state is not maintained. The default is true.

Even if this property is set to true, view state will not be maintained for a control if any of the following conditions apply:

·         The control's EnableViewState property is set to false.

·         The control's ViewStateMode property is set to Disabled or the control inherits the Disabled value.

For more information about view state and control state, see the Control.EnableViewState property.

EnableViewStateMac

Indicates that ASP.NET should verify message authentication codes (MAC) in the page's view state when the page is posted back from the client. true if view state should be MAC checked; otherwise, false. The default is true.

A view-state MAC is an encrypted version of the hidden variable that a page's view state is persisted to when sent to the browser. The MAC is used to verify that view state has not been tampered with on the client.

Security Note-This attribute should never be set to false in a production Web site.

ErrorPage

Defines a target URL for redirection if an unhandled page exception occurs. For more information, see the ErrorPage property.

Explicit

Determines whether the page is compiled using the Visual Basic Option Explicit mode. true indicates that the Visual Basic explicit compile option is enabled and that all variables must be declared using a Dim, Private, Public, or ReDim statement; otherwise, false. The default is false.

Note-This attribute is ignored by languages other than Visual Basic. Also, this option is set to true in the Machine.config configuration file. For more information, see ASP.NET Configuration Files.

Inherits

Defines a code-behind class for the page to inherit. This can be any class derived from the Page class. This attribute is used with the CodeFile attribute, which contains the path to the source file for the code-behind class. The Inherits attribute is case-sensitive when using C# as the page language, and case-insensitive when using Visual Basic as the page language.

If the Inherits attribute does not contain a namespace, ASP.NET checks whether the ClassName attribute contains a namespace. If so, ASP.NET attempts to load the class referenced in the Inherits attribute using the namespace of the ClassName attribute. (This assumes that the Inherits attribute and the ClassName attribute both use the same namespace.)

For more information about code-behind classes, see ASP.NET Web Page Code Model.

Language

Specifies the language used when compiling all inline rendering (<% %> and <%= %>) and code declaration blocks within the page. Values can represent any .NET Framework-supported language, including Visual Basic, C#, or JScript. Only one language can be used and specified per page.

LCID

Defines the locale identifier for the Web Forms page.

Note-The locale identifier is a 32-bit value that uniquely defines a locale. ASP.NET uses the default locale of the Web server unless you specify a different locale for a Web Forms page by using this attribute. Note that the LCID and Culture attributes are mutually exclusive; if you use one of these attributes, you cannot use the other in the same page. For more information about locales, search the MSDN Library.

LinePragmas

Determines whether the runtime should generate line pragmas in the source code. These are compiler options that are often used by debugging tools to mark specific locations in a source file. true if line pragmas should be generated; otherwise, false.

MaintainScrollPositionOnPostback

Indicates whether to return the user to the same position in the client browser after postback. true if users should be returned to the same position; otherwise, false. The default is false.

Note-Developers can define this attribute for all pages by setting the maintainScrollPostitionOnPostback attribute (note that it is case-sensitive in configuration files) on the element of the Web.config file.

MasterPageFile

Sets the path to the master page for the content page or nested master page. Supports relative and absolute paths. For more information, see the MasterPageFile property.

MetaDescription

Sets the MetaDescription property. If the page markup also includes a "description" meta element, the value in the @ Page directive overrides the value in markup.

MetaKeywords

Sets the MetaKeywords property. If the page markup also includes a "keywords" meta element, the value in the @ Page directive overrides the value in markup.

ResponseEncoding

Indicates the name of the encoding scheme used for the HTTP response that contains a page's content. The value assigned to this attribute is a valid encoding name. for a list of possible encoding names, see the Encoding class. You can also call the GetEncodings method for a list of possible encoding names and IDs.

SmartNavigation

Indicates whether the page supports the smart navigation feature of Internet Explorer 5.5 or later. true if smart navigation is enabled; otherwise, false. The default is false.

In ASP.NET version 2.0 and later versions, the SmartNavigation property is obsolete. Use the SetFocus method and the MaintainScrollPositionOnPostback property instead.

Src

Specifies a path to a source file containing code that is linked to the page. In the linked source file, you can choose to include programming logic for your page either in a class or in code declaration blocks.

You can use the Src attribute to link build providers to the page. For more information, see the BuildProvider class. Also, in versions of ASP.NET prior to 2.0, the Src attribute was used as an alternative way to link a code-behind file to a page. In ASP.NET 2.0, the preferred approach to linking a code-behind source file to a page is to use the Inherits attribute to specify a class, along with the CodeFile attribute to specify the path to the source file for the class.

Strict

Indicates that the page should be compiled using the Visual Basic OptionStrict mode. true if Option Strict is enabled; otherwise, false. The default is false.

Note-This attribute is ignored by languages other than Visual Basic.

StyleSheetTheme

Specifies a valid theme identifier to use on the page. When the StyleSheetTheme attribute is set, individual controls can override the stylistic settings contained in a theme. Thus a theme can provide an overall look for a site, while the settings contained in the StyleSheetTheme attribute enable you to customize particular settings on a page and its individual controls.

TargetSchema

Specifies the name of a schema that validates content on the page. This serves only a descriptive purpose; no actual validation is performed, and the attribute is ignored by the parser.

Theme

Specifies a valid theme identifier to use on the page. When the Theme attribute is set without using the StyleSheetTheme attribute, it overrides individual style settings on controls, enabling you to create a unified and consistent look on a page. For more information, see the Theme property.

Title

Specifies a title for the page that is rendered within the HTML