Character encoding with ASP.NET MVC helpers

, ,

In ASP.NET MVC, one of the ways to reuse parts of a web application template is to use helpers. There are two kind of helpers that can be used with Razor templates: helpers created directly from Razor templates using the @helper directive and helpers created from a C# class. To declare a helper with the @helper directive in a Razor view or in a .cshtml file in the App_code folder, you have to use the following syntax :

@helper PageHeader(string pageTitle)
   {
   <h1>@pageTitle</h1>
   }

Helpers created with the @helper directive always return a System.Web.WebPages.HelperResult that implements the System.Web.IHtmlString interface. This interface tells the Razor engine that the string returned is HTML-encoded and does not need to be encoded again to be safe. By default, all strings are encoded by the Razor engine, which means that characters not allowed in URLs or inside HTML tags are encoded into their character-entity equivalents : for example < and > becomes %3c and %3e.

But if you want to create your own helpers in a C# class, the return type to use is not that clear. The HelperResult class should not be used since it belongs the System.Web.WebPages namespace specific to the Razor syntax functionalities and not to the System.Web.Mvc namespace containing the ASP.NET MVC framework functionalities. The documentation of the HelperResult class also clearly indicates that it is not intended to be used directly from your own code. That leaves us with two options :

  • System.Web.HtmlString:  this class implements the IHtmlString interface and returns an HTML-encoded string that should not be encoded again. The only public method is the ToHtmlString method from the IHtmlString interface. The class is in the general System.Web namespace containing classes for the HTTP context.
  • System.Web.Mvc.Html.MvcHtmlString: this class extends the HtmlString class, so it also returns an HTML-encoded string that should not be encoded again. In addition to the ToHtmlString method, it aslo includes the factory method Create to create an MvcHtmlString from a text string and a IsNullOrEmpty method to check if the string is String.Empty, “” or null. The class is in the System.Web.Mvc.Html namespace containing classes that helps to render controls in an MVC application.

Since the MvcHtmlString class is specific to the MVC framework, I choose to use it for the helpers in my ASP.NET MVC projects. If new features are added for ASP.NET MVC, they will be available from that class and not from the less specific HtmlString class. Also, this is the class used by Microsoft for their own helpers, for example those the System.Web.Mvc.Html.InputExtensions class. I prefer to follow Microsoft’s conventions, which makes using their helpers into my own helpers easier. So, a good syntax for a helper built from C# code is :

public static class PageHelperExtensions
   {
   public static MvcHtmlString PageHeader(this HtmlHelper htmlHelper, string pageTitle)
      {
      // Create the HTML markup with TagBuilder or HtmlTextWriter
      return (MVCHtmlString.Create(tagBuilder.ToString()));
      }
   }

In conclusions, there are two other useful helpers to know about that deal with encoding :

  • @Html.Raw: Indicates to the Razor engine that a string is encoded and should not be encoded again. This can be used if you receive HTML markup from your model and want to make sure it is not encoded again.
  • @Html.Encode: Indicates to the Razor engine that a string should be encoded. This should not be used except in a few rare cases: since all strings are already encoded in Razor templates, this will double-encode the string.

Additional resources