CodeProject: Building a Better ASP.NET 1.1 BasePage Framework. Free source code and programming help

This is a journey on how to build a better Base page. The result of this will be a reusable framework that you can use to create as many Base pages as you like (on many different sites) and still have something that will keep the designers on your team happy. There is a lot to explain so I am breaking this up into several parts starting with the pros and cons of all the approaches I have seen in the past.

Whenever I start a new ASP.NET project I am asked how to make a look and feel that can be reused on all pages of the site. The following are the several approaches I have seen to date:

Have a designer create an HTML template and reuse it in all your pages

Comments: This is the approach I have seen done by folks breaking into ASP.NET development. Maintaining sites like this can be a nightmare to say the least. Just pray your client does not ask to change the main look and feel or you will be staying late to get it done�

Create user controls and reuse them on all pages of the site

Comments: This is a little better as it makes use of User Controls to centralize the look and feel into separate components but can still be problematic and time consuming when the main look and feel templates need to be added/removed.

Create a base page and hardcode the look and feel into the base page�s OnInit() call

Comments: We used this approach at two different client sites and it worked well. However when I presented this approach to the client I was at when I wrote this, they balked and wanted to know how to use the visual designer and also how to make changes without compiling and redeploying the site DLL. The next approach is the answer to that question.

Create UserControls for all the sections of your main look and feel, and dynamically load them when your Base page is generated

Comments: Although this approach served us well at a client site, we also did not have to worry about them changing the main layout (yet). If that happens I am going to recommend migrating to the next approach which is the approach we are going to be implementing in this series of posts related to this topic.

Build a Basepage base framework in a separate library and reference it in your websites � derive from this Base page and create 1-n Basepages that you can use within your site � make each Base page configurable in the Web.Config file

I mention ASP.NET 2.0 here because the fact that it�s coming soon will make most of the ASP.NET 1.1 techniques in this article obsolete.

Comments � We have used this approach at several clients in the past, it has worked well in the past. One of the things I did not like about it was the lack of centralized configuration and no way to solidify the state objects in our site. It would be nice to have a framework that did all this, that is what we are going to do in this article.

So why write this article? Simple, even though I have seen a lot of companies upgrade their systems to Windows 2003 Server, Windows XP and have embraced using the .NET framework, I do know of a few places that are still stuck using NT 4 Server (even though the client machines are on Windows 2000 Professional which for them are doing well). So yes, using this approach will be invalid when VS.NET 2005 is released to the world. But for the rest of us that get stuck working with old technology, this will be a huge timesaver.

To close this section, I will describe the steps to get started on your own BasePage Framework implementation.

Add an XML file so we have a place to put our configuration stuff (this does not need to be part of the project, it�s just a nice place to keep our configuration schema for the Base pages).

Part II - Implementing the Configuration Handler

I am going to continue this where we left off in part one, so I am skipping the steps for setting up our Base Page Framework project. Refer to part one to see these steps�

Now I like to centralize everything that is consistent about the pages in my site (i.e. script links, CSS files, body attributes, default name etc...) in one place. I have seen other base pages hard code this stuff which always makes me shudder. (As it should everyone because hard coding things like this should be avoided.)

IMHO it makes sense to place these stuff in a location that can be changed without having to recompile our project. My favorite place for this is the Web.Config file. But since this is a separate framework assembly, it might be a good idea to not use the default <add key="" value=""/> settings available in the <appsettings> section because I personally think this is less intuitive as to what the settings are for. Plus it would be nice to not clutter our appsettings for this application with the configuration information that is going to be used across one to many sites. To solve this problem, we create a custom configuration section for our Base Page Framework. That is the subject of this section.

The first thing we need to do for our base page framework is to create a custom configuration handler to parse the custom configuration settings in our web.config. (See part one for the schema). We do this by implementing the IConfigurationSectionHandler interface which is part of the System.Configuration namespace. This is really easy to do and if you know how to parse XML, you are 4/5th of the way there.

