In the previous post we looked at what middleware means and how it works in .NET Core. A piece of middleware is a component that can be installed during the startup phase of the application in the Configure method of Startup.cs. The components make up a pipeline that the web request travels through until it reaches a so-called terminal component. Once the request has been processed by a terminal component it travels back through the same pipeline in the opposite direct in order to provide some answer to the request. We saw a couple of examples of built-in middleware and we also investigated how to build our own custom component. We also built a wrapper around our component so that it could be easily installed as an extension method of the application builder.

Understanding the basics of middleware is a good foundation for many other areas in .NET as a lot of functionality requires the installation of middleware in Startup.cs. The topic of this post is no exception. We’re going to look at how to work with static files.

We’ll be working in our demo application DotNetCoreBookstore. If you still have the call to…

…in the beginning of the Configure method then don’t forget to either delete it or comment it out otherwise you might not know why the application is not working.

There’s some good documentation of this topic on the relevant Microsoft guide available here.

Static files and the web root

Static files are the files that don’t change dynamically depending on the web request. They are typically JS, image and CSS files or a static welcome page like index.html. By default we put those files in the wwwroot folder in an ASP.NET Core application. Right now it’s empty in our demo app but go ahead and create two subfolders in there: “js” and “css”. Add a javascript file to the js folder called “myscript.js”:

Let’s just add some javascript code to the file, it doesn’t matter what, we won’t execute it:

Next insert a stylesheet to the css folder called mystyle.css:

We add some dummy content into the stylesheet:

Next we enter 2 html files directly to the wwwroot folder: index.html and myhome.html.

Here’s the markup of index.html:

…and here’s the markup of myhome.html:

Start the application and extend the localhost URL with /index.html and press Enter. You’ll see that the home page is not found.

Middleware for static files

Handling static files also requires the installation of middleware. Extend project.json with the following package in the dependencies section:

“Microsoft.AspNetCore.StaticFiles”: “1.1.0”

Add the following middleware somewhere before app.Run in the Configure method in Startup.cs:

This enables the serving of static files. Run the application and navigate to /index.html, then /myhome.html, /js/myscript.js and /css/mystyle.css. All of them should work and you should see the requested file content in each case.

UseStaticFiles has an overload where we can specify some options. Let’s say that images are stored in a different folder. Add a folder called Images to the root of the solution. Insert some kind of image in the folder, doesn’t matter what. The good thing is that we can call UseStaticFiles multiple times. Here’s how we can make sure that both the default web root and the configured static folder are also searched:

PhysicalFileProvider is located in the Microsoft.Extensions.FileProviders namespace. Path and Directory are part of the System.IO namespace. We tell the middleware to include the Images folder in the search for static files. RequestPath declares the URL path which corresponds to the physical path. I put an image called “csharpcode.png” in the Images folder, make sure you replace the image name when you try the next example. Run the application and navigate to…:


You should see your image in the browser window.

Default home pages

Normally if we navigate to a web site and don’t provide a specific HTML page, such as http://www.cnn.com, then a default home page is served. The default home page name is usually index.htm(l) or home.htm(l). Right now it doesn’t work in our case. Simply calling the localhost URL leads us to show the JSON output like before. This can be easily remedied with an extra middleware:

The UseDefaultFiles must come before…:

If you run the application now then the index.html file will be served up. There are 4 default files defined:





The first one to be found in wwwroot will be returned. If we now navigate to a non-defined path, like http://localhost:4427/whatever , then we’ll still see the JSON response like before.

We can change this behaviour and declare a different default home page. This is how to set myhome.html as the default home page:

Run the application and you should see that myhome.html is served instead of index.html. If that’s not the case then clear your browser cache and rerun the application.

There’s a shortcut to combine UseDefaultFiles and UseStaticFiles called UseFileServer:

This combines the following two lines of code:

It also accepts a couple of options like here to define an additional static file folder:

The built-in welcome page

There’s in fact a “hidden” welcome page that can be activated through a – what else? – piece of middleware. The correct extension method is UseWelcomePage which accepts an optional URL extension as a string:

Make sure you place this code before the last terminal component which is currently Run.

If you navigate to localhost:port/hello then you’ll see a nice blue screen with a welcome message. This page is a great test page in fact if you want to see whether your ASP.NET Core web application has correctly started on the web server.

We stop here and we’ll continue in the next post.

View the list of MVC and Web API related posts here.

Show more