The Difference Between @Helpers and @Functions In WebMatrix

This is another post which was inspired by a recent question in the ASP.NET forums, when someone asked what the difference is between @functions and @helpers in ASP.NET Web Pages. Here, I look at both of these contructs and explain what they are, how they are different, and how each should be used appropriately.

Both @helpers and @functions do share one thing in common - they make code reuse a possibility within Web Pages. They also share another thing in common - they look the same at first glance, which is what might cause a bit of confusion about their roles. However, they are not the same. In essence, a helper is a reusable snippet of Razor sytnax exposed as a method, and is intended for rendering HTML to the browser, whereas a function is static utility method that can be called from anywhere within your Web Pages application. The return type for a helper is always HelperResult, whereas the return type for a function is whatever you want it to be.

A typical example of a helper is to display items in an ordered list. You create a folder called App_Code in the root of your site, if you don't have one already, and add a .cshtml file to it. You can name this file anything you like - but Helpers seems to be appropriate. Within your Helpers.cshtml file, you would add the following code:

@helper OrderedList(IEnumerable<string> items){
    <ol>
        @foreach(var item in items){
            <li>@item</li>
        }
    </ol>
}

As you can see, this code includes HTML tags and Razor code, just like it would if you were rendering an ordered list within a Web Page. When the code is compiled, OrderedList becomes a static method of non-static class called Helpers - the name of the class is taken from the file name. A sample method call could look like this:

@Helpers.OrderedList(new[] { "Blue", "Red", "Green" })

When this is executed, unencoded HTML is output to the browser. You could implement the same functionality using @functions, and here is an example which does just that. Again, you need to add a .cshtml file to App_Code, and give it a name. In this case. Functions.cshtml is as good as any:

@using System.Web.Mvc;
@using System.Text;
@functions {
    
    public static HtmlString OrderedList(IEnumerable<string> items)
    {
        var sb = new StringBuilder();
        var orderedList = new TagBuilder("ol");
        foreach(var item in items){
            var listItem = new TagBuilder("li");
            listItem.SetInnerText(item);
            sb.AppendLine(listItem.ToString(TagRenderMode.Normal));
        }
        orderedList.InnerHtml = sb.ToString();
        return new HtmlString(orderedList.ToString(TagRenderMode.Normal));
    }
}

Again, OrderedList becomes a method of a non-static class named after the file (Functions), and calling it in the page is straightforward:

@Functions.OrderedList(new[] { "Blue", "Red", "Green" })

But Oh Lordy! You've had to reference System.Text to create a StringBuilder object and System.Web.Mvc to use the TagBuilder (although you could have rendered the HTML tags as strings yourself), and make sure you returned an object of type HtmlString to ensure that the whole lot doesn't get HTML encoded when it is rendered to the ouput. Functions cannot contain intermixed HTML. Now you can see the attraction of @helpers.

The appropriate use for @functions is when you want to perform an operation on a variable, rather than output some HTML. For example, you might want to validate an incoming DateTime to ensure that it is some time in the past. You wouldn't accept a form submission where someone's date of birth is some time in the future, after all? This is where @functions can be used:

@functions {    
    public static bool IsBeforeToday(string value){
      DateTime result;
      if (DateTime.TryParse(value.ToString(), out result))
      {
        if (result < DateTime.Now)
        {
          return true;
        }
      }
      return false;
    }
}

This function takes a string as an input, and tests to see if it can be converted to a DateTime successfully. If so, it tests to see if it is before the current date and time. If it passes those tests, it returns true:

@Functions.IsBeforeToday("2010/3/22") @*returns True*@
@Functions.IsBeforeToday("2012/5/6") @*returns False at the time of writing*@

Notice that the return type for both @functions examples have differed - the first is an HtmlString, whereas the second is a bool. The return type for a method compiled from @helpers will always be HelperResult.

One other thing to note - I've emphasised that the class that is compiled as a result of the @functions syntax is non-static. This means that you cannot create extensions methods using @functions.

 

Date Posted:
Last Updated:
Posted by:
Total Views to date: 68567

9 Comments

- Jesse

Thanks for the further clarification. Great post

- Q

It's clear that Helpers always return some HTML. Do Functions always have to return a vale however?

Was trying to find this out, as all examples I have seen so far (including here) it does. I wanted a reusable bit of code that logs certain events to a text file. I thought that a Function was the logical choice for that and it also includes a try catch in there. When trying to run it however I got the error "not all code paths return a value". I thus tried adding a line in both the try and the catch to return something and then it worked.

Obviously since I'm not using those values I'm returning it seems like I'm not doing something right here.
Am I incorrectly using the Function or should I be using something other than a Function?

Thanks

- Mike

@Q,

Your function definition is just a wrapper around a C# method. You can declare it with a return type of void if you don't want to return anything:

@functions{
public static void LogThis(Exception ex){
// method body
}
}

- Andrew

The Total Views to date: ... is based on each postback. Not accurate at all!

- Mike

@Andrew,

As you have established, it's 100% accurate. Every time the page is requested, I register 1 view.

Thanks for dropping by and testing that for me.

- Bret Dev

Excellent post! One concern - where can you place global @Functions code within an MVC project to get visibility across pages? Is this unsupported?

- Mike

You can put them in an App_Code folder just like Web Pages. You may need to compile first before they are available to your views.

However, the recommended option in MVC is to create normal extension methods and put them into a class file or reusable project. The MVC version of @Helper is an extension method on the HtmlHelper type.

- Bayu Angkasa

Four years after you wrote it, I still find out how lucky I am to read your posts ... Thank you Mike !!!

- Ryan Williams

You're like the ONLY authority on WebPages. I swear we are screwed if you retire!

Recent Comments

Gayan 7/3/2015 6:20 AM
In response to 7 C# 6.0 Features That Every ASP.NET Developer Should Know About
Great Article thanks...

Semil 7/1/2015 7:03 AM
In response to iTextSharp - Drawing shapes and Graphics
I have created a rectangle using above methode. Now I want to add a text in the center of this How I...

Satyabrata Mohapatra 6/30/2015 6:12 PM
In response to Reading Excel Files Without Saving To Disk In ASP.NET
Ahh.....this is awesome. Happy to see after a long time you wrote a article on web form :D...

Marty 6/30/2015 7:16 AM
In response to Posting Data With jQuery AJAX In ASP.NET Razor Web Pages
Mike, you're the Man! Another great article. So incredibly helpful. I'm definitely going to buy your...

Rohan 6/30/2015 5:32 AM
In response to ASP.NET MVC 5 with EF 6 - Working With Files
Very good and helpful tutorial. Thanks. Just wanted to know what would be the max file size limit we...

Fernando 6/30/2015 1:59 AM
In response to Programmatically accessing data from DataSource controls
What if I want to pass parameters natively using the DataSourceSelectArguments object, instead of be...

pankaj 6/29/2015 3:13 PM
In response to How to retain carriage returns or line breaks in an ASP.NET web page
very nice i'm use this in my code thank you.... ...

Mike 6/29/2015 2:22 AM
In response to MVC 5 with EF 6 in Visual Basic - Sorting, Filtering and Paging
This is the first example that I have found that works....

Marty 6/28/2015 4:57 AM
In response to Posting Data With jQuery AJAX In ASP.NET Razor Web Pages
Mike, what if I don't want to render back the text to the browser, but I want to send it some other...

Mike 6/27/2015 4:00 PM
In response to Migrating Classic ASP To ASP.NET Razor Web Pages Part One- Razor Syntax And Visual Basic
have you used any of the code converters to convert classic asp to c#? If so, which one do you have...