The IConfigurationSectionHandler interface has one method called Create(). Here is the prototype for Create and what each argument is intended to provide:

Returns

Parameters

I like to keep my items in any project logically separated, so create a folder for our configuration stuff. Call it �configuration�. Add a class to this folder and call it BasePageConfigurationSectionHandler. This class will be our configuration handler so implement the IConfigurationSectionHandler interface. Here is the code:

In this implementation, we are going to return the next class we are going to create which is the BasePagesConfiguration class. If you look at the schema for our configuration you will see that there can be 1:n page elements. This is because you can have more than one base page in your site. So if you guessed that BasePagesConfiguration is a collectionbase object, then you guessed right. We are going to need to implement this object next. Here is the code:

The indexer of this object returns a single BasePageConfiguration object via a key value. I am not too concerned with how quickly the collection returns individual configuration objects so I am using a simple loop. The reason we don�t really care about performance here is because our base page will internally cache its configuration object so it does not have to keep going out to the config file every time it gets requested.

Finally we get to the configuration object. We are going to aptly call this BasePageConfiguration. Create the BasePageConfiguration class in your project. Here is the code. I am going to assume that you know how to parse XML documents so I am not going to go into detail on how that works. I will just explain what each field of this object is for.

Finally as you can see, the configuration is a read only object. This is logical because it will only get its values from the configuration file when the object is created by the configuration handler.

Using this handler is easy. To create an instance of the configuration handler, you need to call GetConfig() in your ConfigurationSettings object.

Returns: the appropriate configuration object based on your section in the configSections tag. See the following snippet taken from the schema we created in part one.

The object that gets returned here is whatever you decided to return from your IConfigurationSectionHandler.Create implementation. In this case, it is our ReadOnlyCollectionBase "BasePagesConfiguration" object that contains the individual BasePageConfiguration objects for our site.

The name attribute of this configuration section is the configuration section in your .config file. The type is the fully qualified object name that implements the IConfiguraitonSectionHandler interface, along with the name of the assembly this object resides in, separated by a comma. If you are referencing a strong named assembly then you need to put all four parts of the assembly name into the type attribute like this (taken from System.dll):

As you can see, you put the remaining four parts of the strong name into the type tag after your DLL name (separated by commas).

In part 3, we are going to get started on the implementation of the SuperBasePage itself. To close in part 4, I am going to show you how to throw in some extra features that wrap standard site state management. The objects are classes that implement the ISmartQueryString, ISmartSession, and ISmartApplication interfaces.

Part III - Implementing the SuperBasePage

I am going to continue this at the point where we left off creating the BasePageConfiguration class. In this part, we are going to implement the SuperBasePage that will be used in all the derived Base pages of your site. It is useful to have multiple Base pages in your site because you might want to have a layout for printer friendly pages, popup windows, dialogs, etc�

This part is a bit on the long side, I will try to keep it as short as possible given the amount of stuff that�s happening here. I will also post some UML class and sequence diagrams in the next part so there will be some decent docs to go with it.

The SuperBasePage is actually two separate classes and a user control that implements a custom interface all working together to form a template. They are declared as follows:

These three items when properly used will not only allow us to quickly create Base pages that can be configured from the web.config, but also allows us to leave the HTML in our individual pages on our site. I have seen other frameworks / Base page concepts where you need to remove the HTML, HEAD, TITLE, BODY, and FORM tags in order to be useable. We will not be doing that here. It is important that we keep that part intact for two reasons:

To start with, we need to look at the existing objects at our disposal in the System.Web namespace. The ones we are interested in right now are System.Web.UI.Page and System.Web.UI.HtmlControls.HtmlForm. The latter of the two is what we will be worrying about first.

The HtmlForm when set with a server tag becomes the heart of the ubiquitous ASP.NET webform. You cannot instantiate server controls on your page without it. Herein lies our problem, how can we get our form which we have to define on each page to behave the same by displaying the same outlying content with unique content for each page, and more importantly, how do we get the content from our page to actually nest itself within this form�s content area? What I have seen done in past Base pages I have developed is to �move� the content from each of their pages to a specified �content area� in their Base page class. We are still doing that here but in a more discreet way. And, as I have already mentioned, most of the examples force you to delete the HTML header and footer along with the Form tag from your page before using it (try explaining that to a web-designer and see what they do).

