ASP.NET Quickstart Tutorial

Extending ASP.NET

Page Framework Lifecycle

• Page.InitializeCulture where you can explicitly handle the UICulture and Culture for localization, e.g. from Profile;
• Page.OnPreInit, Page_PreInit, where you can dynamically set the Page.Theme or Page.MasterPageFile;
• Control.LoadControlState, Control.SaveControlState to explicitly handle new state management functionality;
• Other new page events, like OnInitComplete, OnPreLoad, OnLoadComplete, OnPreRenderComplete, OnSaveStateComplete etc.

Server Controls Runtime

When creating custom controls you can compile your controls into assemblies that are added to the application's Bin directory or in ASP.NET 2.0, you can add code file(s) to the application's App_Code directory. In this case ASP.NET 2.0 will dynamically compile the control. You can also in ASP.NET 2.0 reuse tag prefixes when registering controls from multiple namespaces. So it is possible to create several controls in several namespaces that all contribute to the same tag prefix.

<%-- Register the controls defined in an assembly that resides in the Bin directory --%>
<%@ Register TagPrefix="Demos" NameSpace="DemoControls" Assembly="MyDemoControls" %>

<%-- Register the controls defined in code that resides in the App_Code directory --%>
<%@ Register TagPrefix="Demos" NameSpace="DemoControls" %>

<Demos:ControlFromBinAssembly runat="server" ID="CustomControl1" />
<Demos:ControlFromCodeFile runat="server" ID="CustomControl2" />

Control Classes

		
public class MyCompositionControl : CompositeControl {
	protected override void CreateChildControls() {
		Controls.Clear();
		// Create control collection ..
	}
	..
}

The CompositeControl is a WebControl and implements INamingContainer. The Controls collection calls EnsureChildControls. You would create all child controls in CreateChildControls. The base class provides design-time support, again ensuring the Controls collection is created.

You can enable a page developer to style your control by exposing top-level properties that delegate to the child control style properties. If you have many properties and controls, then consider exposing properties of type Style and applying these during render methods so that child controls do not persist these as view-state, but rather the parent handles state management of these complex properties.

Control Class and Property Meta-data

• LocalizableAttribute: Localization is enabled for all controls and objects, including static markup in a web application through the use of expressions, (both implicit and explicit). These features are 'layered' on a control at parse-time and you do not need to add any special handling to your control. During design-time, Visual Studio will 'push' values to a neutral resource for properties that are marked with the LocalizableAttribute.
• ThemeableAttribute: Page developers and developers performing customization can take advantage of themes to affect the stylistic appearance and to some extent the content of a page or site. All properties are by default theme-able, so if there are properties that you decide should not be theme-able, such as sensitive data properties or properties that are not style-based, mark them as Themeable(false).
• UrlPropertyAttribute: Where a control could be used in master-page for example, or other such types then Url type properties will potentially require re-basing (an image or a style sheet). In order to base the Url property value to the consuming page, e.g. a content-page in a master-page, content-page relationship the page framework will rebase that Url when marked with this attribute;
• WebResourceAttribute: Used to mark the assembly that contains an embedded resource, so that resource can be served in a request;
• FilterableAttribute: Used to mark control properties, or controls that wish to support the device filtering, declarative syntax in the page.

State Management

		
protected override void OnInit(EventArgs e) {
	base.OnInit(e);
	Page.RegisterRequiresControlState(this);
}
protected override object SaveControlState() {
	object o = base.SaveControlState();
	..
	return new Pair(o, ViewIndex);
}
protected override void LoadControlState(object state) {
	Pair p = state As Pair;
	if (p != null) {
		base.LoadControlState(p.First);
		ViewIndex = (int)p.Second;
	}  
	..
}

In ASP.NET 2.0, the control-state and view-state are combined in the hidden field in the page rendering. You can make a request to the page to encrypt the field, (Page.RegisterRequiresViewStateEncryption) if you need to round-trip potentially sensitive data.

Control and Page Adapters: Handling Behavior for Devices, Browsers or Markups

The HttpBrowserCapabilities creation process uses declarative browser files that reside in the install directory under Browsers and/or the application's local App_Browsers directory. The following snippet shows a custom browser file that maps a custom adapter for a custom control; the assembly containing the adapter is created in the App_Code directory of the application.

<!-- New browser node links into parent -->
<browser id="My_PIE_PPC" parentID="PIEnoDeviceID">
	<identification>
        	<capability name="browser" match="Pocket IE" />
        	<capability name="majorversion" match="4" />
    	</identification>

	<!-- Define new text-writer for this browser and define control-adapter mapping -->
    	<controlAdapters markupTextWriterType="MyNamespace.MyCustomTextWriter" >
	<adapter controlType="MyNamespace.MyControl" adapterType="MyNamespace.MyControlAdapter" />
    </controlAdapters>
