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 string
s 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 also 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 help 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 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)
{
return (MVCHtmlString.Create(tagBuilder.ToString()));
}
}
In conclusion, 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 string
s are already encoded in Razor templates, this will double-encode the string
.
Additional Resources