There must be a better way, so instead of moving the content from our derived page to the Base page�s content area, we will do a little switcharoo with the HtmlForm and change it into a form that has the following functionality�

So in essence instead of our Base page high-jacking the content of each page, our Base page receives an HtmlForm and makes it work in such a way that allows us to set content wherever we want from a given template that the form will initialize when it gets created. You will notice that our BaseServerForm is nothing more than a plain old HtmlForm with a template reference. The following is the code for our Base server form�

The constructor of this class takes two things, an HtmlForm object and a reference to something called an IBaseTemplate. This is how you will implement the IBaseTemplate in your code�

This template interface is how I get around a limitation in another framework that does almost the same thing this one does. Why define an interface to be used for our complete Base layout if we may want to change that layout in the future? What I think makes sense is to define a class that exposes our Base page�s content areas so we can change what they contain at will. Plus, it would also be nice to create different layouts with access to all areas in our page. This will also allow us to dynamically change our layouts at runtime under certain conditions. Finally, it would also be really nice if our designers could change the look of the Base page without going into the code but instead by using the designer. That is where using a UserControl (that implements our IBaseTemplate interface) comes in handy.

There is one gotcha however, we can�t be sure of what the template developer is going to call the area to place our content. We really need to know this so we can relocate the pages controls to this area in a nice seamless and discreet manner. This is where the IBaseTemplate interface comes in to play. As you can see in the above example, we define a placeholder where our derived pages' content will go in the Base page and return it through this interface's only property �ContentArea� (which coincidentally returns a placeholder for our content). Now our Base page will have a contract with the UserControl that says �I will assume responsibility of locating the controls where they belong so you don�t have too�.

You will see later on in the Base page definition why we need to expose the other placeholders in our user control to the outside world via properties as I have done in the above example.

The BaseServerForm class doesn�t do much other than encapsulate the movement of our page's content to the template�s content area (and perform the role of server form) so besides loading a UI template, it is basically just a server form with a layout defined. I should also note that we do not want anything but the Base page creating a BaseServerForm, so we hide the constructor from the outside world by declaring it internal. This is because the Base page is the only object that should ever need to crate a BaseServerForm. However, we do want developers to be able to reference the form in case they decide to change something programmatically before the request is handled. I had to resort to using reflection to rip apart the old HtmlForm�s private values and copy them to our BaseServerForm. We could have used a �has-a� relationship with the HtmlForm but that seemed a bit on the clunky side, therefore I made it an "is-a" relationship to make its relationship with our pages seamless. Also note that it is critical that we move the control tree and attributes of the old HtmlForm to our new BaseServerForm before we use reflection to get any internal values. We can get to the control tree just fine, we don�t need to use reflection to get to it. I normally do not like using reflection unless absolutely required. I like to think of reflection like I think of Duct Tape, it�s a tool that has a noble purpose� But when used �creatively� you can end up really shooting yourself in the foot (if you will forgive the old C clich�).

Now that we have our BaseServerForm class defined, we need to define the super base page from which we will derive all our sites' base pages. Here is the code�

And this is the derived base template implementation that gets loaded during the virtual LoadBaseUITemplate call:

You can see that I am using a combination of overriding the AddParsedSubObject() and the AddChildControls() virtual methods. This is because we only need to use the AddParsedSubObject() method to do one thing. Intercept our HTML header and HTML form before it gets added to our page. I got this idea from Micheal Earls (a fellow Magenicon from Atlanta). Check out his blog here. I have seen this method overridden in server controls for child control tags but not in a page class like this. I thought it was a very clever use of the method and it solves the problem of having to remove the outer HTML from around our content area. Now that we have the outer HTML intact it also gives us the opportunity to override the Base page configuration at the page level thus imitating the web.config settings/page directive pattern that currently exists in ASP.NET.