</browser> 

During the page framework lifecycle, ASP.NET 2.0 attempts to look for an adapter on the control using the Control.ResolveAdapter method. If an adapter is returned, the page framework will call on the adapter methods instead of the control's lifecycle methods. As an extensibility developer you can extend the adapter base classes, e.g. ControlAdapter, WebControlAdapter and PageAdapter and define overrides for the lifecycle stages and other methods such as child control creation and post-back handling.

• The base adapter classes call back on the control's equivalent method. It is typical therefore, to call on the base method in your adapter. This is not necessarily true of the Render method(s), as you could end-up with unwarranted markup behavior;
• Adapters can implement IPostBackEventHandler and IPostBackDataHandler to handle post-back data and raise events;
• Adapters can implement view-state and control-state methods, LoadAdapterViewState, SaveAdapterViewState and LoadAdapterControlState, SaveAdapterControlState. These methods contribute to the control's behavior however;
• Adapters can implement CreateChildControls and handle data-binding calls;
• Alternatively you can prevent 'adaptation' for your custom control by returning null from Control.ResolveAdapter.

		
// Control
public class MyControl : Control {
	// Example showing override of Render to control entire rendering
	protected override void Render(HtmlTextWriter writer) {
		Style s = new Style();
		s.ForeColor = System.Drawing.Color.Green;
		writer.EnterStyle(s);			
		writer.Write("Welcome custom control.");
		writer.ExitStyle(s);
	}
	..
}
// Adapter	
public class MyControlAdapter : ControlAdapter {
       	// Example showing override of Render to control entire rendering
	protected override void Render(HtmlTextWriter writer) {
		Style s = new Style();
		s.ForeColor = System.Drawing.Color.Red;
		writer.EnterStyle(s);
       		writer.Write("Welcome custom control adapter.");            
		writer.ExitStyle(s);
       	}
	..
}

Data Source and Data Bound Controls

• Represent one or more named views of data
• Each view provides an enumeration of objects
  • Essentially SELECT in SQL terms
• A view may also be able to perform editing operations on its collection of objects
  • Essentially UPDATE, INSERT, DELETE in SQL terms.
  • Capabilities model exposed as boolean properties
• Ability to trigger change events
• Ability to load data on-demand

public interface IDataSource {
    event EventHandler DataSourceChanged { add; remove; }
    DataSourceView GetView(string viewName);
    ICollection GetViewNames();
}

public abstract class DataSourceControl : 
  Control, IDataSource, IListSource {
  ...
}

public abstract class DataSourceView {

    public virtual bool CanDelete { get; }
    // CanInsert, CanPage, CanSort, CanUpdate, ...

    public event EventHandler DataSourceViewChanged;
    public virtual int Delete (IDictionary keys, IDictionary oldValues, ...);
    public virtual bool Insert (IDictionary values, ...);
    public virtual int Update (IDictionary keys, IDictionary values, IDictionary oldValues, ...);
    public abstract IEnumerable Select(DataSourceSelectArguments arguments);
}

Web Resources

		
// Mark the assembly with the resource
[assembly: WebResource("MyClientScript.js", "text/javascript")]

public class MyControl : WebControl {
	protected override void OnInit(EventArgs e) {
		// Register the script to be rendered as a link
                String sScript = Page.ClientScript.GetWebResourceUrl(typeof(MyControl), 
			"MyClientScript.js");
                Page.ClientScript.RegisterClientScriptInclude("MyInclude", sScript);
		base.OnInit(e);		
	}
	..
	protected override void OnPreRender(EventArgs e) {
		this.Attributes["onmouseover"] = "MouseOverScript()";
		base.OnPreRender(e);	
	}
}

Client Script Management

		
public class MyButton : Button {
	protected override void OnPreRender(EventArgs e) {
		String sScript = "function DoAlert(){alert('Hello World');}";
                this.Page.ClientScript.RegisterClientScriptBlock(typeof(MyButton), 
			"ScriptFunction", sScript, true);

                OnClientClick = "javascript:DoAlert();";
                base.OnPreRender(e);
	}
	..
}

Device, (device markup or browser) Filtering

<!-- Text property is defaulted to a value, reset given IE and also if the custom filter applies. --> 
<!-- The more specific the device-filter wins.. -->
<asp:Label runat="server" Id="WelcomeLabel" Text="Welcome to ASP.NET's Quickstarts" 
	IE:Text="Quickstarts" MyFilter:Text="Welcome" />

Call-backs

