Configuring Default Page in ASP.NET Core

Back to: ASP.NET Core Tutorials For Beginners and Professionals

Configuring Default Page in ASP.NET Core

In this article, I will discuss how to configure the default page in the ASP.NET Core Web Application with examples. Please read our previous article, discussing How to Configure Static Files Middleware in ASP.NET Core Web Applications to serve static files such as Images, CSS, JavaScript, etc. At the end of this article, you will understand the Differences Between UseDirectoryBrowser, UseStaticFiles, UseFileServer, and UseDefaultFiles Middleware Components in the ASP.NET Core Application.

How to Configure Default Page in ASP.NET Core:

As we discuss everything from scratch, let’s create a new empty ASP.NET Core Web Application. To do so, open Visual Studio 2022 and click the Create a new project tab, as shown in the image below.

Once you click on the Create a new project tab, it will open the Create a new project window. Select the ASP.NET Core Empty project template from this window and click the Next button, as shown in the image below.

Once you click on the Next button, it will open the Configure Your New Project window. Here, you must provide the necessary information to create a new project. First, give an appropriate name for your project (FirstCoreWebApplication), set the location where you want to create this project, and the solution name for the ASP.NET Core Web application. And finally, click on the Create button, as shown in the image below.

Once you click on the Next button, the following Additional Information window will open. Here, you need to select .NET 8 as the Framework, check the Configure for HTTPS and Do not use top-level statements check boxes, and finally, click the Create button, as shown in the image below.

Once you click the Create Button, the Empty template will create the project. With the Empty project template by default, you will not find the wwwroot folder. The project structure of the ASP.NET Core Web Application with the Empty Project template is shown below.

By default, the ASP.NET Core Empty Project Template does not include the webroot folder, i.e., the wwwroot folder. So, let’s add the wwwroot folder to the project root directory. Right-click on the project, select the add => new folder option from the context menu and then provide the folder name as wwwroot. Once you create the wwwroot folder, your project structure should be shown below.

Adding HTML Page within the wwwroot Folder in ASP.NET Core Application:

Add one HTML page with the name index.html within the wwwroot folder. To do so, right-click on the wwwroot folder and then select add => new item, which will open the following add new item window. From the Add New Item window, search for HTML, select the HTML page, provide the HTML Page name as “index.html,” and then click the Add button as shown in the image below.

Once you add the HTML Page within the wwwroot folder, your project folder structure should look like the one below.

Now, open the index.html file inside the wwwroot folder and copy and paste the following code.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title></title>
</head>
<body>
    <h1> This is Index HTML File</h1>
</body>
</html>

Modifying the Program Class:

To serve static files in ASP.NET Core Web Applications, we need to use the UseStaticFiles Middleware Component in the Request Processing Pipeline. So, let us modify the Program class, as shown below, to use the UseStaticFiles Middleware Component.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            //Adding Static Files Middleware Component to serve the static files
            app.UseStaticFiles();

            //Adding Another Terminal Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            //This will Run the Application
            app.Run();
        }
    }
}

Now run the application and navigate to the URL: http://localhost:<portnumber>/index.html, and you will see the expected output coming from the static Index.html file, as shown in the image below.

Suppose we remove index.html from the URL or navigate to the base URL. In that case, the Terminal Middleware component will handle the request, which is registered using the Run Extension method. The Run Extension method will serve the default request, as shown in the image below.

But we want our index.html page to serve the request when we navigate to the base URL, as shown above. We need to set this page as our default page.

Setting the Default Page in ASP.NET Core Application:

Most Web Applications have a default page, such as index.html or default.html, as their startup page, as it is easy to remember. This Page will be displayed when a user visits the application’s root URL (e.g., https://yoursite.com). For example, if you have a page named index.html and want that page to be your default page, whenever any user visits your application root URL, that page should be displayed. In ASP.NET Core, we can specify this default page using the UseDefaultFiles middleware.

UseDefaultFiles middleware Component in ASP.NET Core

The UseDefaultFiles middleware component in ASP.NET Core specifies a default file (such as index.html or default.html) to be served automatically when a user navigates to a directory without specifying a specific file name. For instance, if a user visits the root URL (https://yoursite.com), UseDefaultFiles will look for specific default files in the wwwroot folder and serve the first one it finds instead of displaying a directory listing or requiring a full URL path to the file (e.g., https://yoursite.com/index.html).

So, please modify the Program class as shown below to use the UseDefaultFiles() middleware component.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            //Setting the Default Files
            app.UseDefaultFiles();

            //Adding Static Files Middleware Component to serve the static files
            app.UseStaticFiles();

            //Adding Another Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            //This will Run the Application
            app.Run();
        }
    }
}

With the above changes in place, now run the application, and you should see the output as expected, as shown below. That index.html page serves as your default page.

Note: You need to add the UseDefaultFiles() middleware before the UseStaticFiles() middleware to serve the default file. Remember that the UseDefaultFiles() middleware is just a URL rewriter, and it never serves static files. Its job is to simply rewrite the incoming URL to the default file, which will then be served by the Static Files Middleware.

How UseDefaultFiles Works in ASP.NET Core?

The UseDefaultFiles middleware searches the wwwroot folder for the following files by default:

index.htm
index.html
default.htm
default.html

If one of these files is found, it will serve as the default page when a user navigates to the root URL. Please remember that UseDefaultFiles only configures the default file path; it doesn’t serve the file by itself, which is why UseStaticFiles is required afterward to serve the file. This is the default behavior.

How to Set Custom HTML Page as the Default Page?

You can also change the default behavior. For example, add another HTML page to the project’s wwwroot folder named MyCustomPage1.html. Once you add the MyCustomPage1.html file, the wwwroot folder contains two HTML files, as shown in the image below.

Now, open the MyCustomPage1.html file and copy and paste the following code.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title></title>
</head>
<body>
    <h1> This is MyCustomPage1 HTML File</h1>
</body>
</html>

Setting MyCustomPage1.html as Default Page:

Now, we want the MyCustomPage1.html page to be our default page instead of the index.html page. To do this, we need to configure DefaultFilesOptions.

Please modify the Program class as follows. Here, we create an instance of the DefaultFilesOptions class, adding the default file name as MyCustomPage1.html, and then passing the DefaultFilesOptions instance to the UseDefaultFiles middleware component. The following code is self-explained, so please read the comment lines for a better understanding.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            //Specify the MyCustomPage1.html as the default page
            //First Create an Instance of DefaultFilesOptions
            DefaultFilesOptions defaultFilesOptions = new DefaultFilesOptions();

            //Clear any DefaultFileNames if already there
            defaultFilesOptions.DefaultFileNames.Clear();

            //Add the default HTML Page to the DefaultFilesOptions Instance
            defaultFilesOptions.DefaultFileNames.Add("MyCustomPage1.html");

            //Setting the Default Files
            //Pass the DefaultFilesOptions Instance to the UseDefaultFiles Middleware Component
            app.UseDefaultFiles(defaultFilesOptions);

            //Adding Static Files Middleware Component to serve the static files
            app.UseStaticFiles();

            //Adding Another Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            //This will Run the Application
            app.Run();
        }
    }
}

Now run the application, and you will see the output from the MyCustomPage1.html file, as shown in the image below. If you still see the output from the index.html page, it may be due to the cache, so try reloading it. If you are still not getting the data from the MyCustomPage1.html file, restart Visual Studio.

UseDirectoryBrowser Middleware Component in ASP.NET Core Application:

The UseDirectoryBrowser middleware component in ASP.NET Core enables directory browsing functionality, allowing clients to view the directory’s file structure. It generates an HTML page displaying the files and folders within the specified directory when enabled. This middleware is useful for development and debugging purposes, as it lets developers explore the files directly on the server, though it’s typically not recommended in production for security reasons.