For those of you unfamiliar with this method, it gets fired whenever a handler encounters a child element. In the case of the System.Web.Page class, it gets fired a total of three times.

As you may have already guessed, we only really care about the first two, when it is fired for the HTML tag, that is when we get our custom configuration settings and place them into the header. This part of the handler needs to really scream so I struggled for awhile on what would be the best way. I have used HtmlWriters in the past but I thought for this it was too much overhead since we are already using one in the render call, plus I am forced to parse all the HTML in order to make that approach effective (so clearly, it is not an option here).

After some experimentation I decided to go with StringBuilders since they are faster than vanilla string concatenation (in fact the performance of the StringBuilder is comparable to using the old memcpy() call in C). To truly take advantage of the StringBuilder�s performance you need to estimate how much space you will need ahead of time. If you don�t the StringBuilder will be moving a lot of character memory around when it has to resize itself internally to make more room. I use a combination of the default HTML content along with what is in the web.config to calculate a good initial size for my StringBuilder�s buffer. The reason this is so important is because when the StringBuilder reaches its limit during an append(), it creates a new buffer twice the size of the old one and copies all the character data over to the new buffer (then destroys the old buffer). All this movement of character data negates the performance gains of using a StringBuilder (although it is still probably faster than plain old string concatenation operators). Regardless, it�s better to be safe than sorry IMHO.

We are doing some initialization in the CreateChildControls override as well. We do this to ensure that these methods are only called once when the request gets handled. This is done by calling EnsureChildControls() from our init() call. This call �ensures� that our child controls get created (in this case we are initializing the SmartQueryString and SmartSessionState). Since they are not critical to using the Base page and since I am trying to keep this short, I will go into more detail on these two classes in the final part.

The virtual methods in the SuperBasePage are to be overridden in our derived SuperBasePage class. Using these virtual methods allows us to define how and what our Base page loads when it is requested.

These are just examples. I plan to release a full project with examples on how to do everything, at a future date.

These last two involve the SmartQueryString and SmartSession interfaces. The smart handler interfaces give us the ability to strongly type our QueryString, Session and Application objects. I will go into more detail on the next post on what these methods are used for�

Other methods in the Base page base�

Well, that was a lot to say (and for you to read). I tried to keep it short since this is just a blog post. So if you have any questions just ask and I will be happy to answer. In the last part of this article, I will talk about the Smart Handler objects (SmartSession, SmartQueryString, SmartApplication) and how you can create your own base handlers to persist values differently. To explain what they are for, they allow us to manage our querystring, etc� from a within our Base page (like the response and request objects already do � these are strongly typed and easy to use). They have made my life infinitely easier.

Part IV - Implementing the Smart Session Objects

In this final part (for now anyway, until someone gives me some better ideas or I wake up in the middle of the night with one of my own), I am going to describe how to implement the Smart State Objects that we can get data from via the master page. One of the things I really don�t like to do is having to hardcode strings to find stuff in a generic collection object and then rely on that object being of a specific type before I can actually use it. When I am working on the project independently it is not as much of a problem, but when it grows to more than a couple of developers, it gets tough to keep track of the keys (unless of course you step through the entire application with trace turned on so you can monitor additions and removals from our state objects).

This gets even worse when dealing with querystring data. You can add and remove things from the query string anywhere and it does not have to be consistent, so when you redirect to another page on the web app, you are assuming that the next page is always going to have access to the query string elements you are going to need and worse, that the values that they represent are not going to change in context. My solution to this is to wrap these objects in my own smart session classes. We had a monster problem synching up the query string that we were using at an E-commerce project once, and the minute the scope shifted and the client stated that they wanted another feature (and another querystring because this site had to do all its state maintenance through the query string), we had to go through every page in our purchasing and payment process, etc� to make sure this element was added when it was needed (and worse � they were using string concatenation operators to do it on every single redirect in the site). Yuck!!!

