Rick Strahl's Web Log

Wind, waves, code and everything in between...
ASP.NET • C# • HTML5 • JavaScript • AngularJs
Contact   •   Articles   •   Products   •   Support   •   Search
Ad-free experience sponsored by:
ASPOSE - the market leader of .NET and Java APIs for file formats – natively work with DOCX, XLSX, PPT, PDF, images and more

IIS Default Documents vs. ASP.NET MVC Routes

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:


you'll unpleasantly find:


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


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:

      <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
      <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" 
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


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.

Posted in MVC  

The Voices of Reason


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)
                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:

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.

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! :)

West Wind  © Rick Strahl, West Wind Technologies, 2005 - 2017