I know that bit of code quite well and it seemed strange to me that such a performance difference would exist because view lookups are cached regardless of how you reference them. Specifically, once an application is warmed up both the Razor and WebForms view engines use the lookup parameters to retrieve the cached results. If anything the cache key produced from a view path is usually longer than the one produced from a view name but even that should not have a measurable impact.

While I cannot explain the differences that Sam is seeing (and since I know he is seeing them in production too I’m quite sure he has the application configured correctly for performance testing) I thought this would be a good opportunity to present the basics of MVC view lookup optimizations as well as a few additional techniques that people might not be familiar with.

Hopefully you won’t go replacing all of your view references with full paths. Using view names is still easier and more maintainable. And before you do any perf-related changes you should always measure your application. It might turn out that it is fast enough for your needs already.

Run in Release mode

You should always make sure that your application is compiled in Release mode and that your web.config file is configured with <compilation debug="false" />. That second part is super-important since MVC will not do any view lookup caching if you are running your application in debug mode. This helps when you are developing your application and frequently adding/deleting view files, but it will kill your performance in production.

This might seem like obvious advice, but I have seen even experienced devs get bitten by this.

Use only the View Engines that you need

I’ve mentioned this before but it’s worth repeating. The MVC framework supports having multiple view engines configured simultaneously in your application and will query each in turn when it is trying to find a view. The more you have the longer the lookups will take, especially if the view engine you are using is registered last. In MVC 3 we register two view engines by default (WebForms and Razor) and in all versions you might have installed 3rd party view engine such as Spark on nHaml. There is no reason to pay the performance price for something you are not using so make sure you specify only the view engines you need in your Global.asax file:

protected void Application_Start() {
    ViewEngines.Engines.Clear();
    ViewEngines.Engines.Add(new RazorViewEngine());
    ...
}

Customize the view lookup caching

By default (when running in Release mode, of course) MVC will cache the results of the lookups in the application cache available via HttpContext.Cache. While this cache works great and helps us avoid having to check for view files on disk there is also a cost associated with using it (this includes the cost of a thread-safe lookup as well as all the additional cache management such as updating entry expiration policies and performance counters).

To speed things up you could introduce a faster cache in front of the application cache. Fortunately all view engines deriving from VirtualPathProviderViewEngine (that includes WebForms and Razor) have an extensibility point via the settable ViewLocationCache property.

So we can create a new class that implements the IViewLocationCache interface:

public class TwoLevelViewCache : IViewLocationCache {
    private readonly static object s_key = new object();
    private readonly IViewLocationCache _cache;

    public TwoLevelViewCache(IViewLocationCache cache) {
        _cache = cache;
    }

    private static IDictionary<string, string> GetRequestCache(HttpContextBase httpContext) {
        var d = httpContext.Items[s_key] as IDictionary<string, string>;
        if (d == null) {
            d = new Dictionary<string, string>();
            httpContext.Items[s_key] = d;
        }
        return d;
    }

    public string GetViewLocation(HttpContextBase httpContext, string key) {
        var d = GetRequestCache(httpContext);
        string location;
        if (!d.TryGetValue(key, out location)) {
            location = _cache.GetViewLocation(httpContext, key);
            d[key] = location;
        }
        return location;
    }

    public void InsertViewLocation(HttpContextBase httpContext, string key, string virtualPath) {
        _cache.InsertViewLocation(httpContext, key, virtualPath);
    }
}

and augment our view engine registration in the following way:

protected void Application_Start() {
    ViewEngines.Engines.Clear();
    var ve = new RazorViewEngine();
    ve.ViewLocationCache = new TwoLevelViewCache(ve.ViewLocationCache);
    ViewEngines.Engines.Add(ve);
    ... 
}

This TwoLevelViewCache will work best in views that call the same partial multiple times in a single request (and should hopefully have minimum impact on simpler pages).

You could go even further and instead of the simple dictionary stored in httpContext.Items you could use a static instance of ConcurrentDictionary<string, string>. Just remember that if you do that your application might behave incorrectly if you remove or add view files without restarting the app domain.

10/22 Update: This post was written before this feature became a part of NuGet.
This feature is now a part of NuGet and the latest version of this information can be found on the NuGet docs site.
There is also a sample project available.

Over the last few years the ASP.NET team has been including more and more libraries into the various project templates that we ship with Visual Studio and other products. The latest MVC 3 templates come with jQuery, jQuery UI, jQuery Validation, Modernizr, and Entity Framework. All this built-in functionality is great but one remaining snag is that upgrading all the packages by hand can be a pain. Of course the NuGet package manager is an excellent tool that solves the package upgrade problem but so far having project templates with preinstalled NuGet packages was not possible.