So I took a little time and wisely spent some time coming up with a better way to handle this problem, the solution is the ISmartQueryString, ISmartSession and ISmartApplication interfaces. Here is an example of the interfaces followed by what they allow us to do�

ISmartQueryStirng: Allows us to encapsulate the query string in one spot in our code � we are always going to be assured of an element's existence (with default values set) so we do not need to write the code to check this in every single page. We will implement this interface in our SmartQueryStringBase class (more on that in a bit).

Now a framework wouldn�t be complete without an out of the box implementation of this interface so I am providing one. In this interface I am using reflection to get the values out of my SmartQueryString object (I am going to call it AcmeSmartQueryString() for lack of a better name). You can see in the following code how reflection takes the property values of our smart querystring and moves the value to our querystring. I am also putting a prefix on this: �sqs� for �Smart Query String�. This tells our smart query string class that there is a query string present and it can begin parsing it out back into our AcmeSmartQueryString() object when the MasterPage is initialized during a request. Here is the code�

Finally, if you look, you can see what the SmartRedirect does. It�s nice because you only need supply the smart redirect with the URL where you are going and the smart query string does the rest of the work for you! Not too shabby!

Now if you are looking closely you will also see that I am using an attribute to generate the key name for our query string. This is the SmartQueryStringKeyAttribute(). We will apply this attribute to our AcmeSmartQueryString object�s properties so we can keep the key values short and sweet in our query string's output.

Finally � here is the AcmeSmartQueryString class (our derived smart query string object that holds our smart query string's values for the app):

You can see that this class does not interact with its base members, this is the beauty of using the interface. You do not need to worry about what is happening to translate the query string to and from this object because it all happens behind the scenes. You are now free to interact with this object as you need just like it�s another instance in your code. I left out one of the attributes so you can see what happens on the receiving end when the next page request is filled. You will see the whole name for the property. It just has state and that�s it! That�s the beauty of it, our developers using this framework do not need to know what is happening under the hood, they just have to interact with this instance and they are good to go� Keep in mind that the smart query string although maps properties to our smart query string, you can only use strings with it (hence the name). I am looking into ways to allow you to add other types to the query string (enumerations, other value types etc�). I will leave that matter as the subject of a future post.

Here is our Acme Master Page that not only initializes the other Master Page components but also loads our AcmeSmartQueryString:

You can see in our event handler in the above page that we are using the SmartQueryString of the current instance (initialized in our base page when it gets requested) to do the redirection and keep our string elements intact. This not only makes it easier to manage the querystring, it also centralizes everything that happens in the querystring in one place making maintenance infinitely easier.

On a side note, so I know what some of you are saying� But I hate using reflection!! Why not use a formatter or typeconverter instead??!! To answer that question, you can write your own. I created interfaces for these objects so you can create your own SmartQueryStringBase class (along with the other smart state objects) � the master page base does not care � all it needs to keep a reference to are these interfaces, so write your own if you must.

Now for the other smart state objects, things are not as automatic because we do not have the �Smart Redirect� to pass the data along to our code so it can be persisted. Therefore we need to tell the other SmartState Objects to persist themselves whenever we change something in them. These interfaces are fairly straightforward minus the fact that we have to set the state somehow. That is where �SetApplicationState� and �SetSessionState� come in. Pass these calls the appropriate state object and away you go!

Here is the AcmeSmartSessionBase implementation (I included the Person object so you can see the class we are keeping in session state:

Using the application state is similar except that we lock the instance before we mess with it. Here is the code for our default SmartApplicationStateBase (not too much different from the SmartSessionBase aside from the thread sync stuff):

Finally here is an example of how to use these objects (remember our master page already set these up for us so they are all ready to go when we need them):

I am not going to post anything about how to use the Application State stuff since it works the exact same way as the SmartSession. That is the smart state objects in a nutshell � I am currently working on ways to make the persisting calls more efficient by adding an interface to check for a new / dirty / clean object. I will post the enhancements to this framework as they become available.

You must Sign In to use this message board.