IIS Default Documents vs. ASP.NET MVC Routes

August 15, 2013 • from Hood River, OR • 9 comments

On this page:

Here's a question that I've quite a few times over the years and that takes me a minute to remember myself every time I try to use a static Default document in an ASP.NET MVC application - as I often do for demos.

Suppose you have a static index.htm page in your project, have IIS configured to include index.htm as your default document (as it is by default) and you want it to come up when the browser navigates to the default url of your site or virtual directory. Now when you create a new empty or basic MVC project and leave everything set at the default settings and you go to:

http://localhost:30735/

you'll unpleasantly find:

So why is IIS not finding your default resource? The file exists and using:

http://localhost:30735/index.htm

works, so what's the deal?

ASP.NET MVC takes over URL management and by default the routing is such that all extensionless URLs are controlled by the extensionless Url handler defined in web.config:

 <handlers>
      <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
      <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" 
           type="System.Web.Handlers.TransferRequestHandler" 
           preCondition="integratedMode,runtimeVersionv4.0" />
</handlers>

This handler routes all extensionless URLs into ASP.NET's routing mechanism which MVC then picks up to define its internal route handling. Since

http://localhost:30735/

is an extensionless URL it's treated like any other MVC routed URL and tries to map to a configured routing endpoint/controller action. ASP.NET MVC tries to map the URL to a controller and action, and if the default routing is in place it'll try to find the HomeController and the Index action on it. If that exists it'll display, otherwise the above 404 and corresponding error page shows up.

To display a static default page for the root folder there's luckily an easy way to accomplish the task by using routes.IgnoreRoute(""):

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    routes.IgnoreRoute("");

    routes.MapRoute(
        name: "Default",
        url: "{controller}/{action}/{id}",
        defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }
    );
}

The routes.IgnoreRoute("") ensures that the default route is ignored and that your index.htm file is found by IIS's default document handling as MVC ignores the route and lets IIS do its thing.

Alas your index.htm page is now served.

The Voices of Reason

steve
August 18, 2013

# re: IIS Default Documents vs. ASP.NET MVC Routes

Thanks Rick.

Could you comment on Web API? I have a website (my first) that is a service as well as containing static pages for display.

Doing nothing, my index.htm went to a View.

My RegisterRoutes:

    public class RouteConfig
    {
        public static void RegisterRoutes(RouteCollection routes)
        {
            routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
 
            routes.MapRoute(
                name: "Default",
                url: "{controller}/{action}/{id}",
                defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }
            );
        }
    }

Which I believe sends the request to HomeController.cs, which I doctored up thusly:

    public class HomeController : Controller
    {
        
        // we come here from RouteConfig.cs
 
        /* replaced this with RedirectResult below...
        public ActionResult Index()
        {
            return View();
        }
        */
 
        // so default URL should go to index.html
        public RedirectResult Index()
        {
            return Redirect("~/index.html");
        }
    }

But somehow I don't feel right about it...

Rick Strahl
August 19, 2013

# re: IIS Default Documents vs. ASP.NET MVC Routes

@steve - WebAPI is hooked into the same routing mechanism that MVC uses (ie. the ASP.NET Route Manager) so the same rules apply. If you use IgnoreRoute("") either on the MVC or WebAPI route config you should be able to get the default doc returned on the default URL.

Urls with extensions like index.htm accessed explicitly should always work since they are bypassed by the extensionless routes that MVC/WebAPI setup unless there is an explicit route override somewhere that overrides extensions in the routes.

I know this works with Web API since I've done tons of sample apps that all have default docs and static pages to access the sample data.

Here's one example w/ an app you can try:
http://west-wind.com/weblog/posts/2012/Aug/21/An-Introduction-to-ASPNET-Web-API

Karl
July 30, 2014

# re: IIS Default Documents vs. ASP.NET MVC Routes

That is great!

I like to drop a default.aspx during development, or downtime and then just remove it and it would find the /index.aspx page which would be the normal run-time home page.

So now I can drop the default.aspx in my MVC site and it will show a "under dev" logo or whatever.

The only problem is since there is no index.aspx file on MVC sites I can't navigate to mydomain/index.aspx and see the content that would be displayed e.g. for client previews etc.

Any idea?

Rick Strahl
July 30, 2014

# re: IIS Default Documents vs. ASP.NET MVC Routes

@Karl - that's kind of an odd setup. But I think you can do that by creating a custom route or web.config RewriteUrl rule that reroutes any link to another. With configurations and .config transformations rewriteurls can be different on your dev setup and production.

Chris
August 13, 2014

# re: IIS Default Documents vs. ASP.NET MVC Routes

Thanks so much. Great article, great help, especially after 1.5 hour of looking through junk then finding your article of gold. Thanks! :)

Gary
February 02, 2017

# re: IIS Default Documents vs. ASP.NET MVC Routes

Thank you so much for this. I spent nearly two days trying to fix this problem with a webapi app. This is the only article I found that was of any help.

Dave
February 19, 2017

# re: IIS Default Documents vs. ASP.NET MVC Routes

Rick, I know this is old but any chance you know how to achieve the same with ASP.NET Core, which use the RouteBuilder rather than the RouteCollection to configure routes. Cheers, Dave

flameater
March 04, 2017

# re: IIS Default Documents vs. ASP.NET MVC Routes

Thanks Rick. I couldn't find a more straightforward solution to this dilemma elsewhere in the entire web. Additionally, I had to recompile the project to put this solution into effect.

John Dvoer
June 04, 2020

# re: IIS Default Documents vs. ASP.NET MVC Routes

Thanks Rick! Saved me a lot of time! I had everything configured correctly, but still IIS would not serve the default document. routes.IgnoreRoute(""); so easy to overlook.

Rick Strahl's Weblog