skmExpressionBuilders - A Suite of Custom Expression Builder Classes

By Scott Mitchell

Introduction

An ASP.NET Web control's properties can be set in one of two ways: declaratively and programmatically. Declaratively setting a Web control's properties entails specifying the property in the control's declarative syntax. For example, Web controls have their ID property set declaratively, like so: <asp:WebControl runat="server" ID="ID" ... />. Properties can also be set programmatically in the ASP.NET page's code-behind class. If you need to set a Web control's property to some dynamic value you may think you need to set it programmatically. However, this is not the case. Expression builders make it possible to assign a dynamic value to a Web control property through the declarative syntax.

Last week's article, Using Expression Builders in ASP.NET, examined the ins and outs of expression builders, their syntax, and how to use them in an ASP.NET page. ASP.NET ships with three built-in expression builder classes: AppSettingsExpressionBuilder, which retrieves a value from the <appSettings> section defined in Web.config; ConnectionStringsExpressionBuilder, which retrieves a value from the <connectionStrings> section; and ResourceExpressionBuilder, which retrieves a resource value. These expression builders can be used in the declarative markup using syntax similar to the following: <asp:Label runat="server" id="Copyright" Text="<%$ AppSettings:CopyrightNotice %>" />.

With a little bit of elbow grease you can create your own custom expression builder classes. I've spent some time creating a handful of custom expression builder classes, which I've packaged into a class library named skmExpressionBuilders. This article walks through the custom expression builders in this library and shows how to use them in your ASP.NET application. Read on to learn more!

- continued -

An Overview of the skmExpressionBuilders Library

The download available at the end of this article includes a Visual Studio Solution with two projects: a website application for testing the custom expression builders (TestWebsite), and a Class Library project named skmExpressionBuilders. skmExpressionBuilders includes four custom expression builder classes:

SessionExpressionBuilder - retrieves a specified Session variable value using the syntax <%$ Session:VariableName %>.
QueryStringExpressionBuilder - retrieves a specified querystring value using the syntax <%$ QueryString:Name %>.
ServerVariableExpressionBuilder - retrieves a specified value from the ServerVariables collection. This collection contains information about the current request, such as the requested URL, whether the request is over HTTPS, the currently logged on user's name, the IP address of the requestor, and HTTP headers, among other information. This custom expression builder uses the syntax <%$ ServerVariable:VariableName %>.
CodeExpressionBuilder - returns the value of a specified expression using the syntax <%$ Code:CodeExpression %>.

We'll dissect these expression builders in a moment, but before we do let's first talk about the steps you'll need to take to use the skmExpressionBuilders library in your web application. skmExpressionBuilders will work with ASP.NET 2.0 and beyond, and while the skmExpressionBuilders is written in C#, it can be used in any ASP.NET web application regardless of the language used.

To use skmExpressionBuilders in your website follow these two simple steps:

Copy the skmExpressionBuilders.dll assembly from the download available at the end of this article into the /Bin folder of your ASP.NET application.

Open your website's Web.config file and add the following markup within the <compilation> section in <system.web>:

That's all there is to it! You can now add these handy expression builders in your declarative syntax.

The `SessionExpressionBuilder`, `QueryStringExpressionBuilder`, and `ServerVariableExpressionBuilder` Custom Expression Builders

The first three custom expression builders in the skmExpressionBuilders library - SessionExpressionBuilder, QueryStringExpressionBuilder, and ServerVariableExpressionBuilder - are all very similar. Each of these custom expression builders pulls a value from a collection in a server-side object. SessionExpressionBuilder retrieves a Session variable, whereas QueryStringExpressionBuilder pulls a value from the querystring. Because these three classes are so similar I created a base class, BaseServerObjectExpressionBuilder, which extends the ExpressionBuilder class and implements the common functionality. The classes that derive from BaseServerObjectExpressionBuilder only need to do three things:

Provide a static method named Instance that returns a new instance of the class.
Override the GetValue method defined in the BaseServerObjectExpressionBuilder class. The GetValue method accepts a string input and returns an object. Specifically, GetValue should return the value in the server-side collection of interest.
Override the SourceObjectName property, which supplies the name of the collection being worked with; it is used in any error message strings.

Take the QueryStringExpressionBuilder class as an example. As you can see, this class is quite simple as it only needs to do the three things noted above. The code that generates the code expression based on the user's input and casts it to the appropriate type (if needed) is handled in the BaseServerObjectExpressionBuilder base class.

