Better understand your app's middleware pipeline by learning some common, built-in middleware components provided by ASP.NET

Built-in ASP.NET Middleware

In a previous lesson, we discussed the basics of middleware. We examined how the middleware components are added in the `Startup.Configure()` method and how the order in which they are called from the `Configure()`method determines the order in which they are added to the pipeline.

The purpose of the `IApplicationBuilder` interface is to provide tools used to configure the request pipeline. The `IApplicationBuilder` interface delivers the built-in middleware components. The components are accessible via methods in the interface and they take the format ‘UseX()’ with X describing the action performed by the method. For example, `UseAuthorization()` adds an authorization middleware component to the application.


Code for Startup.ConfigureServices() includes app.UseX methods

Introduction to Built-in Middleware

So far, we've spent a great amount of time discussing what happens in the middleware pipeline. We've talked about how requests get passed from the server to the pipeline and then from one delegate to the next. We've also mentioned how requests can arrive at the end of the pipeline, get routed appropriately, and then a response is returned. Now, let's dive a little deeper into how requests are routed. 

When the `Configure()` method starts, an important routing component, `UseRouting()`, must be called to compare the HTTP request with the available endpoints and decide which is the best match. Prior to the `UseRouting()` component being executed, the endpoint for all HTTP requests is null and it continues being null unless an appropriate match is found. If we were requesting the Contact page, `UseRouting()` would take our HTTP request and match it with the `/Contact` endpoint. 

It is important to mention that the application would fail without the `UseRouting()` component. Also, a null endpoint or failed routing usually ends with displaying an error page. Although `UseRouting()` does not take the HTTP request to its final destination, it does provide the address of where the request needs to go in order for the proper response to be issued. 


Request for localhost:5001/Contact is routed by UseRouting middleware to Contact.cshtml

Explaining the UseRouting Component

Another common built-in middleware component is the `UseHttpsRedirection()` method. Let’s dive deeper to find out how this method helps our web applications.

HyperText Transfer Protocol, more commonly called HTTP, is a group of standards defining communication between web servers and browsers. HTTP’s job is helping the web server (where our web application will live) and the browser (what the user will be using to interact with our application) communicate with each other.

HyperText Transfer Protocol Secure, more commonly known as HTTPS, is an extension of HTTP for securely transmitting communications between the web server and browser. Part of our job as a developer is making sure our web application is both functional and as secure as possible. HTTPS is the industry standard communication protocol, as HTTP is widely regarded as "unsecure", and should be avoided for any public facing websites. However, what happens when a user sends a request to our application using HTTP?

Well, we have a few options. We could close the connection, present the user with an error page, or we could simply re-route their request through the more secure HTTPS pathway. Typically, the latter option is more common and thankfully we have a built-in middleware component which can easily handle this task.

The `UseHttpsRedirection()` method is the middleware component used to capture HTTP requests and redirect them to the more secure HTTPS.  Since the redirection is done in our configuration the user never even has to know the redirection occurred. Like the other middleware components we’ve reviewed, the `UseHttpsRedirection()` method should also be called from the `Configure()` method of the `Startup` class.


Using the UseHTTPSRedirection Component

In the previous exercise we discussed how the application determines where to send the HTTP request. However, what happens if the user makes a request for a page they are not authorized to view? Well, we also have an ASP.NET built-in component to make handling this situation easier. 

When we create ASP.NET applications, Visual Studio provides us with an option to indicate whether or not we'd like to include authentication, which verifies one's identity. Once a user has been authenticated, we can use authorization to specify the areas which they may access. Setting the application up with the option for authentication allows us to easily implement authorization where necessary.

One way in which authorization can be implemented is through the use of data annotations. Data annotations are attributes that can be added to our .NET classes and methods to enforce specific settings or policies. In our case, we would add the `[Authorize]` data annotation to the page model for which we want users to be authorized.

The `UseAuthorization()` component checks the user's request with their authorization status. Remember when we talked about the importance of components being in the correct order? After `UseRouting()` has established the destination for the request, `UseAuthorization()` checks to see if the destination requires authorization and whether or not the user is authorized. If the authorization check passes, this component will pass the request to the next component in the pipeline. Otherwise, it will short-circuit the pipeline and either present the user with a login page or an error. 

View [ASP.NET authorization documentation](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction?view=aspnetcore-3.1) to see examples and more details about implementing authorization in ASP.NET.


Explaining the UseAuthorization Component

We've reviewed what happens if an exception is thrown when the application is running in a development environment. We've also discussed how the developer exception page reveals a substantial amount of information about the application. Now, let's take a moment to see what should happen if an exception is thrown while the application is running in a production environment. 

Exceptions will happen in every application, but the proper handling of exceptions can prevent an unnecessary security vulnerability. We never want to expose essential details about our application to users. If an exception is thrown in a production environment, one way of handling it is to show users a general error page. Thankfully, ASP.NET has a built-in middleware component to do this. 

The `UseExceptionHandler()` component can be used in production environments. It will catch and log errors and route users to a general error page. The error page can be customized but the significant detail is that this is a way to notify users that an issue has occurred while still hiding the internal details of our application. 

The `UseExceptionHandler()` component has several overloads, but a simple way of using it is to pass in the name of the page (as a string) that should display if an exception is thrown. In the previous exercise, we talked about using conditional logic to determine if the application is running in a development environment. We can add an `else` clause so that if the development environment conditional returns false (i.e. the application is NOT in development) then we call the `UseExceptionHandler()` component.


Explaining the UseExceptionHandler Component

