Writing Helpers in ASP.NET Web Pages (Beta)

by

I’ve been seeing some people asking about how to write their own helpers in ASP.NET Web Pages.  If you’re not familiar with ASP.NET Web Pages or Razor be sure to check out Scott Guthrie’s post announcing them.  I’m the PM for them.  :)  You can use WebMatrix (or Notepad or any text editor of your choice) to build web apps using ASP.NET Web Pages.

First, let me overview how writing your own helper will be in the next version of ASP.NET Web Pages, then I’ll go over how you would go about writing them as of when this blog post went up.

Future @helper Usage (not in Beta)

In the next release of ASP.NET Web Pages you will be able to use our new @helper syntax to easily build new helpers.  The main scenario we’re trying to cover with this is simple.  Say you have a page with a little code/markup that you would like to reuse on other pages.

<!DOCTYPE html>
<html>
  <head>
       <title>Gravatar</title>
   </head>
   <body>
       <img src="@Gravatar.GetUrl("someone@somewhere.com")" alt="Gravatar" />
   </body>
</html>

In the next version you will be able to simply do the following:

  • Create a new file under App_Code in your app named Utilities.cshtml (this can be named anything)
  • Cut the code/markup you’d like to reuse and place it into a method in the new file and replace any hard-coded values with any incoming parameters you have in your method.
  • Call the new helper by the name of the file (Utilities in this example) and the name of the method

Here is what the Utilities.cshtml file would look like:

@helper GetGravatarImage(string email) {
   <img src="@Gravatar.GetUrl(email)" alt="Gravatar" />
}

And here is what the original page would now look like using the new helper:

<!DOCTYPE html>
<html>
  <head>
       <title>Gravatar</title>
   </head>
   <body>
       @Utilities.GetGravatarImage("someone@somewhere.com")
   </body>
</html>

Pretty straightforward and simple. Unfortunately, we’re still working on this feature.  It will be in the next release.

Writing a Helper Today in Beta

For the time being you can convert your code/markup into a static class, which is how we currently build helpers internally.  Here is an example:

using System.Web;
using Microsoft.WebPages.Helpers;

public static class Utilities {
    public static IHtmlString GetGravatarImage(string email) {
        return new HtmlString("<img src=\"" + @Gravatar.GetUrl(email) + "\" alt=\"Gravatar\" />");
    }
}

The most important thing to note here is that your method should return IHtmlString for things to get rendered properly.  How you build it internally doesn’t really matter.  In my simple example I just build a string and then wrap it up into a new instance of HtmlString (which is an implementation of HtmlString).  One other thing to note here is that I’m importing the Microsoft.WebPages.Helpers namespace because that’s where the Gravatar helper that I’m using exists.

One other important thing to note is that while I’m building a string here because it’s such a simple solution, the better/safer way to do this is to build it using the TagBuilder, which is in MVC (and available in the Beta).

The usage for this helper would be exactly the same as the new way stated above:

<!DOCTYPE html>
<html>
  <head>
       <title>Gravatar</title>
   </head>
   <body>
       @Utilities.GetGravatarImage("someone@somewhere.com")
   </body>
</html>

So it’s still pretty easy to build your own, but unfortunately today you have to start learning some OOP concepts, which goes against our goal of simplicity and staying relatively procedural.  Can you see why we’re working on a newer syntax to help simplify this?  🙂

Summary

Writing helpers isn’t too difficult but can be a lot of work if you’re trying to compartmentalize a lot of code/markup and requires you to understand more advanced concepts.  In the next release of ASP.NET Web Pages you will be able to simply cut and paste your code/markup that you want to reuse into a new file and use it.

Do you like the new syntax?  What sorts of helpers are you building?

Leave a comment