Customize how your ASP.NET web app responds to HTTP requests using middleware components and the middleware pipeline.

Introduction To ASP.NET Middleware

In this lesson we talked about the prevalent use of web applications and how our actions in a web application correspond to sending requests. We detailed how middleware is responsible for processing those requests sent via HTTP and then returning an appropriate response. We also discussed several different built-in middleware components and how to create our own custom components and add them to the pipeline.

There’s no doubt that middleware plays an essential role in ASP.Net web applications. Now that you’ve completed this lesson you should have a better understanding of how to implement middleware. Happy configuring!

Submitting form initiates HTTP request, which runs through middleware. Middleware returns an HTTP response.

Middleware Review

We know `CreateHostBuilder()` is important because it’s responsible for certain configuration settings for our application, but now, let's take some time to dive into the `UseStartup()` method, which gets called to build our middleware pipeline.

Inside of the `Startup` class is a `Configure()` method. The `Configure()` method calls various `app.UseX()` methods to build the middleware pipeline. Each `app.UseX()` method corresponds to a different component and the methods are typically named based on the action they perform. For example, `app.UseAuthorization()` adds an authorization middleware component to the application.

A key aspect to remember about the `Configure()` method is that the order in which the `app.UseX()` methods are called determines the order in which the components appear in the pipeline. 

Adding Components to the Pipeline

In the previous exercise, we mentioned that each component performs its processing and then has to choose between passing the request to the next delegate in the sequence or short-circuiting the pipeline. The `Use()` method is dedicated for processing and passing the request to the next delegate. The `Run()` method, however, is used when passing the request is no longer desired since we may be at the end of the middleware pipeline and need to start returning a response. 

Before we dive into the `Run()` method, let’s first clarify the point that this method does not have to be included in the pipeline. If there is no `Run()` method, the pipeline will just continue processing until it reaches the last component in the sequence. Similarly, if the `Use()` method does not invoke the next component the pipeline will be short-circuited and the response will be returned.

The `Run()` method is simply another way to begin returning the response to the user. `Run()` is considered terminal middleware because it terminates the pipeline. Remember how we mentioned the importance of properly ordering our components? Well, this concept becomes particularly important when we use the `Run()` method because any delegates after this component will not be executed.

Check out the example below. Notice the placement of methods inside of `Configure()`. Do you see how `app.Run()` appears before `app.UseStaticFiles()`? The `Run()` method will kick off processing to start returning a response to the user. Since the response is already being returned, `UseStaticFiles()` will never get a chance to execute.

```cs
public class Startup
{
 public void Configure(IApplicationBuilder app)
 {
  app.Run(async (context) =>
  {
   await context.Response.WriteAsync("Terminal middleware activated!");
  });
  app.UseStaticFiles();
//Extra code removed for brevity
  }
}
```

Adding Terminal Middleware with IApplicationBuilder.Run()

We know middleware is made up of delegates and these delegates are called in sequence, but let’s discuss how that sequence is determined. When we create a new web application in Visual Studio, the `Program` class and the `Startup` class are added by default. 

The `Program.cs` file is important because it contains the `Main()` method. The `Main()` method is where the application will start and it calls the method, `CreateHostBuilder()`. `CreateHostBuilder()` is important because it’s responsible for certain configuration settings for our application, but the focus of our attention will be on the `UseStartup()` method. 

```cs
namespace TestWebApplication
{
  public class Program
  {
    public static void Main(string[] args)
    {
      CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
      Host.CreateDefaultBuilder(args)
          .ConfigureWebHostDefaults(webBuilder =>
          {
            webBuilder.UseStartup<Startup>();
          });
  }
}
```

If you ever have trouble reading these snippets, copy and paste them into a text editor on your own computer.


Files in project include Program.cs and Startup.cs

Start-Up Files

We know web applications need middleware to be able to respond to user requests. We also know middleware is made up of a series of components. Now, let’s dive deeper into the technical implementation of these components.

Each middleware component is a request delegate. Remember when we talked about how actions inside of web applications are actually sending requests? Well these requests are sent via Hypertext Transfer Protocol (HTTP). A request delegate is simply a function that can process our HTTP requests.

The request delegates used in middleware are created from either an anonymous method or a reusable class. The components are organized in an ordered sequence with each delegate performing its processing and then calling the next. The sequence continues until either the response is returned or the pipeline short circuits, where the component immediately returns a response instead of calling the next component. The pipeline, created by this sequence of delegates, is ultimately responsible for how web applications receive a user’s request and return an appropriate response.

It’s worth noting that the response is returned in the reverse order of which the request is sent. For example, if the request goes through component A, then component B, then component C, the response is returned by going through Component C, then B, and finally, A. For a visual representation, take a second look at the diagram in the previous exercise.

High-level system overview of middleware pipeline

Exploring Middleware Components

We know how middleware components are added to the request pipeline, but how do we know which methods are available for use? We can find this answer by examining the `IApplicationBuilder` interface.

Remember the `Configure()` method we discussed in the previous lesson? The `Configure()` method accepts an `IApplicationBuilder` interface as a parameter:

```cs
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
```

 The `IApplicationBuilder` interface provides the built-in middleware methods. These methods take the format `UseX()` with `X` describing the action performed by the method. There are five `UseX()` methods highlighted in the example below. We’ll examine them in more detail a little later.