This post describes a new feature that will be shipping in NuGet 1.5: preinstalled NuGet packages. Since it is not documented anywhere at this time the purpose of this post is to describe how to create a VS project template with NuGet packages. If you play around with it please also provide feedback so we can make changes/improvements.

Authoring VS project templates is out of scope of this article but you can read more on how to create a project template directly using Visual Studio or using the Visual Studio SDK.

Adding packages to a project templates

NuGet 1.5 is not out yet but the feature has already been checked in and you can try it out by grabbing a recent NuGet preview build and installing the Visual Studio add-in (note that you might have to remove the previous version via the Extension Manager first).

Preinstalled packages work using project template wizards. A special wizard gets invoked when the project gets instantiated. The wizard loads the list of packages that need to be installed and passes that information to the appropriate NuGet APIs. The project template needs to specify where to find the package nupkg files. Currently two package repositories are supported:

1. Packages embedded inside of a VSIX package.
2. Packages embedded inside of the project template itself.

A frequent question is why not support downloading the nupkg files directly from https://nuget.org. We decided not to support such an option because users expect project templates to instantiate quickly and downloading files from the internet would slow things down. Also, it would not work on a plane or in other situations where a connection is not available.

To add preinstalled packages to your project template you need to:

1. Edit your vstemplate file and add a reference to the NuGet template wizard by adding a WizardExtension element:

   <WizardExtension>
       <Assembly>NuGet.VisualStudio.Interop, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null</Assembly>
       <FullClassName>NuGet.VisualStudio.TemplateWizard</FullClassName>
   </WizardExtension>

   NuGet.VisualStudio.Interop.dll is a new assembly that only contains the TemplateWizard class. This class is a simple wrapper that calls into the actual implementation that lives in NuGet.VisualStudio.dll. The assembly version will never change so that project templates continue to work with new versions of NuGet.
2. Add the list of packages to install in the project:

   <WizardData>
       <packages>
           <package id="jQuery" version="1.4.4" />
       </packages>
   </WizardData>

   You can of course add multiple <package> elements. Both the id and version attributes are required. You will notice that this means that a specific version of a package will be installed, even if a newer version is available in the online package feed. We cannot just update to the latest version because a future version of a package might introduce incompatibilities that would break an older version of the project template. It is up to the developer to upgrade using the package manager.

The remaining step is to specify the repository where NuGet can find the package files. As mentioned earlier, two package repository modes are supported:

VSIX package repository

The approach I recommend for deploying Visual Studio project templates is through a VSIX package (read more about VSIX deployment here). The VSIX method is preferable because it allows you to package multiple project templates together and allows developers to easily discover your templates using the VS Extension Manager or the Visual Studio Gallery. On top of that you can easily push updates to your users using the Extension Manager automatic update mechanism.

1. To specify a VSIX as a package repository you modify the <package>element:

   <packages repository="extension"
             repositoryId="MyTemplateExtension.46431780-a0c7-44e0-83c7-5dbd985f8e49">
       ...
   </packages>

The repository attribute specifies the type of repository (“extension”) while repositoryId is the unique identifier of your VSIX (i.e. the value of the ID attribute in the extension’s vsixmanifest file).

You need to add your nupkg files as custom extension content and ensure that they are located under a folder called Packages within the VSIX package. You can place the nupkg files in the same VSIX as your project templates or you can have the packages be located in a separate VSIX if that makes more sense for your scenario (just note that you should not reference VSIXs you do not have control over since they could change in the future and your project templates would break).

Template package repository

If packaging multiple projects is not important to you (e.g. you’re only distributing a single project template), a simpler but also more limited approach is to include the nupgk files in the project template zip file itself.

