Creating messages in your Web application should be quick, easy, and most importantly, consistent.

They should look like they belong with the rest of the application even if an error occurs. How often have you created a new page to display simple text or a notification message to your users? Wouldn’t it be better if you could reuse an existing template and simply pass in a few parameters to tell it to render an application-specific message? In this article I will show you how to create a reusable Message Display class that reduces displaying messages generically in your application to a single line of code.

ASP.NET reduces the need for generic message pages with its postback-based metaphor. Because most pages post back to themselves rather than going off to other pages, you can often re-display messages on the original page with a message or error header. Not only is this convenient to code with .NET by simply adding a label or even a custom error display control to show the message, but it’s also better for the user who sees the message in the context of the operation that produced the error or action that caused the message.

ASP.NET reduces the need for generic messages considerably, but there are still places where separate message pages are required.

However, there are still a number of occasions where the ASP.NET postback mechanism doesn’t lend itself well to message and error display. In these situations, a generic message display page comes in very handy. A generic message display is a simple, reusable page template that your application can call as a single method call by passing a couple of parameters. You can use it for these types of situations:

  • Global error messages. Errors captured in Global.asax’s Application_Error generally end up displaying a generic error page. Rather than redirecting to a completely static page, you can provide customized info via a generic display page that may contain a semi-static message, or for administrators, detailed error information.
  • Simple confirmation pages. There are still a number of forms that do well with simply having a confirmation page that says, “Thank you for your submission.” ASP.NET will always post back to the same page, but in many instances there’s nothing to display when you go back. For example, when you delete a record or you need to display a simple, but lengthy generated result. Although you can do this with a Redirect() you really don’t want to create a new form for each message, nor do you always want to go somewhere else without giving the user some feedback first.
  • Redirection situations where you need cookies. In many applications there are login scenarios where users are either automatically logged in or logged in through a login form. Although Forms Authentication can handle some of these scenarios, it’s often not granular enough to provide the functionality needed. In some login situations you need to forward to a new page, but at the same time you also need to store a Cookie (for permanent record), so you can’t use a Response.Redirect(). Instead, use an intermediate Display page that includes a META refresh tag to handle the forwarding either automatically or with an optional link. This approach makes it possible to pass Cookies forward to the next page.
  • Quick dynamic display of HTML data. Because this class uses predefined controls, it’s easy to pass in a header and a message-optionally in HTML format to easily create an HTML display. You can use this for debugging scenarios or while testing code.

Using the Class

The primary purpose of this class and template is to display stand alone messages easily and consistently from within your application. To implement this functionality I created a generic reusable class that you must subclass for each application you build. The base class consists of a non-visual Web Form class and it relies on the concrete implementation and the ASPX template of the subclassed Web Form to provide its visual interface.

The concept is simple: You add a new Web Form to your application and subclass it from the wwMessageDisplay base class. The HTML layout/design for your message page is customized to your application and reflects your own theme and layout. You must also add a few required labels that get dynamically filled in with the data you want to display. This includes the header and body as well as the title and optional redirection directives. Beyond that, the form can be of your own design to match your Web application’s look and feel. Figure 1 shows an example of an application-specific error message displayed in my Web Store application for the West Wind site that uses the custom MessageDisplay form created for the application.

Figure 1: Showing a generic message page. A single method call to the DisplayMessage() method with a Header and Message body is all it takes to generate a parameterized, generic message page from anywhere in the Web application.

Once you’ve designed your HTML form and subclassed it from wwMessageDisplay, calling this custom message page is as simple as making a static method call with at least two parameters to specify the header and message. Assuming the custom class and ASPX page is called the default MessageDisplay (MessageDisplay.aspx) you can call this from anywhere in your application.