1.      `UseHttpsRedirection()` redirects HTTP requests to the more secure HTTPS protocol
2.      `UseStaticFiles()` allows static files, like CSS and images, to be served
3.      `UseRouting()` allows route matching
4.      `UseAuthorization()` ensures requests are authorized
5.      `UseEndpoints()` adds endpoint execution to the middleware pipeline. It runs the code associated with the selected endpoint. 

Note: There are several other built-in middleware components. Visit [the `IApplicationBuilder` documentation](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) to see a complete list.

Examining the IApplicationBuilder Interface

We know components are added to the request pipeline using `Startup.Configure()`. We understand that the middleware request pipeline is a sequence in which each delegate performs its processing and then calls the next component to do the same or short circuits the pipeline. Since the pipeline components are called in sequence, the order in which they are called is very important and is determined by where the component appears in the `Startup.Configure()` method. Let’s dive in and see what effect the ordering of components has on the application.

One way to clearly demonstrate the importance of this order is when dealing with privileged information. Imagine going to your bank’s website to check your account balance. If you request the account summary page, your bank will require you to authenticate before providing the requested information. The account summary page required you to be routed through authentication before returning the information. Order matters.

In much the same way, the order of methods in `Startup.Configure()` determines the order in which components are run in the middleware request pipeline of a .NET web application. Adding components in the incorrect order will affect how the application handles requests. If a user needs to be authorized before viewing certain pages of a website, we want to make sure the `UseAuthorization()` method is included in the pipeline before the requested page is rendered.

The default pathway sends each HTTP request through `UseHttpsRedirection()`, then `UseStaticFiles()`, `UseRouting()`, then `UseAuthorization()`, and finally, `UseEndpoints()`.


Ordering Middleware Components

We know we can use `IApplicationBuilder` to add built-in middleware components to the request pipeline. We also know there’s an entire list of `UseX()` methods available via the interface. Although the built-in middleware provides a wide array of functionality, there may be times when we want to define our own middleware components. Remember when we talked about how middleware delegates perform their processing and then either call the next delegate in the sequence or short-circuit the pipeline? Let’s explore this concept as it relates to custom middleware components. 

We are familiar with the `UseX()` methods provided by `IApplicationBuilder`. However, the interface also provides a generic `Use()` method which can be used to process custom middleware components and call the next component in the pipeline. Multiple middleware components can be chained together with the `Use()` method. The `Use()` method accepts two parameters, the HTTP context and the next middleware component to be called. Let’s take a look at each of these in more detail. 

Previously, we discussed how performing actions inside of a web application correspond with sending requests, more specifically, HTTP requests. Well, each HTTP request and its specific data are encapsulated in the HTTP context object (of type `HttpContext`). So, when the HTTP context object is passed inside of the `Use()` method, we are just passing along the information about an individual HTTP request.

Each middleware component is responsible for making a decision. It must decide to either pass the request to the next component for processing or short-circuit the pipeline by returning a response. If the component is to pass the request to the next delegate in the sequence, the second parameter, `next`, is what provides for this functionality.



Adding Custom Middleware Components

Web applications are everywhere. We use them for shopping, connecting with friends and family, and even for learning. Every time we perform an action in a web application, we are generating a request. When we put an item in our shopping cart on Amazon, we’re making a request. When we click on our friend’s profile, we’re requesting information from the web application. Clicking the button to get us to the next exercise? You guessed it, that’s us sending a request to the web app too.

Some web applications literally receive millions of requests per day. With so many incoming requests, how does the application know where to send each request and ultimately, how to provide the appropriate response? The ability to respond to our requests is at the core of web applications providing user interaction.

Contrary to what we may believe, web applications are not a magical box. Web requests do not disappear inside only to miraculously emerge with the requested information. Truth is,  web applications use a series of components to route each request to its destination and then return an appropriate response to the user. This series of components is organized in a pipeline which is collectively known as middleware.  

Middleware is essential to web applications because it is responsible for processing each request, routing each request, and responding accordingly. In this lesson, we will talk about how components get added to the pipeline and configuring the pipeline. 

What is Middleware?

Within the lambda expression passed to `app.Use()` and `app.Run()`, we can add a `next` parameter. This allows us to call the "next" middleware in the pipeline.

For example, this middleware does nothing but call the next middleware:

```cs
app.Use(async (context, next) =>
{
  await next();
});
```

However in a typical `app.Use()` expression, there are three steps:

```cs
app.Use(async (context, next) =>
{
  // i. Do stuff before next middleware
  await context.Response.WriteAsync("Hello from 1st middleware\n");

  // ii. Execute next middleware 
  await next();

  // iii. Do stuff after next middleware
  await context.Response.WriteAsync("Hello again from 1st middleware\n");
});
```

Now we can start to see the _nested_ aspect of middleware.

![Nested middleware](https://content.codecademy.com/courses/asp-dot-net/Middleware_nested_v2.png)


If the above code matches "Middleware 1" in the diagram, then we can trace its execution through both the code and diagram at the same time: 
* Middleware 1 writes to the response (step `i.` in code and `// logic` in diagram)
* Middleware 1 invokes Middleware 2 (step `ii.` and `next();`)
* Middleware 2 and 3 execute, then control is passed back to Middleware 1
* Middleware 1 writes again to the response (step `iii.` and `// more logic`)

We use `app.Use()` here, but this nested execution happens with all middleware components, including `app.UseDeveloperExceptionPage()`, `app.UseHttpsRedirection()`, etc.