• Create a call back event with a given signature in your class. (ICallbackEventHandler);
• Create client-side script that will manage the return call or error;
• Use the call back event reference hooked up to a client-side event in your custom control.

		
public class MyControl : CompositeControl, ICallbackEventHandler {
        public string ICallbackEventHandler.RaiseCallbackEvent(string eventArgument) {
            if (eventArgument == "Dogs") 
                return "Labrador";
            else
                throw new ApplicationException("Only Dogs allowed!");
        }
	.. 
	// Client script functions that handle the callback
	private String sButtonCallBack = 
		"function ButtonCallBack(result, context){ alert(result);}";
	private String sButtonCallBackError = 
		"function ButtonErrorCallBack(result, context){ alert(result);}";

        protected override void OnInit(EventArgs e) {
            	base.OnInit(e);
		..
		Page.ClientScript.RegisterClientScriptBlock(typeof(MyControl), 
			"ButtonCallBack", sButtonCallBack, true);
		Page.ClientScript.RegisterClientScriptBlock(typeof(MyControl), 
			"ButtonCallBackError", sButtonCallBackError, true);
	}
	..
	protected override void OnPreRender(EventArgs e) {
            // Set up the OnClick event to fire an out-of band call to the handler
		Attributes["OnClick"] = Page.ClientScript.GetCallbackEventReference(this, 
			"'Dogs'", "ButtonCallback", "null", "ButtonErrorCallback", true);
                base.OnPreRender(e);
	}
}

Page-state

ASP.NET 2.0 also enables the splitting up the single hidden field into several using the maxViewStateFieldLength attribute in configuration.

Server Controls Design-time

• Region-based editing. In ASP.NET 1.x you would use a ReadWriteControlDesigner to provide a single read/write area for your control on the design-surface. In ASP.NET 2.0 you can create editable, template-able and read-only regions (DesignerRegion types) for richer editing experiences. Regions can also provide tool-tips and highlighting. You can also handle click events on the control and interact with the regions;
• Painting on the design-surface. You can provide graphics on the design-surface for your control by indicating that the control supports painting and overriding OnPaint;
• Control-designer types can interact with the control more closely with accessors but also can take advantage of control features such as embedded resources like images;
• Task-based editing. Using DesignerActionLists you can provide a very visual, contextual task list for page developers to interact with. This advances the previous concept of DesignerVerbs;
• Improved and much simplified template-editing. Your control-designer can defer simply to the tool's template editing UI or you can create your own UI using regions. Adding template editing is now as simple as defining the TemplateGroups collection on the ControlDesigner;
• Several new convenient control-designer base classes, CompositeControlDesigner and ContainerControlDesigner for common scenarios.

		
[Designer(typeof(MyDesigner)), ParseChildren(false), PersistChildren(true)]
public class MyControl : WebControl { }