MessageDisplay.DisplayMessage(
"We're sorry, an error occurred",
An <b>error</b> occurred in the application…");

Places you can call this from include: an ASPX page event, within an ASPX page expression (<%= %>), and even from an HTTP handler or module. The call will take care of the current request, displaying the message page, and then exit. You don’t need to issue Response.End() to finish. It is implicit in the DisplayMessage() code.

You pass in a header message and the body text for the page. Both can contain HTML markup to allow you to embed links or formatting if necessary as Figure 1 does with the link back to the Web Store Home Page. Additional overloads of the DisplayMessage() method allow you to specify an explicit ASPX page (in case you have more than one “message template page” in your application) and you can pass in a URL to automatically redirect to after a specified interval. The redirection is performed with a META Refresh tag in the generated HTML output.

The concept is simple: Create an HTML Template with a couple of specific controls, subclass the form from wwMessageDisplay and you’re ready to go.

As you can see in Figure 1, the page is customized with the look and feel of the main application. It has the toolbar, links, and page footer of the original application. The layout is provided by the custom Web form the developer creates. This form is required to contain at least a Header and a Message label control in order to work. The template HTML in this example includes several optional user controls (the toolbar, footer and links boxes), but the layout is completely up to you and your application’s look and feel.

In order for the information to display the HTML Template, your .ASPX page requires that a couple of expressions and label controls exist in the page. Listing 1 shows the ASPX HTML source for the page above. The required portions are marked in bold. Only a few things are specific to the MessageDisplay routine.

lblHeader label. This is where the header text is displayed. In Figure 1, this is the Application Error message in the blue bar.

lblMessage label. This is the label that receives the main message text. This text should be in HTML format or plain text (in which case it just flows as a single paragraph).

lblRedirectHyperLink label. If you’re using a Redirect link, this label indicates the page you are redirecting to. The page should automatically redirect to this link when the timeout is hit, but if it doesn’t (if the browser doesn’t support it or has it disabled) it’s there to click on.

<title> tag. You’ll usually want to set the Title of the page to display your main message. To do so, use the this.Header member and embed it into the <title> tag. Note that each of the passed in parameters are available as properties: Header, Message, RedirectUrl, and RedirectMetaTag. You can use these anywhere you need.

this.BasePath. This property contains the base path of the Web application as a fully qualified URL like http://www.west-wind.com/WebStore/. A base URL is quite important if you need to display messages out of multiple directories. Without a <base> tag in the HTML, header images might not be found since relative paths can easily break. The <base> above points back to the application root from which it can find any relative links. Here this.BasePath is used to reference the style sheet and set the <base> tag.

The above describes the contents of the .ASPX page (MessageDisplay.aspx) HTML template. You also need a little bit of code to hook up the page logic. This basically consists of forwarding the standard page processing to a helper method that parses out the values passed in and then assigning them to the appropriate controls. Listing 2 shows a full code behind implementation of the class.

Server.Transfer() is used to transfer your static method call to the HTML template page that renders the message.

The key here is the DisplayPage() method, which is inherited from the base class and is responsible for picking up the values passed into the static DisplayMessage() method. It looks for the controls mentioned above and populates them with the values retrieved from its internal state before the page is displayed.

How it Works

Prior to ASP.NET I always had a function like this in my toolbox because in so many places I needed a consistent way to dump a quick message to the user. In those days I generated some code on the fly from within the source code and eventually called Response.Write() or its equivalent to dump the hand-generated HTML to the HTTP output stream. ASP.NET makes this process much cleaner by providing a clear Page processing model, the ability to transfer control to another page, and pass context information to this page. Because of this, it’s now much easier to create a new subclass that includes a template describing the display formatting (the .ASPX template).

I’ve based the implementation on a base class that provides all the processing functionality and a subclass you implement to provide the display template plus any additional logic you might need to fire when the page runs.

Figure 2 shows the flow of this process. You simply call the static DisplayMessage() method on your subclass from anywhere in your application with at least two parameters of Header and Body. This method then handles calling your ASPX page by using the Server.Transfer() mechanism and the Context object’s state mechanism to pass it the input parameters.

Figure 2: The static DisplayMessage method accepts simple parameters and uses the HttpContext object to pass the values to the ASP.NET page handler for processing via the Server.Execute() method. This process allows a single method call to cause an ASP.NET page to be generated from anywhere in the application.

The .ASPX page is then run as a live instance of your subclass. Your only task is to call this.DisplayPage() which it inherits from the base class. This method contains the logic to retrieve the data stored in the Context object, populate properties on the form, and then render the ASPX page.

The key concept is ASP.NET’s ability to transfer control from one request to another using the Server.Transfer()mechanism. If you’re not familiar with Server.Transfer() it provides the ability to stop execution of the current request and jump over to another page in the same application and process it. All Request information (except the URL which is adjusted for the Transfer’s new URL) are kept intact so when you jump over to the new page, your Request.Form and Request.ServerVariables still contain the same content as they had on the original page.

Keeping Context

What ties the original page or request and the transferred page together is the Context object. The Context object-as the name implies-has the lifetime of the current request. All of ASP.NET’s intrinsic objects like Request, Response, Session, and others are actually members of the Context object. Think of the Context object as the main object that passes through the current request from beginning to end. The Context object also includes an Items state bag that can be used to store values into so they can be picked up at a later point in processing, which is exactly what you need to pass information over a Server.Transfer() call. Using Context.Items["key"] values essentially serves as the parameter interface for Server.Transfer().

Implementation

To provide this functionality I used a subclass of the Page class that implements both a static and public interface to handle the generic tasks of message creation. The static methods are called from your application and are static so you can easily call the methods without any setup. The instance properties and methods are called only from within a running Web form. This way the two interfaces have clear separation as external for the static and internal for the instance.

The HttpContext object makes it possible to pass the parameters from the static method to the Page instance.

Message display is a two-step process: Initiate the request with a simple static method call, then transfer control to your custom class and let ASP.NET render the template.

Let’s start with the static call interface. Listing 3 shows the full parameter list DisplayMessage method implementation and its overloads which you can call from anywhere in your ASP.NET application.

The DisplayMessage() method simply accepts a set of parameters and stuffs all of them except the TemplatePageName into the Context object. The full function version includes a first parameter of the TemplatePageName in case you don’t want to use the default name specified in the Pagename static property. This means if you implement your page as MessageDisplay.aspx you can use one of the other overloads that omits the page name. Why pass the page name? A static method has no way to determine the name of the currently accessed class and so the name of the page/class needs to be stored somewhere (Pagename) or be passed in as a parameter so that we can transfer to the correct page. If you have more than one message template page in your application you can use the TemplatePageName to specify it explicitly.

Note the use of the HttpContext.Current reference to get a reference to the ASP.NET intrinsic objects including Context and Request. HttpContext.Current is always available to an ASP.NET request (except in design mode) and provides a great way to access all ASP.NET objects in generic methods like this one without having to explicitly pass in either Request, Response, or the Context object.

The wwDisplayMessage class contains additional non-static methods and properties that provide the page execution behavior. The non-static interface shown in Listing 4 shows the internal interface used to fill the controls of the Web form.

This part of the interface consists of a few properties that simply pull their values out of the Context object for easier access inside the ASPX page code, and the DisplayPage method which is responsible for parsing the context values into the appropriate placeholder Label controls of your page.

Notice that the DisplayPage() method has two overloads-one with no parameters and one with a set of control references for the controls that are to be updated on the page. The parameterless version uses Page.FindControl() to create references to the common names of the controls. Header.Text and Message.Text are simply assigned from the Header and Message properties which return the corresponding Context collection values.

Most of the DisplayPage code deals with fixing up URLs to display properly. Dealing with the URLs is a bit tricky, because this page can be loaded from different locations in your application, including from the root of the application or one of its subdirectories, which makes it difficult to determine relative paths of links, stylesheets, images, and more. For this reason, the HTML template includes a <BASE> tag in the page to force all related links relative to this base URL. Things are further complicated because some URLs are bound by this base tag and others are not. For example, redirect tag and style sheet references are in the header since <BASE> doesn’t apply to the header.

There are two paths: the path for the <base> tag which is a full URL including protocol and port, and the path that is used for the redirection link if provided which must be server relative. Creation of the base path involves taking the Request.ApplicationPath and prepending protocol, server, and port information. The redirection URL is more work because you have to deal with absolute URLs, relative links, or links that use ASP.NET’s ‘root’ convention (using the ‘~’ character to signify the application root). The Control.ResolveURL() method can easily take care of ‘~’ parsing and converting that into an application-relative URL. If the URL is absolute and includes protocol prefix and a port, you don’t need to do anything else and just use it as is. If the path is relative, you have to start with the page’s current path and then add the relative path to it. Unfortunately, ASP.NET has no mechanism to return you just the path of the current request so you have to parse it out of the full script path using the Request.FilePath property. All of this takes care of parsing the URL for redirection and the <base> tag.

Slight Difference for ASP.NET 2.0

I originally wrote this article for ASP.NET 1.x. The concept and implementation still works just fine with ASP.NET 2.0 with one change: You must store the CodeBehind page for your MessageDisplay.aspx page in the APP_CODE directory rather than in the same directory as your ASPX page so that the page class (MessageDisplay) is globally accessible to your application.

In ASP.NET 2.0, you can no longer globally access individual ASPX page classes by direct reference because they compile into dynamic assemblies at runtime. This mean you cannot access the static MessageDisplay.DisplayMessage() method from your application. However, any class stored in APP_CODE directory gets compiled into a separate assembly that is implicitly referenced by the ASP.NET application and is thus globally accessible.

The sample projects I’ve provided for download include both ASP.NET 1.x and 2.x versions.

You’ve Got Messages!

You now have a generic message display implementation that you can call from anywhere in your application with a single method call. You can even set up multiple message display pages by providing a specific page name to display. As long as the pages derive from wwMessageDisplay and they include the required controls to display the header and messages you’re ready to go.

The hardest part of the implementation is fixing up the HTTP paths to make sure all embedded links point at the right relative paths.

I use this class all over the place. All of my error handling goes through this class as well as many administrative forms that do not work well for the postback mechanism. For example, many of my applications include delete functionality where the main operations are handled through plain postback, but at the end of a delete operation I display a message of the final status that lets the user know the operation has completed.

MessageDisplay.DisplayMessage("Invoice Deleted",
   "Invoice Number: " + Invoice.InvNo +
   "<hr>has been deleted.",
   "InvoiceList.aspx",5);

This is much nicer than just redirecting-you’re giving some feedback first, then going to another location. Also in this case where a deletion occurs, it’s hard to post back to the current page. The invoice no longer exists, and you can’t display a message on that invoice page itself since there’s nothing left to show. Instead you have to go somewhere else and it’s nice to be notified first that the operation completed before moving on. Being able to do this with a couple of lines of code is very convenient.

I hope that this article has given you a few tips and insights in to how you can build front-end routines to ASP.NET pages. In essence, I’ve shown you a generic way to call an ASPX page through a simple method. If you look at this approach you might find a few other places where a single method interface provides efficient access to frequently used pages that require dynamic data to be passed in and displayed. The source code for this article is available from:

http://www.west-wind.com/presentations/

wwMessageDisplay/wwMessageDisplay.zip