public class QueryStringExpressionBuilder : BaseServerObjectExpressionBuilder { public static QueryStringExpressionBuilder Instance() { return new QueryStringExpressionBuilder(); } protected override object GetValue(string key) { return HttpContext.Current.Request.QueryString[key]; } public override string SourceObjectName { get { return "QueryString"; } } }

If you'd like to create any additional custom expression builders that perform a similar function to these three - namely, a custom expression builder that grabs some value from a server-side object like Session or Request.QueryString - have your class extend BaseServerObjectExpressionBuilder and implement the aforementioned requisites.

Let's look at using these three expression builders. Imagine you had a search page that was passed the search criteria through the a querystring field named query, as in: /SearchResults.aspx?query=user's search query. Furthermore, assume that the search results had a TextBox at the top from which the user could start a new search. You could populate this TextBox with the user's current search query by assigning the TextBox's Text property declaratively with the following expression builder syntax:

<asp:TextBox runat="server" id="SearchQuery" Text="<%$ QueryString:query %>" />

Likewise, you could display the current visitor's IP address in a Label using the SessionVariable REMOTE_ADDR:

<asp:Label runat="server" id="UsersIP" Text="<%$ SessionVariable:REMOTE_ADDR %>" />

The download includes a test website with additional demos.

`CodeExpressionBuilder`, A Generic Code Expression Builder

In his blog entry The CodeExpressionBuilder, Microsoft ASP.NET team member Dave Reed showcased a very generic and powerful custom expression builder that can evaluate any ad-hoc code expression, assigning the result to a Web control property. I added this control into skmExpressionBuilders (with permission).

With the CodeExpressionBuilder you can assign any generic code expression statement to a property value. You could, for instance, display the current date and time in a Label using the following syntax:

<asp:Label runat="server" id="CurrentTime" Text="<%$ Code:DateTime.Now.ToString() %>" />

A code expression is some statement that evaluates to a value, like:

DateTime.Now.ToString()
4 + 17
"Your IP address is: " + Request.ServerVariables["REMOTE_ADDR"]

The code expression you specify for the CodeExpressionBuilder must be in the same language as specified in the Language attribute of the ASP.NET page's @Page directive. Also, if your code snippet includes quotation marks you'll need to make sure you surround the property value in the declarative syntax with apostrophes so that there's no ambiguity where the strings start and end. For example, when assigning the Text property of a Label to the code expression

"Your IP address is: " + 
Request.ServerVariables["REMOTE_ADDR"]

you should surround the value of the Text property with apostrophes, like so:

<asp:Label runat="server" id="UsersIP" Text='<%$ Code:"Your IP address is: " + Request.ServerVariables["REMOTE_ADDR"] %>' />

You can also perform simple if/then/else-type operations using the ternary operator. The C# ternary operator takes the form:

Boolean Expression ? Output If True : Output If False

So you could use this expression builder to assign a different value to a Label depending on whether the user was authenticated or not like so:

<asp:Label runat="server" id="WelcomeMessage" Text='<%$ Code:Request.IsAuthenticated ? "Welcome back, " + User.Identity.Name + "!" : "Please login." %>' />

Moreover, you can always call a method defined in your page's code behind class. We could replicate the above functionality by created a protected or public method in the code-behind class named GenerateWelcomeMessage. This method would need to return a value that will be assigned to the property in question; in this case, we'd want the GenerateWelcomeMessage method to return a string.

protected string GenerateWelcomeMessage() { if (Request.IsAuthenticated) return "Welcome back, " + User.Identity.Name + "!"; else return "Please login."; }

And the expression builder would be used like so:

<asp:Label runat="server" id="WelcomeMessage" Text='<%$ Code:GenerateWelcomeMessage() %>' />

Pretty neat, eh?

Design-Time Support

The expression builder syntax can be specified directly in the declarative syntax, as my examples in this article and last week's article have demonstrated, but you can also use a GUI for supplying these values. Go to the Designer in Visual Studio, click on a Web control, and go to the Properties window. At the top of the Properties window is the text (Expressions). Click the ellipses next to this option to display the Expressions dialog box. From this dialog box you can select a bindable property, choose the expression type from a drop-down list, and then enter the expression property. The following screen shot shows the Expressions dialog box for a TextBox whose Text property is assigned using the SessionExpressionBuilder custom expression builder, pulling in the value of the DefaultName Session variable.

The skmExpressionBuilders custom expression builders each include support in this dialog box. Moreover, the GUI for the ServerVariableExpressionBuilder is comprised of a drop-down list with the server variable options pre-loaded. (You can manually type in a value into the drop-down list, as well.)

Happy Programming!

By Scott Mitchell

Attachments:

Download skmExpressionBuilders (a suite of free custom expression builder classes)