public class MyDesigner : ContainerControlDesigner {
	private Style _style = null;
	public override string FrameCaption { get { /* Return a caption */"; } }
	public override Style FrameStyle { get { /* Return a Style for the frame*/ } }

	public override DesignerActionListCollection ActionLists {
		get { 
			// Get the base collection and add my own list
			..
			al.Add(new MyList(this));	
			return al;
		}
	}
	private sealed class MyList : DesignerActionList {
		// Members to handle the smart-tag
		..
		public override DesignerActionItemCollection GetSortedActionItems() {
			// Create a collection and add DesignerActionTextItem, 
			// DesignerActionPropertyItem and DesignerActionMethodItem types
		}
	}
}

Application Service Providers

• Membership
• Role Manager
• Session State
• Profile
• Site Navigation
• Site Counters
• Web Parts Personalization
• Web Events

Expression Builders

• Connection strings. Used to access connection-strings in configuration. <%$ connectionstrings: MyConnStr %>;
• Application settings. Used to access the application setting in configuration. <%$ appsettings: MyAppValue %>, and;
• Resources. Used as the foundation for building a multi-lingual site. <%$ resources: mykey %>.

Expression builders can also be constructed to support the no compile feature of ASP.NET 2.0. Instead of ASP.NET generating code through the expression builder during the generation of the page-class, the runtime instead instantiates the expression builder and evaluates the expression. The following example shows a pseudo ExpressionBuilder and ExpressionBuilderEditor. .

// In configuration, add your expression builder. Here the type is defined in App_code
<expressionBuilders>
	<add expressionPrefix="MyExpr" type="MyExpressionBuilder" />
</expressionBuilders>

// In code, create Expression builder and define the prefix, the editor etc.
[ExpressionPrefix("MyExpr"), ExpressionEditor("MyExpressionEditorDesigner"]
public sealed class MyExpressionBuilder : ExpressionBuilder {
        public override bool SupportsEvaluate {
            get {
                return true; // Supports the evaluation for no compile scenarios
            }
        }

        public override CodeExpression GetCodeExpression(..) {
		// Return a code expression, given the expression
	}

        public override object EvaluateExpression(..) {
            // Return an evaluation of the expression for no compile scenarios
        }
	..
}

// The editor is used at design-time.
public sealed class MyExpressionEditor : ExpressionEditor {
       	public override ExpressionEditorSheet GetExpressionEditorSheet(..) {
		// Create a sheet
       		return new MyExpressionEditorSheet(..);
       	}

        public override object EvaluateExpression(..) {
		// Return an evaluation during design-time
        }

       	private sealed class MyExpressionEditorSheet : ExpressionEditorSheet {

		// Expose any properties that represent the expression's value, you can define
		// default values, type converters and descriptions
	}
}

Localization

// In configuration. Here the type is defined in App_Code
<globalization resourceProviderFactoryType="MyResourceProviderFactory" ../>

// In code. Note that to support design-time too, add the following attribute and
// define the provider
[DesignTimeResourceProviderFactoryAttribute(typeof(MyDesignTimeResourceProviderFactory))]
public sealed class MyResourceProviderFactory: ResourceProviderFactory {
       	public override IResourceProvider CreateGlobalResourceProvider(string classKey) {
       		return new MyGlobalResourceProvider(classKey);
       	}
       	public override IResourceProvider CreateLocalResourceProvider(string virtualPath) {
       		return new MyLocalResourceProvider(virtualPath);
       	}

	private sealed class MyGlobalResourceProvider: IResourceProvider {
       		object IResourceProvider.GetObject(string resourceKey, CultureInfo culture) {
			// Get a resource object for the resource key and culture
		}
		IResourceReader ResourceReader {
       			get { /* return a reader that enumerates the neutral resource */ }
		}    
	}
	..            
}		

Compilation and Pre-compilation

Dynamic compilation includes for example, code separation files associated with web pages and user controls, code in the App_Code directory and abstract files such as ASPX, ASCX, RESX, and also, WSDL, XSD.

There are two forms of pre-compilation of sites for deployment as well as a pre-compilation mode that 'primes' the site. Pre-compiling for deployment can be performed in two ways that either allows specific updates to the compiled site or not. In both cases code is removed from the compiled site (target). Where no updates are selected, the declarative files like ASPX are removed too. Pre-compiling to prime a site means that ASP.NET will perform regular compilation of the entire site to avoid the first-time request penalty.

To precompile a site, you can use the aspnet_compiler.exe tool. This tool is located in the .NET Framework installation directory, for example %WINDIR%\Microsoft.NET\Framework\<version>. You can run the tool with a /? switch to see the list of available options. For example, to pre-compile a site in-place by specifying the virtual path to the application, use the following command line:

  > aspnet_compiler.exe -v /MyApp c:\MyTarget

You can also extend the compilation processes in a number of ways; by contributing new file types or extensions to the compilation using BuildProviders, or by making specific content virtual so that the source is for example not on disk. The VirtualPathProvider provides this extensibility point.

Build Providers

// In configuration
<compilation ..>
	<buildProviders>
		<add extension=".myext" type="MyBuildProvider, .." appliesTo="All"/>
	</buildProviders>
</compilation>	

public class MyBuildProvider : BuildProvider {
	..
	public override void GenerateCode(AssemblyBuilder assemBuilder) {
		// Return code, e.g. a CodeCompileUnit that is added to the 
		// assembly builder. This will involve custom parsing and code generation	
	}
       	public override System.Type GetGeneratedType(CompilerResults results) {
		// Return the type generated (e.g. MyNamespace.MyClass)
       	}
}

If you need to obtain a type in application code you can use the BuildManager.GetType method as assembly names are not predictable.

Virtual Path Provider

Your virtual path provider can return content for a virtual path, or simply hand off to the previous provider in the chain.

// In code in the App_Code directory
public sealed class MyVirtualPathProvider : VirtualPathProvider {

	public static void AppInitialize() {
		MyVirtualPathProvider myVpp = new MyVirtualPathProvider();
		HostingEnvironment.RegisterVirtualPathProvider(myVpp);
	}

	// Implement other methods that define file hashing and dependencies ..
	
	public override bool FileExists(string virtualPath) {
		// Return whether this virtualPath exists, or defer to the Previous.
	}
	public override bool DirectoryExists(string virtualDir) {
		// Return whether this virtualDir exists, or defer to the Previous.
	}
	public override VirtualFile GetFile(string virtualPath) {
		// Handle the virtualPath and return a 
		// VirtualFile or defer to Previous. 
		// VirtualFile implements an Open method to return a Stream
	}
	public override VirtualDirectory GetDirectory(string virtualDir) {
		// Handle the virtual directory and return a 
		// VirtualDirectory or defer to Previous.
		// VirtualDirectory implements enumerations of sub-dirs and files
	}
	
}