By default, ASP.NET Core doesn’t enable directory browsing. You can enable it by adding the UseDirectoryBrowser middleware component to the application pipeline. Let us understand this with an example. Please modify the Main method of the Program class as follows. Here, I am using the UseDirectoryBrowser Middleware Component.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            // Enable directory browsing on the current path
            app.UseDirectoryBrowser();

            app.UseStaticFiles();

            //Adding Another Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            //This will Run the Application
            app.Run();
        }
    }
}

Now, run the application. When you visit the root URL, you will see the directory structure of the wwwroot folder, as shown in the image below.

How Does UseDirectoryBrowser Work Internally?

When a client accesses the specified RequestPath, the middleware:

Check for the presence of the UseDirectoryBrowser middleware.
Generates an HTML page showing the files and directories within the specified folder.
Lists files with links, allowing users to download or view the files directly.

UseFileServer() Middleware Component in ASP.NET Core:

The UseFileServer middleware component in ASP.NET Core provides an all-in-one solution for serving static files, setting a default page, and enabling directory browsing within an ASP.NET Core Web application. By combining the functionalities of UseStaticFiles, UseDefaultFiles, and UseDirectoryBrowser, UseFileServer simplifies the configuration process for serving static content and managing directory browsing. So, when we add UseFileServer to the middleware pipeline, it automatically includes:

Static File Serving (UseStaticFiles): This option enables the serving of static files (e.g., CSS, JavaScript, images) from the wwwroot directory or any specified directory.
Default File Serving (UseDefaultFiles): Configures a default file (e.g., index.html, default.html) to be displayed when the user accesses the root URL of a directory.
Directory Browsing (UseDirectoryBrowser): Enables the option for users to view the directory contents in the browser (e.g., see the files in a folder if no default file is present).

How to Use UseFileServer in ASP.NET Core

Using UseFileServer is straightforward. We need to use the app.UseFileServer(); middleware. This single line configures all three functionalities to serve static files, set a default page, and enable directory browsing.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            //Enable Default File, Static File and Directory Browsing
            app.UseFileServer();

            //Adding Another Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            //This will Run the Application
            app.Run();
        }
    }
}

Now, run the application. It will display the Index.html page by default when you access the root URL, as shown in the image below.

Directory browsing is disabled by default for security reasons, but you can explicitly enable it. To enable directory browsing, please modify the Program class as follows. We need to customize UseFileServer with the FileServerOptions to control the behavior of each component.

using Microsoft.Extensions.FileProviders;

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);
            var app = builder.Build();

            // Configure FileServer options for root directory browsing
            var fileServerOptions = new FileServerOptions
            {
                EnableDirectoryBrowsing = true, // Enable directory browsing at the root URL
                FileProvider = new PhysicalFileProvider(Path.Combine(Directory.GetCurrentDirectory(), "wwwroot"))
            };

            // Enable Default File, Static File, and Directory Browsing at the root URL
            app.UseFileServer(fileServerOptions);

            // Adding Another Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            // This will Run the Application
            app.Run();
        }
    }
}

Explanation of FileServerOptions Properties

EnableDirectoryBrowsing: Enables or disables directory browsing. Users can view and navigate directory contents in the specified path when true.
FileProvider: Sets the file provider, determining the root directory from which files are served. In this example, it’s set to the wwwroot folder.

Note: With this configuration, when you navigate to the root URL, directory browsing will be displayed if there’s no default file (like index.html or default.html) in the wwwroot folder. If default pages are there, they will be displayed instead of directory browsing.

How Do I Ignore the Default Page and Show Directory Browsing?

There are two options. First, remove the default page. The second option is to clear the default page setting in the FileServerOptions instance. Let us use the second option. Modify the Program class file as follows:

using Microsoft.Extensions.FileProviders;

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);
            var app = builder.Build();

            // Configure FileServer options for root directory browsing
            var fileServerOptions = new FileServerOptions
            {
                EnableDirectoryBrowsing = true, // Enable directory browsing at the root URL
                FileProvider = new PhysicalFileProvider(Path.Combine(Directory.GetCurrentDirectory(), "wwwroot"))
            };

            // Clear the default file names to prevent showing the default page
            fileServerOptions.DefaultFilesOptions.DefaultFileNames.Clear();

            // Enable Default File, Static File, and Directory Browsing at the root URL
            app.UseFileServer(fileServerOptions);

            // Adding Another Middleware Component to the Request Processing Pipeline
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Request Handled and Response Generated");
            });

            // This will Run the Application
            app.Run();
        }
    }
}

Now, with the above changes in place, run the application, and you should see directory browsing when you visit the root URL. If you are not seeing directory browsing, it is because of caching issues. You can try with a different launch profile or restart Visual Studio, and it should work.

Differences Between UseDirectoryBrowser, UseStaticFiles, UseFileServer, and UseDefaultFiles

In ASP.NET Core, the middleware components UseDirectoryBrowser, UseStaticFiles, UseFileServer, and UseDefaultFiles serve different purposes when handling static content. Each enables specific functionality, and understanding their differences helps correctly configure how static files and directories are accessed.

UseStaticFiles

Serves static files such as HTML, CSS, JavaScript, and images directly to clients. Serves files from the wwwroot folder by default. Responds to requests matching the file’s URL path directly without additional processing.
Use UseStaticFiles when you only need to serve static content (e.g., CSS, JS, images) without requiring a default file or directory browsing.

UseDefaultFiles

Configures a default file to be served automatically when a directory is requested (e.g., index.html or default.html). By default, look for index.html, index.htm, default.html, or default.htm by default. It only sets the default file behavior and does not serve the files itself; it requires UseStaticFiles afterward to serve the files.
Use UseDefaultFiles with UseStaticFiles if you want a specific default file (like index.html) to be served automatically when accessing a directory URL.

UseDirectoryBrowser

Enables directory browsing, allowing users to see and navigate the contents of directories on the server. It generates an HTML page showing the directory’s contents, allowing users to view and download files directly. It should only be used in development or trusted internal environments, as it exposes all files within a directory to users.
Use UseDirectoryBrowser in scenarios where directory contents need to be accessible, such as in a development environment or an internal documentation site.

UseFileServer

It combines the functionality of UseStaticFiles, UseDefaultFiles, and UseDirectoryBrowser into a single middleware. This is useful for scenarios where you need to enable multiple static file-related features at once.
Use UseFileServer when you want a single middleware configuration to serve static files, handle default files, and enable directory browsing.

For a Detailed comparison, please have a look at the following diagram.

In the next article, I will discuss the Developer Exception Page Middleware in ASP.NET Core Web Applications with Examples. In this article, I try to explain how to configure the default page in the ASP.NET Core Web Application with examples. Please post your feedback, questions, or comments about this Configuring Default Page in the ASP.NET Core Web Application article.

Dot Net Tutorials

About the Author: Pranaya Rout

Pranaya Rout has published more than 3,000 articles in his 11-year career. Pranaya Rout has very good experience with Microsoft Technologies, Including C#, VB, ASP.NET MVC, ASP.NET Web API, EF, EF Core, ADO.NET, LINQ, SQL Server, MYSQL, Oracle, ASP.NET Core, Cloud Computing, Microservices, Design Patterns and still learning new technologies.

5 thoughts on “Configuring Default Page in ASP.NET Core”

henji
September 22, 2020 at 11:24 am

Very great, very clear thinking, there is no github, convenient for you to sponsor?

CaoFangsheng
June 20, 2021 at 6:02 am

Very good article ,helps me a lot ,thanks

ANURAG MOHANTY
November 7, 2022 at 10:42 pm

Could you plz explain DirectoryBrowser middleware with a real-time example in a web application, why we use and when we should use…

1. Dot Net Tutorials
  January 20, 2024 at 9:55 am
  
  DirectoryBrowser middleware is only for the development. Even though it is provided, we never used it on production because of security. We should not expose our directory to everyone.
  
sameera
June 10, 2023 at 11:52 pm

great job