However, if you are bundling a set of project templates that relate to each other and share NuGet packages (e.g. you are shipping a custom MVC project template with versions for Razor, Web Forms, C#, and VB.NET), we do not recommend adding the NuGet packages directly to each project template zip file. It needlessly increases the size of the project template bundle.

1. To specify the project template as a package repository you modify the <package>element:

   <packages repository="template">
       ...
   </packages>

The repository attribute now has the value “template” and the repositoryId attribute is not longer required. The nupkg files need to be placed into the root directory of the project template.

Depending on which features you are using they might not always apply to your application and their benefit will not be that significant (a few % points improvement at most - sorry I don't have more specific numbers as I'm writing this from memory). I can't guarantee how much improvement you will see as it depends so much on what your application does. But I hope this will provide some leads for you to investigate. Just remember to always measure for your specific scenario.

Disable unused view engines

When: Your application is using built-in display/editor templates (via the Html.EditorFor or Html.DisplayFor methods) and you are using only one type of view engine.

Why: ASP.NET MVC is generally very good about caching file lookup hits (views, partials, display/editor templates). However one scenario that is not cached is the use of the built-in (default) display/editor templates (where all file lookups are misses).

Any time you use the Html.EditorFor or Html.DisplayFor methods and you do not have a matching template file MVC will generate the appropriate markup for you based on the model’s metadata. However, before that happens it checks all the view engines to find a template file. The more view engines you have registered the longer this will take and since the miss is not cached the process will have to be repeated the next time a page is requested. If you are using only one view engine in your project you should remove the other ones in Global.asax. The easies way to do that is with the following code:

ViewEngines.Engines.Clear();
ViewEngines.Engines.Add(new RazorViewEngine());

Avoid passing null models to views

When: You pass in a null model to a view that uses strongly-typed html helpers (such as Html.TextBoxFor). This frequently happens in Insert scenarios.

Why: Strongly-typed html helpers such as Html.TextBoxFor(m => m.Name) will try to emit the value of the model using the provided expression. However when something along the expression chain is null a NullReferenceException will be thrown when the expression gets evaluated. MVC’s expression evaluator catches the exception but on a page with multiple such html helpers the cost of the exception adds up. You can avoid that cost by always passing an instance of the model to the view:

public ActionResult Insert() {
    // return View(); // here the model instance defaults to null
    return View(new Product());
}

Uninstall URL Rewrite if you don’t use it

When: Your IIS server has the URL Rewrite module installed but none of the applications on the server are using it and you are running ASP.NET MVC 3.

Why: When performing URL generation (for example via a method like Html.ActionLink) in some cases MVC checks to see if the currently requested URL has been rewritten by the URL Rewrite module. If that is the case the result is processed so that it correctly matches the URL requested by the client.

The act of checking if a URL has been rewritten has a non-trivial cost (because it involves checking server variables). ASP.NET MVC 3 checks to see if URL Rewrite is turned off and can cache that fact thus avoiding the need to inspect server variables for each request. If URL Rewrite is turned on MVC will have to check server variables even if no rewriting happened for a particular request so if you are not using URL Rewrite you should turn it off (Note that MVC 2 always performs this check so turning URL Rewrite off will not make a difference).

Of course that short statement is not accurate because the only correct answer to such performance questions is: “it depends”. It depends on what your application does and which features it is using: database connections, business logic, output caching, html helpers, etc. I say this because in a moment I will present some numbers and they might not correspond to what you would see in your application. But they should provide you with a good starting point.

The more detailed answer is that some applications will perform better while others will perform worse. That is because as we added new features (dependency injection, improved filters, etc.) some components of MVC 3 got slower than in MVC 2 simply because they are now doing more work. At the same time we have introduced targeted performance optimizations which improved other components. The only definite way you can know the impact on your application is if you carefully measure performance yourself. At the end of this post I will provide a rough list of some of the things that have gotten faster or slower.

The Setup

The application I will use for the tests is the default “Internet Application” project template that ships with every installation of MVC. While quite small, it is still a pretty good choice because it uses a wide variety of MVC features. This means that the test exercises a large part of the framework without focusing on any individual features.

For my tests I have the following applications:

1. MVC 2 Aspx Internet Application project running against MVC 2 runtime
2. MVC 2 Aspx Internet Application project running against MVC 3 runtime
3. MVC 3 Aspx Internet Application project running against MVC 3 runtime
4. MVC 3 Razor Internet Application project running against MVC 3 runtime

I modified each of these applications in the following ways to ensure consistency and remove unnecessary noise from the results:

• Set debug=”false” in the root Web.config file.
• Changed application to build in Release mode.
• Changed the FormsAuthenticationService and MembershipService classes to return hardcoded values (I do not want to test database connection latency).

For each of the applications I executed the following sequence of requests and recorded the throughput (number of requests per second). The sequence ran for about 1 hour in our performance testing lab (meaning that the results should be amortized with respect to any other OS tasks that might have occurred on the server).

1. GET /Home/Index (arrive at site)
2. GET /Account/LogOn (click on “log on” link)
3. POST /Account/LogOn (attempt to log on with invalid credentials)
4. GET /Account/Register (click on “register” link)
5. POST /Account/Register (submit the registration form)

The Results

Note: The above results were captured on a 12-core server and should only be used for comparative purposes. Absolute RPS values on your own machine might de vastly different but their relative distribution should remain the same. 

Applications 1 vs. 2

As you can see from comparing the results for Application 1 and Application 2 the difference is quite small. In fact –1.82% falls within the margin of error. Application 1 and Application 2 are the same identical application, except 1. references System.Web.Mvc.dll version 2.0 and 2. references System.Web.Mvc.dll version 3.0. These results are why we say that MVC 3 is on par with the performance characteristics of MVC 2.

Of course followers of Scott Guthrie will point out that with the RC2 release he claimed that MVC 3 was faster than MVC 2. While that was true at the time it is not correct any longer for RTM. We had to undo a pretty significant performance fix related to model metadata caching because it caused some functional bugs (after all it does not matter how fast your application is if it does not actually work correctly). However, we will have that improvement available as an add-on in MVC Futures and we will roll it into MVC 4.

Applications 2 vs. 3

Comparing Application 2 with Application 3 shows that 3. is –6.64% slower. However, in this case the runtimes are the same. The difference is in the project templates used. The project template that ships with MVC 3 has more functionality enabled by default. Most notably it has unobtrusive client-side validation enabled; MVC 2 project templates did not have client-side validation enabled. The extra time is taken up inspecting the model metadata and emitting additional markup and javascript code. Of course while page rendering will be slower, the overall result of enabling client-side validation should be reduced load on the server as the majority of invalid inputs will be caught on the client thus avoiding the need for unnecessary roundtrips.

Applications 3 vs. 4

The comparison of Application 3 and Application 4 will be of interest to those looking at adopting the new Razor view engine. Application 4 is –4.3% slower than Application 3. This shows that using Razor does have a performance cost. However, that difference is not that big and is outweighed by the elegance and increased readability of the new view engine. Razor is also a new technology and I am sure that as it matures we will be able to optimize it even further.

The Changes

At the beginning of this post I promised that I would list how the various features or components of MVC changed in their performance characteristics. This list is compiled from our internal performance tests as well as change logs. It is meant to be taken as informational only. Your results may vary and depends on how you actually use each feature and what else you have happening in your application

Things that got faster (in no particular order):

• Expression caching (internal subsystem that helps in the performance of methods that accept lambdas)
• URL generation
• Action lookup
• Filter invocation
• TagBuilder

Things that got slower (also in no particular order):

• Things for which Dependency Injection entry points have been exposed
• Auto-generated editor and display helpers
• Model binding

Of course I am not going to tell you by how much things have changed because it depends... you will have to measure yourself.

To help you upgrade your MVC 2 projects to MVC 3 we have released an upgrade tool. You can download it here: https://aspnet.codeplex.com/releases/view/59008. (This is an update of the tool that Eilon Lipton previously previewed on his blog and now we are giving it a more permanent home on our CodePlex site).

April 11 Update: We made a small update to the tool that allows you to skip the backup step. You might want to consider skipping the backup step if you use source control or if your solution is very big.

January 14 Update: We have updated the file on codeplex to fix an issue with converting solutions that had Web Sites or other solution items. If you are having problems please make sure you download the tool again from the codeplex site.

The upgrade tool only supports Visual Studio 2010 projects targeting .NET 4. Upgrading both MVC 2 and MVC 3 Beta (or RC) projects is supported.

The tool does not support Visual Studio 2008 solutions, MVC 1 projects, or projects targeting .NET 3.5. Those projects will first have to be upgraded using Visual Studio 2010 and/or retargeted for .NET 4:

• If you have a Visual Studio 2008 solution you can simply open it with Visual Studio 2010 to initiate the solution upgrade process.
• If your projects are targetting .NET 3.5 read how to target .NET 4.
• If you have a MVC 1.0 project you can use the old version of this tool to convert it to MVC 2.

The usage of the tool is quite simple:

1. If you use a source control system make sure your files are checked out and writable
2. Run the executable
3. Select your Visual Studio 2010 solution file that contains your project
4. Review the changes for each item in the Item details pane
5. Click on the Convert button to initiate the conversion process
6. Review the results in the Conversion log pane

During the conversion process the tool will:

1. Create a backup of the entire solution.
2. Update all class library projects (including Test projects) that reference System.Web.Mvc.dll to reference version 3.0.
3. Update all Web Application projects that reference System.Web.Mvc to reference version 3.0 and add references to System.Web.Helpers.dll and System.Web.WebPages.dll.
4. Change all MVC 2 Web Application projects to be MVC 3 projects (this affects which version of the 'Add View' dialog you get etc) 
5. Update all MVC Web Application root Web.config files:
   1. Update references to System.Web.Mvc version 3.0.
   2. Add an assembly binding redirect entry for System.Web.Mvc.
   3. Add assembly and namespace references to System.Web.Helpers and System.Web.WebPages.
   4. Add the “ClientValidationEnabled” and “UnobtrusiveJavaScriptEnabled” settings to the <appSettings> element with value “false” if they were not already present (these settings can be used to control the unobtrusive client validation and unobtrusive Ajax features).
6. Update all MVC Web Application views Web.config files (~\Views\Web.config as well as the views Web.config files for all Areas):
   1. Update references to System.Web.Mvc version 3.0
   2. Add a <configSections> entry required for Razor configuration in MVC
   3. Add the <system.web.webPages.razor> entry required for Razor support in MVC
   4. Add the “webPages:enabled” setting to the <appSettings> element with value “false” (required to prevent .cshtml or .vbhtml files in the Views folder from being directly accessible from a web browser)
7. Add the following JavaScript libraries to the MVC Web Applications (only if they did not already exist):
   • jQuery 1.4.4 (jquery-1.4.4.js, jquery-1.4.4-vsdoc.js, jquery-1.4.4.min.js)
   • jQuery UI 1.8.7 (jquery-ui.js, jquery-ui.min.js)
   • jQuery Validation 1.7 (jquery-validate.js, jquery-validate-vsdoc.js, jquery-validate.min.js)
   • Microsoft Ajax (MicrosoftAjax.js, Microsoft.Ajax.debug.js)
8. Overwrite MVC-specific JavaScript files in MVC Web Applications:
   • MicrosoftMvcAjax.js, MicrosoftMvcAjax.debug.js, MicrosoftMvcValidation.js, MicrosoftMvcValidation.debug.js, jquery.unobtrusive-ajax.js, jquery.unobtrusive-ajax.min.js, jquery.validate.unobtrusive.js, jquery.validate.unobtrusive.min.js
9. Add jQuery UI theme files (stylesheet and images)

This is an unsupported utility and there is a possibility that it might not work correctly for your solution. Specifically, the tool has the following limitations:

• Read-only project files are not supported (make sure you check out your solution if you use source control)
• Very long file paths might cause problems
• Solutions with project files outside of the solution folder might cause problems
• The tool will not upgrade your application code to account for any potential runtime breaking changes
• Non-standard project files (e.g. missing MVC project type GUID) will not be handled correctly
• Once again, VS 2008 solutions, MVC 1 or .NET 3.5 projects are not supported
• The tool will also not modify any Web Sites in your solution

However, if you run into problems let me know and I will see if we can get them addressed.

One aspect of the relationship between layout pages and sections in Razor that a fair number of people might find surprising is that a section defined in a content page can only be used in its immediate layout. There is implicit scoping going on that prevents certain use cases. Take the following example:

<!DOCTYPE html>
<html>
<body>
@RenderSection("SubSection")
@RenderBody()
</body>
</html>

@{
    Layout = "~/Views/_MasterLayout.cshtml";
}
<div>
@section SubSection {
<h1>Title</h1>
}
@RenderBody()
@RenderSection("ContentSection")
</div>

@{
    Layout = "~/Views/_SubLayout.cshtml";
}
<div>
<p>Main content</p>
@section ContentSection {
<div>Footer</div>
}
</div>

In the above example you can certainly call RenderSection("SubSection") in _MasterLayout.cshtml, as well as call RenderSection("ContentSection") in _SubLayout.cshtml. However, it is impossible to call RenderSection("ContentSection") from _MasterLayout.cshtml because the file rendering the section and the file defining the section are not directly related. Essentially sections are limited to the Content-Layout scope and are not accessible to other layout pages outside of that scope.

Redefining sections

You can work around this by essentially redefining the section in the intermediate layout. 

@{
    Layout = "~/Views/_MasterLayout.cshtml";
}
<div>
@section SubSection {
<h1>Title</h1>
}
@RenderBody()
@section ContentSection {
  @RenderSection("ContentSection", required: false)
}
</div>

Now you are able to reference “ContentSection” from _MasterLayout.cshtml. However you should be aware that you are not overriding “ContentSection" in the same sense as overriding methods in a child class. You are actually defining a new section named “ContentSection” in the SubLayout-MasterLayout scope that renders the section named “ContentSection” from the Content-SubLayout scope. The fact that the names match is incidental. The names certainly do not have to match.

Things get even more complicated when you want to use the IsSectionDefined method to conditionally provide default content for optional sections. Because it’s necessary to propagate “ContentSection” by redefining the section in _SubLayout.cshtml you can no longer depend on IsSectionDefined returning the expected result.

Conditionally redefining sections via RedefineSection

Fortunately not everything is lost. What you want to do is to conditionally redefine a section. Building on the RenderSection helper method from my previous post I created the RedefineSection more helper methods to aid in this scenario:

public static class SectionExtensions {
    private static readonly object _o = new object();
    public static HelperResult RenderSection(this WebPageBase page,
                            string sectionName,
                            Func<object, HelperResult> defaultContent) {
        if (page.IsSectionDefined(sectionName)) {
            return page.RenderSection(sectionName);
        }
        else {
            return defaultContent(_o);
        }
    }

    public static HelperResult RedefineSection(this WebPageBase page,
                            string sectionName) {
        return RedefineSection(page, sectionName, defaultContent: null);
    }

    public static HelperResult RedefineSection(this WebPageBase page,
                            string sectionName,
                            Func<object, HelperResult> defaultContent) {
        if (page.IsSectionDefined(sectionName)) {
            page.DefineSection(sectionName,
                               () => page.Write(page.RenderSection(sectionName)));
        }
        else if (defaultContent != null) {
            page.DefineSection(sectionName,
                               () => page.Write(defaultContent(_o)));
        }
        return new HelperResult(_ => { });
    }
}

The RedefineSection method conditionally redefines a section (that is it redefines in only if a section was already defined in a content page). The second overload also allows you to provide a default content template that will be used if the content page did not define the section. Using this code you can write the following pages:

<!DOCTYPE html>
<html>
<body>
@RenderSection("TitleSection", required: false)
@RenderBody()
</body>
</html>

@{
    Layout = "~/Views/_MasterLayout.cshtml";
}
<div>
@this.RedefineSection("TitleSection",
                      @<h1>Default SubLayout title</h1>)
@RenderBody()
</div>

@{
    Layout = "~/Views/_SubLayout.cshtml";
}
@section TitleContent {
<h1>Title</h1>
}
<p>Main content</p>

In the above example Content.cshtml defines the “TitleContent” section. _SubLayout.cshtml redefines that section but also provides some default markup in case the content page does not have the “TitleContent” section defined. Finally, _MasterLayout.cshtml consumes the section indicating that it is optional – this means that the entire site will still work even if the content page does not define the section and the intermediate layout does not provide a default value.

Hope you find the above technique useful in your complex layout pages. Please let me know if you encounter any issues and whether these methods are valuable enough that they should be added to the framework for the next version.

1. IsSectionDefined method
2. Razor inline templates

RenderSection

The new ASP.NET page framework built on Razor (which is available in MVC 3) provides a facility for content pages to contribute named fragments of markup to their layout pages which the layout page can then render in an arbitrary location using the RenderSection method.

For example, the following content page declares an "ExtraContent" section:

@{
    Layout = "~/Views/Shared/_Layout.cshtml";
}

@section ExtraContent {
    <div>Some extra content</div>
}

<div>The main content</div>

And the following layout page renders it:

<!DOCTYPE html>
<html>
<head></head>
<body>
@RenderBody()

@RenderSection("ExtraContent")
@RenderSection("OptionalContent", required: false)
</body>
</html>

You can even declare that a section is not required like the “OptionalContent” section in the example above.

But what if you want to have some default content for your optional sections?

Option 1: Use the IsSectionDefined method

The IsSectionDefined method returns true if a child content page defined a section. You can use that to decide whether to render a section or some other content:

<!DOCTYPE html>
<html>
<body>
@RenderBody()

@if (IsSectionDefined("OptionalContent")) { 
    @RenderSection("OptionalContent")
}
else { 
    <div>Default content</div>
}
</body>
</html>

Just remember that you need to use the @RenderSection() syntax (you need the @ character) so that the contents of the section is actually printed to the output. Without that character you will get an exception with the following message:

The following sections have been defined but have not been rendered for the layout page "~/Views/Shared/_Layout.cshtml": "OptionalContent"

Option 2: Use Razor inline templates

Razor provides a way to pass inline markup templates into function calls. This is a powerful mechanism that allows you to combine custom markup fragments with general purpose display logic. In order to make the following example work you will need to drop the following code into your project:

using System.Web.WebPages;
using System;

public static class SectionExtensions {
    private static readonly object _o = new object();
    public static HelperResult RenderSection(this WebPageBase page,
                        string sectionName,
                        Func<object, HelperResult> defaultContent) {
        if (page.IsSectionDefined(sectionName)) {
            return page.RenderSection(sectionName);
        }
        else {
            return defaultContent(_o);
        }
    }
}

This code essentially wraps the previous example in a reusable extension method. All you need now is to provide the default content markup. With it you can write views like the following:

<!DOCTYPE html>
<html>
<body>
@RenderBody()

@this.RenderSection("OptionalContent",
                    @<div>Default content</div>)
</body>
</html>

For the second parameter you need to use the @ character to trigger the Razor parser to go into markup mode. Once in markup mode you can do anything that you do in the main body of the page.

Just remember that since this is an extension method you need to call it off the this object. Otherwise the C# compiler will not be able to locate it and you will get a compilation error.

If you like this technique read the follow up: Razor, Nested Layouts and Redefined Sections

Oskar from the ASP.NET forums asked a question about the order of view lookups when using Areas in MVC 3. The problem is that now that MVC ships with two view engines registered by default (WebFormViewEngine and RazorViewEngine), the order of lookups might not work as expected when you are using Areas in conjunction with a mixed environment of Aspx and Razor views.

Take the following application layout as an example. This application has an “Admin” area with a Home controller and a Home Index view written in Razor. There’s also a default Home Index view written using the Aspx view engine.

The Problem

When requesting the Index action of the Admin area’s HomeController you would expect Index.cshtml to be served. However, in MVC 3 you will actually be served Index.aspx. This is because the process for looking up a View involves querying the collection of registered view engine until the first successful match. Once a successful match is found the remaining view engines are ignored. This gets a bit counter-intuitive when you mix Razor and Aspx views because this is the effective search order:

~/Areas/Admin/Views/Home/Index.aspx
~/Areas/Admin/Views/Home/Index.ascx
~/Areas/Admin/Views/Shared/Index.aspx
~/Areas/Admin/Views/Shared/Index.ascx
~/Views/Home/Index.aspx
~/Views/Home/Index.ascx
~/Views/Shared/Index.aspx
~/Views/Shared/Index.ascx
~/Areas/Admin/Views/Home/Index.cshtml
~/Areas/Admin/Views/Home/Index.vbhtml
~/Areas/Admin/Views/Shared/Index.cshtml
~/Areas/Admin/Views/Shared/Index.vbhtml
~/Views/Home/Index.cshtml
~/Views/Home/Index.vbhtml
~/Views/Shared/Index.cshtml
~/Views/Shared/Index.vbhtml

Notice that because the WebFormsViewEngine is registered first by default, the path Views/Home/Index.aspx file gets looked at before the Areas/Admin/Views/Home/Index.cshtml path. That’s because the MVC Areas support is not hardcoded as a general pattern. Instead, it’s the job of each view engine to implement the lookup ordering and fallback logic.

To make things work intuitively, you would need a multi-pass system that first scans all view engines for area-specific matches and then does another pass asking for general matches. But that is not how things are implemented in MVC (mainly because Areas did not exist in MVC 1 and it was not possible to change the existing view lookup contracts).

The Solution

However, it’s actually quite easy to reconfigure MVC to emulate this multi-pass behavior. Just use multiple instances of view engines. In your Global.asax.cs file add the following code (don’t forget to call this method from Application_Start):

public static void SetUpViewEngines(ViewEngineCollection viewEngines) {
    viewEngines.Clear();

    string[] dummyFormats = new[] { "~/ThisFileShouldNotExist.aspx" };

    // area-specific pass
    viewEngines.Add(new WebFormViewEngine {
        ViewLocationFormats = dummyFormats,
        PartialViewLocationFormats = dummyFormats,
        MasterLocationFormats = dummyFormats
    });
    viewEngines.Add(new RazorViewEngine {
        ViewLocationFormats = dummyFormats,
        PartialViewLocationFormats = dummyFormats,
        MasterLocationFormats = dummyFormats
    });

    // general pass
    viewEngines.Add(new WebFormViewEngine {
        AreaViewLocationFormats = null,
        AreaPartialViewLocationFormats = null,
        AreaMasterLocationFormats = null
    });
    viewEngines.Add(new RazorViewEngine {
        AreaViewLocationFormats = null,
        AreaPartialViewLocationFormats = null,
        AreaMasterLocationFormats = null
    });
}

This solution works by first registering a pair of WebForms and Razor view engines that have dummy general location formats pointing to a file that does not exist (meaning that they are effectively only aware of the area-specific locations formats) and then a pair that only knows about the general location formats. This way both Aspx and Razor views will be searched for in area locations and if neither succeed the general views will be searched.

This technique should be helpful for those who want to transition their application from Aspx to Razor (or maybe between some other pair of view engines). However, once you are done with the transition you should probably stick to just having one view engine registered to avoid unnecessary searches in the other view engines.

12/10 Update: In MVC 3 RC 2 SkipRequestValidationAttribute got renamed to AllowHtmlAttribute. I have updated the examples below.

A little while ago I wrote a blog post describing granular request validation that shipped in MVC 3 Beta. However, since then we have changed the API for this feature and that post is no longer valid. In this post I will present the new API which is usable in the recently-shipped MVC 3 Release Candidate.

But first: a quick refresh on request validation and why it’s great to make it granular. Request validation is a feature of ASP.NET that analyzes the data that a browser sends to the server when a user interacts with your site (such as form or query string data) and rejects requests that contain suspicious input that looks like html code (basically anything with a ‘<’). This protects you from HTML injection attacks such as cross-site scripting (XSS). It is enabled by default, however in previous versions it was an all-on-or-off feature, meaning that if you want to be able to accept HTML-formatted input from your users in just one field you had to completely turn this protection off. This in turn meant that you now had to validate every bit of data that came from the client.

AllowHtmlAttribute SkipRequestValidationAttribute

In MVC 3 we are introducing a new attribute called AllowHtmlAttribute. You can use this attribute to annotate your model properties to indicate that values corresponding to them should not be validated. Let’s take this User model and UserController as an example:

public class User {
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    [AllowHtml]
    public string Description { get; set; }
    [AllowHtml]
    public string Bio { get; set; }
}

public class UserController {
    [HttpPost]
    public ActionResult Update(User user) {
        // update user database
    }
}

I have annotated the Description and Bio properties to indicate they should not be request-validated. Now when the Update action method gets invoked these two properties on the User object will not be validated and any HTML they might contain will be passed straight through to the action method. However, everything else will still go through request validation and requests that contain suspicious content in the Name or Email fields will get rejected.

ValidateInputAttribute

AllowHtmlAttribute can only be applied to properties of a model class. For other request validation scenarios the existing ValidateInputAttribute is still helpful. For example, you can use it to disable request validation for action methods that bind to a loose collection of parameters:

[ValidateInput(false)]
public ActionResult Update(int userId, string description) {
}

Now when the parameters of the Update method get bound request validation will not be performed. You can apply ValidateInput to action methods as shown above or to the entire controller to affect all of its action methods.

ValidateInput is also more usable in MVC 3. In MVC 2 running on .NET 4 you had to set requestValidationMode="2.0" in order to turn request validation off. In MVC 3 this is no longer necessary.

11/9 Update: This article only applies to the MVC 3 Beta release. I have a new post about AllowHtmlAttribute that describes the new APIs and behaviors available in MVC 3 RC and later.

If you don’t know already, we have just released the ASP.NET MVC 3 Beta and it brings a slew of new features. A small but useful feature is what we call granular request validation. It allows you to opt out of ASP.NET’s request validation on a field-by-field basis, meaning that it will be a lot easier now to write forms that accept HTML user input (think smart text boxes like TinyMCE, etc.) for some of the fields while at the same time maintaining the built-in security for the rest.

Request Validation is a core ASP.NET feature that helps in preventing cross-site scripting (XSS) and other flavors of HTML injection attacks. It works by examining incoming requests and blocking when any client-supplied data (such as through form fields or the query string) contains potentially dangerous input (for example, the less-than character ‘<’). It is turned on by default and the you have to explicitly disable it if you want to accept HTML-formatted user input. However, until now this was an all-or-nothing setting and turning it off meant that you had to take extra steps to manually validate all of the inputs for malicious content.

In ASP.NET MVC you can control whether an action should have request validation performed using ValidateInputAttriubte. For example the following usage will disable request validation:

[ValidateInput(false)]
public ActionResult MyAction() { ... }

<httpRuntime requestValidationMode="2.0" />

MVC 3 Beta introduces a new property on ValidateInputAttribute called Exclude. Using this property you can opt out of request validation for only some of your fields. For example, take the following User model:

public class User {
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public string Description { get; set; }
    public string Bio { get; set; }
}

If you want your users to be able to edit their Bio or Description and insert arbitrary markup into those two fields while at the same time ensuring no markup makes its way into the Name or Email fields you can annotate your action in the following manner:

[ValidateInput(true, Exclude="Bio, Description")]
public ActionResult Edit(User user) { ... }

The Exclude property takes in a string with a comma-separated list of property/field names that should not be validated. All other fields in the incoming request will be validated and blocked if dangerous input is detected.

With this Beta release it is also no longer necessary to set your application to 2.0 request validation mode. You benefit from .NET 4’s more secure behavior while at the same time being able to allow unvalidated HTML input only on the fields of your choosing.