At this point, we’ve discussed setting up exception handlers as the first step in our middleware pipeline. We’ve reviewed how to redirect HTTP requests to a more secure protocol and we’ve talked about a component to render CSS and other static files that affect the appearance of our application. We’ve even discussed how the application determines where to send the HTTP request and how it checks to ensure the request is authorized. Now, let's take a moment to examine how the pipeline starts returning a response for the HTTP request.

Before we begin, let’s first talk about the final destination of a request. In an ASP.NET Core application the final destination of an HTTP request is known as an endpoint. Endpoints are blocks of code capable of handling the HTTP request and providing a response. For example, if the request is for the Contact page of a particular site, the endpoint would be the block of code which returns the Contact page as a response.

If the pipeline is not short-circuited, typically the last component in the pipeline is `UseEndpoints()`. If we think of ASP.NET core routing as being similar to mailing a letter to a friend, we can liken `UseRouting()` to looking up our friend’s address and `UseEndpoints()` to actually placing the addressed letter in the mail and having the postal service send it to the correct destination. From a technical perspective, `UseEndpoints()` calls `MapRazorPages()` with a lambda expression to register the endpoint, and then executes the selected delegate that matches our HTTP request.

```cs
app.UseEndpoints(endpoints =>
{
  // Map Razor pages here
});
```

Once the appropriate delegate for our HTTP request has been executed, a response is generated. The response travels back through the middleware pipeline traversing each component in reverse order until the response is returned to the user. Since `UseEndpoints()` begins returning the response, it is important to note that any code placed after `UseEndpoints()` will only be executed if no endpoint was found to match the request.


Enabling Razor Pages Endpoints

Clearly, the exception page can reveal a substantial amount of information about the application, which is beneficial to the developer, but what about application security? Would we really want to expose internal details about our application to everyone? What about hackers? 

The information in the developer exception page can certainly be detrimental in the wrong hands so deciding when it should be displayed is a key concept in helping safeguard our application and data.

We can use conditional logic to determine the environment in which the application is running and then decide whether we should show the developer exception page. Typically, we will check to see if the application is running in a development environment and if it is, we opt to use the developer exception page in case any exceptions are thrown. However, if the application is not running in development and an exception is thrown, an alternate error handling pathway will be followed.

[`IWebHostEnvironment` is an interface](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.iwebhostenvironment) that provides information about the web hosting environment in which the application is running. An object that implements this interface (`env`) is passed into the `Configure()` method. Inside of the `Configure()` method we can use this object to obtain more information about the environment. This information can then be used to determine if the developer exception page should be shown.


Using the UseDeveloperExceptionPage Component

In conclusion, the middleware pipeline is a system designed to handle each HTTP request, route it to the appropriate destination, and return the correct response. Understanding the functionality of each component is vital to creating a customized pipeline which accurately reflects our desired processing chain. Here are the components we covered in this lesson:

* `UseDeveloperExceptionPage()` provides an exception page specifically designed for developers
* `UseExceptionHandler()` logs and catches errors and routes users to a general error page
* `UseHttpsRedirection()` redirects HTTP requests to the more secure HTTPS protocol
* `UseStaticFiles()` allows static files, like CSS and images, to be served
* `UseRouting()` allows route matching
* `UseAuthorization()` ensures requests are authorized.
* `UseEndpoints()` adds endpoint execution to the middleware pipeline. It runs the code associated with the selected endpoint. 
 
Hopefully, this lesson has provided you with enough information to be able to customize and configure your own middleware pipeline. Happy configuring!

View [ASP.NET middleware documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-5.0#built-in-middleware) to see examples and a full-list of available built-in middleware components.

Built-in Middleware Review

We’ve discussed the `IApplicationBuilder` interface and how it provides the built-in methods used to configure the middleware pipeline. Now, let’s dive deeper into some of the more commonly used built-in methods and explore their functionality. We’ll start with `UseDeveloperExceptionPage()`.

`UseDeveloperExceptionPage()` is a method which provides an exception page specifically designed for developers. While developers are working on the web application, they need to be able to see detailed information about any exceptions that may be thrown. This detailed information can help the developer write better code so the end user can avoid the exception.

The method should be placed before any middleware components that are catching exceptions. Some of the information displayed includes the stack trace, any query string parameters, cookies, headers, and routing information.

Example developer exception page: InvalidOperationException

Explaining the UseDeveloperExceptionPage() Component

Web applications are typically dynamic (frequently changing) in nature. However some of the files associated with web applications do not change. For example, if a file contains code that does not need to be modified we would consider it to be static; the same is true for images that we want displayed. Files that can be presented to the application as-is, without any processing, are known as static files. Some examples of static files would be CSS, Bootstrap, JQuery, and images. Some of these files (Bootstrap, JQuery, etc) are provided by default in the ASP.NET templates.

Static files make up an important part of the application because sometimes they contain code that controls how the application looks and/or behaves. If we want our site to use static files we have to explicitly declare that we want the files to be made available and fortunately, there’s a built-in middleware component for that.

The `UseStaticFiles()` method is available to ensure static file content is rendered alongside the HTML for our web applications. Static files are stored in the **wwwroot** directory and are accessible via a path relative to the web root. In the below example, the **wwwroot** directory contains **css**, **js**, **lib** directories and the **favicon.ico** image file.


```cs
RazorApp
├── Program.cs
├── RazorApp.csproj
├── Startup.cs
├── ...
└── wwwroot
     ├── css
     │   └── site.css
     ├── favicon.ico
     ├── js
     │   └── site.js
     └── lib
     ├── bootstrap
     │   └── ...
     ├── jquery
     │   └── ...
     ├── jquery-validation
     │   └── ...
     └── jquery-validation-unobtrusive
         └── ...
```
For reference, the **site.js** file would be available at:
```
http://localhost:5000/js/site.js
```