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 :<\/p>\n\n\n
\n@helper PageHeader(string pageTitle)\n {\n <h1>@pageTitle<\/h1>\n }\n<\/pre>\n\n\n\nHelpers created with the @helper directive always return a System.Web.WebPages.HelperResult<\/em> that implements the System.Web.IHtmlString<\/em> 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.<\/p>\n\n\n\nBut if you want to create your own helpers in a C# class, the return type to use is not that clear. The HelperResult<\/em> class should not be used since it belongs the System.Web.WebPages<\/em> namespace specific to the Razor syntax functionalities and not to the System.Web.Mvc<\/em> namespace containing the ASP.NET MVC framework functionalities. The documentation of the HelperResult<\/em> class also clearly indicates that it is not intended to be used directly from your own code. That leaves us with two options :<\/p>\n\n\n\n- System.Web.HtmlString:<\/strong>\u00a0 this class implements the IHtmlString<\/em> interface and returns an HTML-encoded string that should not be encoded again. The only public method is the ToHtmlString<\/em> method from the IHtmlString<\/em> interface. The class is in the general System.Web<\/em> namespace containing classes for the HTTP context.<\/li>
- System.Web.Mvc.Html.MvcHtmlString:<\/strong> this class extends the HtmlString<\/em> class, so it also returns an HTML-encoded string that should not be encoded again. In addition to the ToHtmlString<\/em> method, it aslo includes the factory method Create<\/em> to create an MvcHtmlString<\/em> from a text string and a IsNullOrEmpty<\/em> method to check if the string is String.Empty, “” or null. The class is in the System.Web.Mvc.Html<\/em> namespace containing classes that helps to render controls in an MVC application.<\/li><\/ul>\n\n\n\n
Since the MvcHtmlString<\/em> 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<\/em> class. Also, this is the class used by Microsoft for their own helpers, for example those the System.Web.Mvc.Html.InputExtensions<\/em> 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 :<\/p>\n\n\n\npublic static class PageHelperExtensions\n {\n public static MvcHtmlString PageHeader(this HtmlHelper htmlHelper, string pageTitle)\n {\n \/\/ Create the HTML markup with TagBuilder or HtmlTextWriter\n return (MVCHtmlString.Create(tagBuilder.ToString()));\n }\n }<\/pre>\n\n\n\nIn conclusions, there are two other useful helpers to know about that deal with encoding :<\/p>\n\n\n\n
- @Html.Raw:<\/strong> 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.<\/li>
- @Html.Encode:<\/strong> 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.<\/li><\/ul>\n\n\n\n
Additional resources<\/h3>\n\n\n\n