IOptions<T><\/code> pattern, and in section 31.2 you\u2019ll learn how to take this further. You\u2019ll learn how to use the OptionsBuilder<T><\/code> type to \ufb02uently build your IOptions<T><\/code> object with the builder pattern. You\u2019ll also see how to use services from DI when con\ufb01guring your IOptions objects\u2014something that\u2019s not possible using the methods you\u2019ve seen so far.<\/p>\nWe stick with DI in section 31.3, where I\u2019ll show you how to replace the built-in DI container with a third-party alternative. The built-in container is \ufb01ne for most small apps, but your ConfigureServices function can quickly get bloated as your app grows and you register more services.<\/p>\n
I\u2019ll show you how to integrate the third-party Lamar library into an existing app, so you can use extra features such as automatic service registration by convention.<\/p>\n
The components and techniques shown in this chapter are more advanced than most features you\u2019ve seen so far. You likely won\u2019t need them in every ASP.NET Core project, but they\u2019re good to have in your back pocket should the need arise!<\/p>\n
31.1 Customizing your middleware pipeline\u200c<\/h2>\n
In this section you\u2019ll learn how to create custom middleware. You\u2019ll learn how to use the Map, Run, and Use extension methods to create simple middleware using lambda expressions. You\u2019ll then see how to create equivalent middleware components using dedicated classes. You\u2019ll also learn how to split the middleware pipeline into branches, and you\u2019ll \ufb01nd out when this is useful.<\/p>\n
The middleware pipeline is one of the building blocks of ASP.NET Core apps, so we covered it in depth in chapter 4. Every request passes through the middleware pipeline, and each middleware component in turn gets an opportunity to modify the request or to handle it and return a response.<\/p>\n
ASP.NET Core includes middleware for handling common scenarios out of the box. You\u2019ll \ufb01nd middleware for serving static \ufb01les, handling errors, authentication, and many more tasks.<\/p>\n
You\u2019ll spend most of your time during development working with Razor Pages, minimal API endpoints, or web API controllers. These are exposed as the endpoints for most of your app\u2019s business logic, and they call methods on your app\u2019s various business services and models. However, you\u2019ve also seen middleware like the Swagger middleware and the WelcomePageMiddleware that returns a response without using the endpoint routing system. The various improvements to the routing system in .NET 7 mean I rarely \ufb01nd the need to create \u201cterminal\u201d middleware like this, as endpoint routing is easy to work with and extensible.Nevertheless, it may occasionally be preferable to create small, custom, terminal middleware components like these.<\/p>\n
At other times, you might have requirements that lie outside the remit of Razor Pages or minimal API endpoints. For example, you might want to ensure that all responses generated by your app include a speci\ufb01c header. This sort of cross-cutting concern is a perfect \ufb01t for custom middleware. You could add the custom middleware early in your middleware pipeline to ensure that every response from your app includes the required header, whether it comes from the static-\ufb01le middleware, the error handling middleware, or a Razor Page.<\/p>\n
In this section I show three ways to create custom middleware components, as well as how to create branches in your middleware pipeline where a request can \ufb02ow down either one branch or another. By combining the methods demonstrated in this section, you\u2019ll be able to create custom solutions to handle your speci\ufb01c requirements.<\/p>\n
We start by creating a middleware component that returns the current time as plain text whenever the app receives a request. From there we\u2019ll look at branching the pipeline, creating general-purpose middleware components, and encapsulating your middleware into standalone classes.<\/p>\n
Finally, in section 31.1.5 you\u2019ll see how to turn your custom middleware component into an endpoint and integrate it with the endpoint routing system.<\/p>\n
31.1.1 Creating simple apps with the Run extension\u200c<\/h3>\n
As you\u2019ve seen in previous chapters, you de\ufb01ne the middleware pipeline for your app in Program.cs by adding middleware to a WebApplication object, typically using extension methods, as in this example:\u200c<\/p>\n
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nWebApplication app = builder.Build();\napp.UseExceptionHandler();\napp.UseStaticFiles();\napp.Run();<\/code><\/pre>\nWhen your app receives a request, the request passes through each middleware component, each of which gets a chance to modify the request or handle it by generating a response. If a middleware component generates a response, it e\ufb00ectively short-circuits the pipeline; no subsequent middleware in the pipeline sees the request. The response passes back through the earlier middleware components on its way back to the browser.<\/p>\n
You can use the Run extension method to build a simple middleware component that always generates a response. This extension takes a single lambda function that runs whenever a request reaches the component. The Run extension always generates a response, so no middleware placed after it ever executes. For that reason, you should always place the Run middleware last in a middleware pipeline.<\/p>\n
TIP<\/b> Remember that middleware components run in the order in which you add them to the pipeline. If a middleware component handles a request and generates a response, later middleware never sees the request.<\/p>\n
The Run extension method provides access to the request in the form of the HttpContext object you saw in chapter 4. This contains all the details of the request in the Request property, such as the URL path, the headers, and the body of the request. It also contains a Response property you can use to return a response.\u200c\u200c\u200c<\/p>\n
The following listing shows how you could build a simple middleware component that returns the current time. It uses the provided HttpContext context object and the Response property to set the Content-Type header of the response (not strictly necessary in this case, as text\/plain is used if an alternative content type is not set) and writes the body of the response using WriteAsync(text).<\/p>\n
Listing 31.1 Creating simple middleware using the Run extension<\/p>\n
app.Run(async (HttpContext context) => \u2776\n{\ncontext.Response.ContentType = "text\/plain"; \u2777\nawait context.Response.WriteAsync( \u2778\nDateTimeOffset.UtcNow.ToString()); \u2778\n});\napp.UseStaticFiles(); \u2779<\/code><\/pre>\n\u2776 Uses the Run extension to create simple middleware that always returns a response
\n\u2777 You should set the content-type of the response you\u2019re generating; text\/plain is the default value.
\n\u2778 Returns the time as a string in the response. The 200 OK status code is used if not explicitly set.
\n\u2779 Any middleware added after the Run extension will never execute.<\/p>\n
The Run extension is useful for two di\ufb00erent things:<\/p>\n
\u2022 Creating simple middleware that always generates a response<\/p>\n
\u2022 Creating complex middleware that hijacks the whole request to build an additional framework on top of ASP.NET Core<\/p>\n
Whether you\u2019re using the Run extension to create basic endpoints or a complex extra framework layer, the middleware always generates some sort of response.<\/p>\n
Therefore, you must always place it at the end of the pipeline, as no middleware placed after it will execute.<\/p>\n
TIP<\/b> Using the Run extension to unconditionally generate a response is rare these days. The endpoint routing system used by minimal APIs provides many extra niceties such as model binding, routing, integration with other middleware such as authentication and authorization, and so on.<\/p>\n
There may be occasional situations where you want to unconditionally generate a response, but a more common scenario is where you want your middleware component to respond only to a speci\ufb01c URL path, such as the way the Swagger UI middleware responds only to the \/swagger path. In the next section you\u2019ll see how you can combine Run with the Map extension method to create branching middleware pipelines.<\/p>\n
31.1.2 Branching middleware\u200c pipelines with the Map extension<\/h3>\n
So far when discussing the middleware pipeline, we\u2019ve always considered it to be a single pipeline of sequential components. Each request passes through every middleware component until one component generates a response; then the response passes back through the previous middleware.<\/p>\n
The Map extension method lets you change that simple pipeline into a branching structure. Each branch of the pipeline is independent; a request passes through one branch or the other but not both, as shown in \ufb01gure 31.1. The Map extension method looks at the path of the request\u2019s URL. If the path starts with the required pattern, the request travels down the branch of the pipeline; otherwise, it remains on the main trunk. This lets you have completely di\ufb00erent behavior in di\ufb00erent branches of your middleware pipeline.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3101.jpg\")
<\/p>\n
Figure 31.1 A sequential middleware pipeline compared with a branching pipeline created with the Map extension. In branching middleware, requests pass through only one of the branches at most. Middleware on the other branch never see the request and aren\u2019t executed.<\/p>\n
NOTE<\/b> The URL-matching used by Map is conceptually similar to the routing you\u2019ve seen throughout the book, but it is much more basic, with many limitations. For example, it uses a simple string-pre\ufb01x match, and you can\u2019t use route parameters. Generally, you should favor using endpoint routing instead of branching using Map. A similar extension, MapWhen, allows matching based on anything in HttpContext, such as headers or query string parameters.<\/p>\n
For example, imagine you want to add a simple health-check endpoint to your existing app. This endpoint is a simple URL you can call that indicates whether your app is running correctly. You could easily create a health-check middleware using the Run extension, as you saw in listing 31.1, but then that\u2019s all your app can do. You want the health-check to respond only to a speci\ufb01c URL, \/ping. Your Razor Pages should handle all other requests as normal.<\/p>\n
TIP<\/b> The health-check scenario is a simple example for demonstrating the Map method, but ASP.NET Core includes built-in support for health-check endpoints, which integrate into the endpoint routing system. You should use these instead of creating your own. You can learn more about creating health checks in Microsoft\u2019s \u201cHealth checks in ASP.NET Core\u201d documentation: http:\/\/mng.bz\/nMA2<\/a>.<\/p>\nOne solution would be to create a branch using the Map extension method and to place the health-check middleware on that branch, as shown in \ufb01gure 31.1. Only those requests that match the Map pattern \/ping will execute the branch; all other requests are handled by the standard routing middleware and Razor Pages on the main trunk instead, as shown in the following listing.<\/p>\n
Listing 31.2 Using the Map extension to create branching middleware pipelines<\/p>\n
app.UseStatusCodePages(); \u2776\napp.Map("\/ping", (IApplicationBuilder branch) => \u2777\n{\nbranch.UseExceptionHandler(); \u2778\nbranch.Run(async (HttpContext context) => \u2779\n{ \u2779\ncontext.Response.ContentType = "text\/plain"; \u2779\nawait context.Response.WriteAsync("pong"); \u2779\n}); \u2779\n});\napp.UseStaticFiles(); \u277a\napp.UseRouting(); \u277a\napp.MapRazorPages(); \u277a\napp.Run();<\/code><\/pre>\n\u2776 Every request passes through this middleware.
\n\u2777 The Map extension method branches if a request starts with \/ping.
\n\u2778 This middleware runs only for requests matching the \/ping branch.
\n\u2779 The Run extension always returns a response, but only on the \/ping branch.
\n\u277a The rest of the middleware pipeline run for requests that don\u2019t match the \/ping branch.<\/p>\n
The Map middleware creates a completely new IApplicationBuilder (called branch in the listing), which you can customize as you would your main app pipeline. Middleware added to the branch builder are added only to the branch pipeline, not the main trunk pipeline.\u200c<\/p>\n
TIP<\/b> The WebApplication object you typically add middleware to implements the IApplicationBuilder interface. Most extension methods for adding middleware use the IApplicationBuilder interface, so you can use\u200c the extension methods in branches as well as your main middleware pipeline.<\/p>\n
In this example, you add the Run middleware to the branch, so it executes only for requests that start with \/ping, such as \/ping, \/ping\/go, and \/ping?id=123. Any requests that don\u2019t start with \/ping are ignored by the Map extension. Those requests stay on the main trunk pipeline and execute the next middleware in the pipeline after Map (in this case, the StaticFilesMiddleware).<\/p>\n
WARNING<\/b> There are several Map extension method overloads. Some of these are extension methods on IApplicationBuilder and are used to branch the pipeline, as you saw in listing 31.2. Other overloads are extensions on IEndpointRouteBuilder and are used to create minimal endpoints, using the endpoint routing system. If you\u2019re struggling to make your app compile, make sure that you\u2019re not accidentally using the wrong Map overload!<\/p>\n
If you need to, you can create sprawling branched pipelines using Map, where each branch is independent of every other. You could also nest calls to Map so you have branches coming o\ufb00 branches.<\/p>\n
The Map extension can be useful, but if you try to get too elaborate, it can quickly get confusing. Remember that you should use middleware for implementing cross-cutting concerns or simple endpoints. The endpoint routing mechanism of minimal APIs and Razor Pages is better suited to more complex routing requirements, so always favor it over Map where possible.<\/p>\n
One situation where Map can be useful is when you want to have two independent subapplications but don\u2019t want the hassle of multiple deployments. You can use Map to keep these pipelines separate, with separate routing and endpoints inside each branch of the pipeline.<\/p>\n
TIP<\/b> This approach can be useful, for example, if you\u2019re embedding an OpenID Connect server such as IdentityServer in your application. By mapping IdentityServer to a branch, you ensure that the endpoints and controllers in your main app can\u2019t interfere with the endpoints exposed by IdentityServer.<\/p>\n
Be aware that these branches share con\ufb01guration and a DI container, so they\u2019re independent only from the middleware pipeline\u2019s point of view. You must also remember that WebApplication adds lots of middleware to the pipeline by default, so you may need to override these by explicitly calling UseRouting() in all your branches, for example.<\/p>\n
NOTE<\/b> Achieving truly independent branches in the same application requires a lot of e\ufb00ort. See Filip Wojcieszyn\u2019s blog post, \u201cRunning multiple independent ASP.NET Core pipelines side by side in the same application,\u201d for guidance: http:\/\/mng.bz\/vzA4<\/a>.<\/p>\nThe \ufb01nal point you should be aware of when using the Map extension is that it modi\ufb01es the e\ufb00ective Path seen by middleware on the branch. When it matches a URL pre\ufb01x, the Map extension cuts o\ufb00 the matched segment from the path, as shown in \ufb01gure 31.2. The removed segments are stored on a property of HttpContext called PathBase, so they\u2019re still accessible if you need them.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3102.jpg\")
<\/p>\n
Figure 31.2 When the Map extension diverts a request to a branch, it removes the matched segment from the Path property and adds it to the PathBase property.\u200c<\/p>\n
NOTE<\/b> ASP.NET Core\u2019s link generator (used in Razor and minimal APIs, as discussed in chapter 6) uses PathBase to ensure that it generates URLs that include the PathBase as a pre\ufb01x.<\/p>\n
You\u2019ve seen the Run extension, which always returns a response, and the Map extension, which creates a branch in the pipeline. The next extension we\u2019ll look at is the general- purpose Use extension.<\/p>\n
31.1.3 Adding to the pipeline with the Use extension\u200c<\/p>\n
You can use the Use extension method to add a general- purpose piece of middleware. You can use it to view and modify requests as they arrive, to generate a response, or to pass the request on to subsequent middleware in the pipeline.<\/p>\n
As with the Run extension, when you add the Use extension to your pipeline, you specify a lambda function that runs when a request reaches the middleware. ASP.NET Core passes two parameters to this function:<\/p>\n
\u2022 The HttpContext representing the current request and response\u2014You can use this to inspect the request or generate a response, as you saw with the Run extension.<\/p>\n
\u2022 A pointer to the rest of the pipeline as a Func\u2014By executing this task, you can execute the rest of the middleware pipeline.<\/p>\nBy providing a pointer to the rest of the pipeline, you can use the Use extension to control exactly how and when the rest of the pipeline executes, as shown in \ufb01gure 31.3. If you don\u2019t call the provided Func at all, the rest of the pipeline doesn\u2019t execute for the request, so you have complete control.<\/p>\n![\"alt](\"\/images\/aspnetcoreinaction\/3103.jpg\")
<\/p>\n
Figure 31.3 Three pieces of middleware, created with the Use extension. Invoking the provided Func using next() invokes the rest of the pipeline. Each middleware component can run code before and after calling the rest of the pipeline, or it can choose to not call next() to short-circuit the pipeline.<\/p>\nExposing the rest of the pipeline as a Func makes it easy to conditionally short-circuit the pipeline, which enables<\/p>\nmany scenarios. Instead of branching the pipeline to implement the health-check middleware with Map and Run, as you did in listing 31.2, you could use a single instance of the Use extension, as shown in the following listing. This provides the same required functionality as before but does so without branching the pipeline.<\/p>\n
Listing 31.3 Using the Use extension method to create a health-check middleware<\/p>\n
app.Use(async (HttpContext context, Func<Task> next) => \u2776\n{\nif (context.Request.Path.StartsWithSegments("\/ping")) \u2777\n{\ncontext.Response.ContentType = "text\/plain"; \u2778\nawait context.Response.WriteAsync("pong"); \u2778\n}\nelse\n{\nawait next(); \u2779\n}\n});\napp.UseStaticFiles();<\/code><\/pre>\n\u2776 The Use extension takes a lambda with HttpContext (context) and Func<Task><\/code> (next) parameters.
\n\u2777 The StartsWithSegments method looks for the provided segment in the current path.
\n\u2778 If the path matches, generates a response and short-circuits the pipeline
\n\u2779 If the path doesn\u2019t match, calls the next middleware in the pipeline\u2014in this case UseStaticFiles()\\<\/p>\nIf the incoming request starts with the required path segment (\/ping), the middleware responds and doesn\u2019t call the rest of the pipeline. If the incoming request doesn\u2019t start with \/ping, the extension calls the next middleware in the pipeline, with no branching necessary.<\/p>\n
With the Use extension, you have control of when and whether you call the rest of the middleware pipeline. But it\u2019s important to note that you generally shouldn\u2019t modify the Response object after calling next(). Calling next() runs the rest of the middleware pipeline, so subsequent middleware may start streaming the response to the browser. If you try to modify the response after executing the pipeline, you may end up corrupting the response or sending invalid data.<\/p>\n
WARNING<\/b> Don\u2019t modify the Response object after calling next(). Also, don\u2019t call next() if you\u2019ve written to the Response.Body; writing to this Stream can trigger Kestrel to start streaming the response to the browser, and you could cause invalid data to be sent. You can generally read from the Response object safely, such as to inspect the \ufb01nal StatusCode or ContentType of the response.<\/p>\n
Another common use for the Use extension method is to modify every request or response that passes through it. For example, you should send various HTTP headers with all your applications for security reasons. These headers often disable old, insecure legacy behaviors by browsers or restrict the features enabled by the browser. You learned about the HSTS header in chapter 28, but you can add other headers for additional security.<\/p>\n
TIP<\/b> You can test the security headers for your app at https:\/\/securityheaders.com<\/a>, which also provides information about what headers you should add to your application and why.<\/p>\nImagine you\u2019ve been tasked with adding one such header\u2014 X-Content-Type-Options: nosniff, which provides added protection against cross-site scripting (XSS) attacks\u2014 to every response generated by your app. This sort of cross- cutting concern is perfect for middleware. You can use the Use extension method to intercept every request, set the response header, and then execute the rest of the middleware pipeline. No matter what response the pipeline generates, whether it\u2019s a static \ufb01le, an error, or a Razor Page, the response will always have the security header.\u200c<\/p>\n
Listing 31.4 shows a robust way to achieve this. When the middleware receives a request, it registers a callback that runs before Kestrel starts sending the response back to the browser. It then calls next() to run the rest of the middleware pipeline. When the pipeline generates a response, likely in some later middleware, Kestrel executes the callback and adds the header. This approach ensures that the header isn\u2019t accidentally removed by other middleware in the pipeline and also ensures that you don\u2019t try to modify the headers after the response has started streaming to the browser.<\/p>\n
Listing 31.4 Adding headers to a response with the Use extension<\/p>\n
app.Use(async (HttpContext context, Func<Task> next) => \u2776\n{\ncontext.Response.OnStarting(() => \u2777\n{\ncontext.Response.Headers["X-Content-Type-Options"] = "nosniff"; \u2778\nreturn Task.CompletedTask; \u2779\n});\nawait next(); \u277a\n}\napp.UseStaticFiles(); \u277b\napp.UseRouting(); \u277b\napp.MapRazorPages \u277b<\/code><\/pre>\n\u2776 Adds the middleware at the start of the pipeline
\n\u2777 Sets a function that runs before the response is sent to the browser
\n\u2778 Adds the header to the response for added protection against XSS attacks
\n\u2779 The function passed to OnStarting must return a Task.
\n\u277a Invokes the rest of the middleware pipeline
\n\u277b No matter what response is generated, it\u2019ll have the security header added.<\/p>\n
Simple cross-cutting middleware like the security header example is common, but it can quickly clutter your Program.cs con\ufb01guration and make it di\ufb03cult to understand the pipeline at a glance. Instead, it\u2019s common to encapsulate your middleware in a class that\u2019s functionally equivalent to the Use extension but that can be easily tested and reused.<\/p>\n
31.1.4 Building a custom middleware component\u200c<\/h3>\n
Creating middleware with the Use extension, as you did in listings 31.3 and 31.4, is convenient, but it\u2019s not easy to test, and you\u2019re somewhat limited in what you can do. For example, you can\u2019t easily use DI to inject scoped services inside these basic middleware components. Normally, rather than call the Use extension directly, you\u2019ll encapsulate your middleware into a class that\u2019s functionally equivalent.<\/p>\n
Custom middleware components don\u2019t have to derive from a speci\ufb01c base class or implement an interface, but they have a certain shape, as shown in listing 31.5. ASP.NET Core uses re\ufb02ection to execute the method at runtime. Middleware classes should have a constructor that takes a RequestDelegate object, which represents the rest of the middleware pipeline, and they should have an Invoke function with a signature similar to\u200c<\/p>\n
public Task Invoke(HttpContext context);<\/code><\/pre>\nThe Invoke() function is equivalent to the lambda function from the Use extension, and it is called when a request is received. The following listing shows how you could convert the headers middleware from listing 31.4 into a standalone middleware class.<\/p>\n
Listing 31.5 Adding headers to a Response using a custom middleware component<\/p>\n
\npublic class HeadersMiddleware\n{\nprivate readonly RequestDelegate _next; \u2776\npublic HeadersMiddleware(RequestDelegate next) \u2776\n{ \u2776\n_next = next; \u2776\n} \u2776\npublic async Task Invoke(HttpContext context) \u2777\n{\ncontext.Response.OnStarting(() => \u2778\n{ \u2778\ncontext.Response.Headers["X-Content-Type-Options"] = \u2778\n"nosniff"; \u2778\nreturn Task.CompletedTask; \u2778\n}); \u2778\nawait _next(context); \u2779\n}\n}<\/code><\/pre>\n\u2776 The RequestDelegate represents the rest of the middleware pipeline.
\n\u2777 The Invoke method is called with HttpContext when a request is received.
\n\u2778 Adds the header to the response as before
\n\u2779 Invokes the rest of the middleware pipeline. Note that you must pass in the
\nprovided HttpContext.<\/p>\n
NOTE<\/b> Using this shape approach makes the middleware more \ufb02exible. In particular, it means you can easily use DI to inject services into the Invoke method. This wouldn\u2019t be possible if the Invoke method were an overridden base class method or an interface. However, if you prefer, you can implement the IMiddleware interface, which de\ufb01nes the basic Invoke method.<\/p>\n
This middleware is e\ufb00ectively identical to the example in listing 31.4, but it\u2019s encapsulated in a class called HeadersMiddleware. You can add this middleware to your app in Startup.Configure by calling<\/p>\n
app.UseMiddleware<HeadersMiddleware>();<\/code><\/pre>\nA common pattern is to create helper extension methods to make it easy to consume your extension method from<\/p>\n
Program.cs (so that IntelliSense reveals it as an option on the WebApplication instance). The following listing shows how you could create a simple extension method for HeadersMiddleware.<\/p>\n
Listing 31.6 Creating an extension method to expose HeadersMiddleware<\/p>\n
public static class MiddlewareExtensions\n{\npublic static IApplicationBuilder UseSecurityHeaders( \u2776\nthis IApplicationBuilder app) \u2776\n{\nreturn app.UseMiddleware<HeadersMiddleware>(); \u2777\n}\n}<\/code><\/pre>\n\u2776 By convention, the extension method should return an IApplicationBuilder to allow chaining.
\n\u2777 Adds the middleware to the pipeline<\/p>\n
With this extension method, you can now add the headers middleware to your app using<\/p>\n
app.UseSecurityHeaders();<\/code><\/pre>\nTIP<\/b> My SecurityHeaders NuGet package makes it easy to add security headers using middleware without having to write your own. The package provides a \ufb02uent interface for adding the recommended security headers to your app. You can \ufb01nd instructions on how to install it at http:\/\/mng.bz\/JggK<\/a>.<\/p>\nListing 31.5 is a simple example, but you can create middleware for many purposes. In some cases you may need to use DI to inject services and use them to handle a request. You can inject singleton services into the constructor of your middleware component, or you can inject services with any lifetime into the Invoke method of your middleware, as demonstrated in the following listing.<\/p>\n
Listing 31.7 Using DI in middleware components<\/p>\n
public class ExampleMiddleware\n{\nprivate readonly RequestDelegate _next;\nprivate readonly ServiceA _a; \u2776\npublic HeadersMiddleware(RequestDelegate next, ServiceA a) \u2776\n{ \u2776\n_next = next; \u2776\n_a = a; \u2776\n}\npublic async Task Invoke(\nHttpContext context, ServiceB b, ServiceC c) \u2777\n{\n\/\/ use services a, b, and c\n\/\/ and\/or call _next.Invoke(context);\n}\n}<\/code><\/pre>\n\u2776 You can inject additional services in the constructor. These must be singletons.
\n\u2777 You can inject services into the Invoke method. These may have any lifetime.<\/p>\n
WARNING<\/b> ASP.NET Core creates the middleware only once for the lifetime of your app, so any dependencies injected in the constructor must be singletons. If you need to use scoped or transient dependencies, inject them into the Invoke method.<\/p>\n
In addition to cross-cutting concerns, a good use for middleware is creating simple handlers with as few dependencies as possible that respond to a \ufb01xed URL, similar to the Use extension method you learned about in section 31.1.3. These simple handlers can be dropped into multiple applications, regardless of how the app\u2019s routing is con\ufb01gured.<\/p>\n
So-called well-known Uniform Resource Identi\ufb01ers (URIs) are a good use case for these simple middleware handlers, such as the security.txt well-known URI (https:\/\/www.rfc<\/a>- editor.org\/rfc\/rfc9116) and the OpenID Connect URIs (http:\/\/mng.bz\/wvj2<\/a>). These handlers always respond to a single path, so they can neatly encapsulate all the logic without risk of interfering with any other routing con\ufb01guration.\u200c<\/p>\nListing 31.8 shows a simple example of a security.txt handler implemented as middleware. It always responds to the well- known path with a \ufb01xed value and is easy to add to any application by calling app.UseMiddleware.<\/p>\nListing 31.8 A Security.txt handler implemented as middleware<\/p>\n
public class SecurityTxtHandler\n{\nprivate readonly RequestDelegate _next;\npublic SecurityTxtHandler(RequestDelegate next)\n{\n_next = next;\n}\npublic Task Invoke(HttpContext context)\n{\nvar path = context.Request.Path;\nif(path.StartsWithSegments("\/.well-known\/security.txt")) \u2776\n{\ncontext.Response.ContentType = "text\/plain"; \u2777\nreturn context.Response.WriteAsync( \u2777\n"Contact: mailto:security@example.com"); \u2777\n}\nreturn _next.Invoke(context); \u2778\n}\n}<\/code><\/pre>\n\u2776 The middleware looks for a fixed, well-known path.
\n\u2777 If the path is matched, the middleware returns a response.
\n\u2778 If the path didn\u2019t match, the next middleware in the pipeline is called.<\/p>\n
That covers pretty much everything you need to start building your own middleware components. By encapsulating your middleware in custom classes, you can easily test their behavior or distribute them in NuGet packages, so I strongly recommend taking this approach. Apart from anything else, it will make Program.cs \ufb01le less cluttered and easier to understand.<\/p>\n
31.1.5 Converting middleware into endpoint routing endpoints\u200c<\/h3>\n
In this section you\u2019ll learn how you can take the custom middleware you created in section 31.1.2 and convert it to a simple middleware endpoint that integrates into the endpoint routing system. Then you can take advantage of features such as routing and authorization.<\/p>\n
In section 31.1.2 I described creating a simple ping-pong endpoint, using the Map and Run extension methods, that returns a plain-text pong response whenever a \/ping request is received by branching the middleware pipeline.\u200c\u200cThis is \ufb01ne because it\u2019s so simple, but what if you have more complex requirements?<\/p>\n
Consider a basic enhancement of this ping-pong example. How would you add authorization to the request? The AuthorizationMiddleware looks for metadata on endpoints like Razor Pages or minimal APIs to see whether there\u2019s any authorization metadata, but it doesn\u2019t know how to work with the ping-pong Map extension.<\/p>\n
Similarly, what if you wanted to use more complex routing? Maybe you want to be able to call \/ping\/3 and have your ping-pong middleware reply pong-pong-pong. (No, I can\u2019t think why you would either!) You now have to try to parse that integer from the URL, make sure it\u2019s valid, and so on.That\u2019s sounding like a lot more work and seems to be a clear indicator you should have created a minimal API endpoint using endpoint routing!<\/p>\n
For our simple ping-pong endpoint, that wouldn\u2019t be hard to do, but what if you have a more complex middleware component that you don\u2019t want to rewrite completely? Is there some way to convert the middleware to an endpoint?<\/p>\n
Let\u2019s imagine that you need to apply authorization to the simple ping-pong endpoint you created in section 31.1.2. This is much easier to achieve with endpoint routing than simple middleware branches like Map or Use, but let\u2019s imagine you want to stick to using middleware instead of a traditional minimal API endpoint. The \ufb01rst step is creating a standalone middleware component for the functionality,using the approach you saw in section 31.1.4, as shown in the following listing.<\/p>\n
Listing 31.9 The PingPongMiddleware implemented as a middleware component<\/p>\n
public class PingPongMiddleware\n{\npublic PingPongMiddleware(RequestDelegate next) \u2776\n{\n}\npublic async Task Invoke(HttpContext context) \u2777\n{\ncontext.Response.ContentType = "text\/plain"; \u2778\nawait context.Response.WriteAsync("pong"); \u2778\n}\n}<\/code><\/pre>\n\u2776 Even though it isn\u2019t used in this case, you must inject a RequestDelegate in the
\nconstructor.
\n\u2777 Invoke is called to execute the middleware.
\n\u2778 The middleware always returns a \u201cpong\u201d response.<\/p>\n
Note that this middleware always returns a "pong" response regardless of the request URL; we will con\ufb01gure the "\/ping" path later. We can use this class to convert a middleware pipeline from the branching version shown in \ufb01gure 31.1, to the endpoint version shown in \ufb01gure 31.4.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3104.jpg\")
<\/p>\n
Figure 31.4 Endpoint routing separates the selection of an endpoint from the execution of an endpoint. The routing middleware selects an endpoint based on the incoming request and exposes metadata about the endpoint. Middleware placed before the endpoint middleware can act based on the selected endpoint, such as short-circuiting unauthorized requests. If the request is authorized, the endpoint middleware executes the selected endpoint and generates a response.<\/p>\n
Converting the ping-pong middleware to an endpoint doesn\u2019t require any changes to the middleware itself. Instead, you need to create a mini middleware pipeline containing only your ping-pong middleware.<\/p>\n
TIP<\/b> Converting response-generating middleware to an endpoint essentially requires converting it to its own mini pipeline, so you can even include additional middleware in the endpoint pipeline if you wish.<\/p>\n
To create the mini pipeline, you call CreateApplicationBuilder() on IEndpointRouteBuilder instance, which creates a new IApplicationBuilder. There are two ways to access the IEndpointRouteBuilder: call UseEndpoints(endpoints =>{}) and use the endpoints variable or explicitly cast WebApplication to IEndpointRouteBuilder.\u200c<\/p>\n
NOTE<\/b> Although WebApplication implements IEndpointRouteBuilder, it deliberately hides the advanced CreateApplicationBuilder() method from you! This should be a good indication that you\u2019re in advanced territory and should probably consider using minimal API endpoints instead.<\/p>\n
In the following listing, we create a new IApplicationBuilder, add the middleware that makes up the endpoint to it, and then call Build() to create the pipeline. Once you have a pipeline, you can associate it with a given route by calling Map() on the IEndpointRouteBuilder instance and passing in a route template.<\/p>\n
Listing 31.10 Mapping the ping-pong endpoint in UseEndpoints<\/p>\n
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nWebApplication app = builder.Build();\napp.UseRouting();\napp.UseAuthentication();\napp.UseAuthorization();\nvar endpoint = ((IEndpointRouteBuilder)app) \u2776\n.CreateApplicationBuilder() \u2777\n.UseMiddleware<PingPongMiddleware>() \u2778\n.Build(); \u2778\napp.Map("\/ping", endpoint); \u2779\napp.MapRazorPages();\napp.MapHealthChecks("\/healthz");\napp.Run();<\/code><\/pre>\n\u2776 Casts the WebApplication to IEndpointRouteBuilder so you can call
\nCreateApplicationBuilider
\n\u2777 Creates a miniature, standalone IApplicationBuilder to build your endpoint
\n\u2778 Adds the middleware and builds the final endpoint. This is executed when the
\nendpoint is executed.
\n\u2779 Maps the new endpoint with the route template \u201c\/ping\u201d<\/p>\n
TIP<\/b> Note that the Map() function on IEndpointRouteBuilder creates a new endpoint (consisting of your mini-pipeline) with an associated route.<\/p>\n
Although it has the same name, this is conceptually di\ufb00erent from the Map function on IApplicationBuilder from section 31.1.2, which is used to branch the middleware pipeline. It is analogous to the MapGet (and kin) methods you use to create minimal API endpoints.<\/p>\n
As is common with ASP.NET Core, you can extract this somewhat-verbose functionality into an extension method to make your endpoint easier to read and discover. The following listing extracts the code to create an endpoint from listing 31.10 into a separate class, taking the route template to use as a method parameter.<\/p>\n
Listing 31.11 An extension method for using the PingPongMiddleware as an endpoint<\/p>\n
public static class EndpointRouteBuilderExtensions\n{\npublic static IEndpointConventionBuilder MapPingPong( \u2776\nthis IEndpointRouteBuilder endpoints, \u2776\nstring route) \u2777\n{\nvar pipeline = endpoints\n.CreateApplicationBuilder() \u2778\n.UseMiddleware<PingPongMiddleware>() \u2778\n.Build(); \u2778\nreturn endpoints \u2779\n.Map(route, pipeline) \u2779\n.RequireAuthorization(); \u277a\n}\n}<\/code><\/pre>\n\u2776 Creates an extension method for registering the PingPongMiddleware as an endpoint
\n\u2777 Allows the caller to pass in a route template for the endpoint
\n\u2778 Creates the endpoint pipeline
\n\u2779 Adds the new endpoint to the provided endpoint collection, using the provide route template
\n\u277a You can add additional metadata here directly, or the caller can add metadata themselves.<\/p>\n
Now that you have an extension method, MapPingPong(), you can update your mapping code to be simpler and easier to understand:<\/p>\n
app.MapPingPong("\/ping"); \napp.MapRazorPages(); app.MapHealthChecks("\/healthz");<\/code><\/pre>\nCongratulations\u2014you\u2019ve created your \ufb01rst custom endpoint from middleware! By turning the middleware into an endpoint, you can now add extra metadata, as shown in listing 31.11. Your middleware is hooked into the endpoint routing system and bene\ufb01ts from everything it o\ufb00ers.<\/p>\n
The example in listing 31.11 used a basic route template, "\/ping", but you can also use templates that contain route parameters, such as "\/ping\/{count}", as you would with minimal APIs. The big di\ufb00erence is that you don\u2019t get the bene\ufb01ts of model binding that you get from minimal APIs, and it clearly takes more e\ufb00ort than using minimal APIs!<\/p>\n
TIP<\/b> For examples of how to access the route data from your middleware, as well as best-practice advice, see my blog entry titled \u201cAccessing route values in endpoint middleware in ASP.NET Core 3.0\u201d at http:\/\/mng.bz\/4ZRj<\/a>.<\/p>\nConverting existing middleware like PingPongMiddleware to work with endpoint routing can be useful when you have already implemented that middleware, but it\u2019s a lot of boilerplate to write if you want to create a new simple endpoint. In almost all cases you should use minimal API endpoints instead. But if you ever \ufb01nd yourself needing to reuse some existing middleware as an endpoint, now you know how!<\/p>\n
In the next section we\u2019ll move away from the middleware pipeline and look at how to handle a common con\ufb01guration requirement: using DI services to build a strongly typed IOptions objects.\u200c<\/p>\n
31.2 Using DI with OptionsBuilder and ICon\ufb01gureOptions\u200c<\/h2>\n
In this section I describe how to handle a common scenario: you want to use services registered in DI to con\ufb01gure IOptions objects. There are several ways to achieve this, but in this section I introduce the OptionsBuilder as one possible approach and highlight some of the other features it enables.<\/p>\nIn chapter 10 we discussed the ASP.NET Core con\ufb01guration system in depth. You saw how an IConfiguration object is built from multiple layers, where subsequent layers can add to or replace con\ufb01guration values from previous layers. Each layer is added by a con\ufb01guration provider, which reads values from a \ufb01le, from environment variables, from User Secrets, or from any number of possible locations.<\/p>\n
A common and encouraged practice is to bind your con\ufb01guration object to strongly typed IOptions objects, as you saw in chapter 10. Typically, you con\ufb01gure this binding in Program.cs by calling builder.Services.Configure<T>()<\/code> and providing an IConfiguration object or a con\ufb01guration section to bind.<\/p>\nFor example, to bind a strongly typed object called CurrencyOptions to the "Currencies" section of an IConfiguration object, you could use the following:<\/p>\n
builder.services.Configure<CurrencyOptions>( Configuration.GetSection("Currencies"));<\/code><\/pre>\nTIP<\/b> You can see an example of the CurrencyOptions type and the associated "Currencies" section of appsetttings.json in the source code for this chapter.<\/p>\n
This sets the properties of the CurrencyOptions object, based on the values in the "Currencies" section of your IConfiguration object. Simple binding like this is common, but sometimes you might not want to rely on con\ufb01guring your IOptions<T><\/code> objects via the con\ufb01guration system; you might want to con\ufb01gure them in code instead.The IOptions pattern requires only that you con\ufb01gure a strongly typed object before it\u2019s injected into a dependent service; it doesn\u2019t mandate that you have to bind it to an IConfiguration section.<\/p>\nTIP<\/b> Technically, even if you don\u2019t con\ufb01gure an IOptions at all, you can still inject it into your services. In that case, the T object is simply created using the default constructor.<\/p>\nThe Configure() method has an additional overload that takes a lambda function. The framework executes the lambda function to con\ufb01gure the CurrencyOptions object when it is injected using DI. The following listing shows an example that uses a lambda function to set the Currencies property on a con\ufb01gured CurrencyOptions object to a \ufb01xed array of strings.\u200c\u200c<\/p>\nListing 31.12 Con\ufb01guring an IOptions object using a lambda function<\/p>\n
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nbuilder.Services.Configure<CurrencyOptions>( \u2776\nbuilder.Configuration.GetSection("Currencies")); \u2776\nbuilder.services.Configure<CurrencyOptions>(options => \u2777\noptions.Currencies = new string[] { "GBP", "USD"}); \u2777\nWebApplication app = builder.Build();\napp.MapGet("\/", (IOptions<CurrencyOptions> opts) => opts.Value); \u2778\napp.Run();<\/code><\/pre>\n\u2776 Configures the IOptions object by binding to an IConfiguration section
\n\u2777 Configures the IOptions object by executing a lambda function
\n\u2778 The injected IOptions value is built by first binding to configuration and then applying the lambda.<\/p>\n
Each call to Configure<T>()<\/code>, both the binding to IConfiguration and the lambda function, adds another con\ufb01guration step to the CurrencyOptions object. When the DI container \ufb01rst requires an instance of IOptions, the steps run in turn, as shown in \ufb01gure 31.5.<\/p>\n![\"alt](\"\/images\/aspnetcoreinaction\/3105.jpg\")
<\/p>\n
Figure 31.5 Con\ufb01guring a CurrencyOptions object. When the DI container needs an IOptions<> instance of a strongly typed object, the container creates the object and then uses each of the registered Configure() methods to set the object\u2019s properties.<\/p>\n
In the previous code snippet, you set the Currencies property to a static array of strings in a lambda function. But what if you don\u2019t know the correct values ahead of time? You might need to load the available currencies from a database or from some remote service, such as an ICurrencyProvider.<\/p>\n
This situation, in which you need a con\ufb01gured service to con\ufb01gure your IOptions<T><\/code>, is potentially hard to resolve. Remember that you declared your IOptions<T><\/code> con\ufb01guration as part of your app\u2019s DI con\ufb01guration. But if you need to resolve a service from DI to con\ufb01gure the IOptions object, you\u2019re stuck with a chicken-and-egg problem: how can you access a service from the DI container before you\u2019ve \ufb01nished con\ufb01guring the DI container?<\/p>\nThis circular problem has several potential solutions, but the easiest approach is to use an alternative API for con\ufb01guring IOptions instances, using the OptionsBuilder type. This type is e\ufb00ectively a wrapper around some of the core IOptions interfaces, but it often results in a terser and more convenient syntax to the approach you\u2019ve seen so far.\u200c<\/p>\nTIP<\/b> Another helpful feature of OptionsBuilder is adding validation to your IOptions objects. This ensures that your con\ufb01guration is loaded and bound correctly on app startup so that you don\u2019t have any typos in your con\ufb01guration section names, for example. You can read more about adding validation to your IOptions objects on my blog at http:\/\/mng.bz\/qrjJ<\/a>.<\/p>\nThe following listing shows the equivalent of listing 31.12 but using OptionsBuilder<T><\/code> instead. You create an OptionsBuilder<T><\/code> instance by calling AddOptions<T> ()<\/code>, and then chain additional methods such as BindConfiguration() and Configure() to con\ufb01gure your \ufb01nal IOptions<T><\/code> object, building up layers of options con\ufb01guration, as shown previously in \ufb01gure 31.5.\u200c<\/p>\nListing 31.13 Con\ufb01guring an IOptions<T><\/code> object using OptionsBuilder<T><\/code><\/p>\nWebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nbuilder.Services\n.AddOptions<CurrencyOptions>() \u2776\n.BindConfiguration("Currencies") \u2777\n.Configure(opts => \u2778\nopts.Currencies = new string[] { "GBP", "USD"}); \u2778\nWebApplication app = builder.Build();\napp.MapGet("\/", (IOptions<CurrencyOptions> opts) => opts.Value);\napp.Run();<\/code><\/pre>\n\u2776 Creates an OptionsBuilder object
\n\u2777 Binds to the Currencies section of the IConfiguration
\n\u2778 Configures the IOptions object by executing a lambda function<\/p>\nYou\u2019ve seen the builder pattern many times throughout the book, and the pattern in this case is no di\ufb00erent. The builder exposes methods that you can chain together \ufb02uently. One of the bene\ufb01ts of the builder pattern is that it\u2019s easy to discover all the methods it exposes. In this case, if you explore the type in your integrated development environment (IDE), you may notice that OptionsBuilder<T><\/code> exposes multiple Con\ufb01gure overloads, such as<\/p>\n\u2022 Configure(Action<T,TDep> config);<\/p>\n\u2022 Configure<TDep1,TDep2>(Action<T, TDep1, TDep2> config);<\/p>\n
\u2022 Configure<TDep1,TDep2,TDep3> (Action<T,TDep1,TDep2,TDep3> config);<\/p>\n
These methods allow you to specify dependencies that are automatically retrieved from the DI container and passed to the con\ufb01g action when the IOptions object is fetched from DI, as shown in \ufb01gure 31.6. Five overloads for Configure allow you to inject dependencies, allowing you to inject up to \ufb01ve dependencies with these methods.<\/p>\n![\"alt](\"\/images\/aspnetcoreinaction\/3106-1.jpg\")
\n![\"alt](\"\/images\/aspnetcoreinaction\/3106-2.jpg\")
<\/p>\n
Figure 31.6 Using OptionsBuilder to build an IOptions object. Dependencies that are requested via the Configure methods are automatically retrieved from the DI container and used to execute the lambda function.<\/p>\nUsing this pattern, we can update the code from listing 31.13 to use the ICurrencyProvider whenever our app needs to create the CurrencyOptions object. We can register the service in the DI container and know that the DI will take<\/p>\n
care of providing it to the lambda function at runtime, as shown in the following listing.<\/p>\n
Listing 31.14 Using a DI service<\/p>\n
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nbuilder.Services\n.AddOptions<CurrencyOptions>()\n.BindConfiguration("Currencies")\n.Configure<ICurrencyProvider>((opts, service) => \u2776\nopts.Currencies = service.GetCurrencies()); \u2776\nbuilder.Services.AddSingleton<ICurrencyProvider, CurrencyProvider>(); \u2777\nWebApplication app = builder.Build();\napp.MapGet("\/", (IOptions<CurrencyOptions> opts) => opts.Value); \u2778\napp.Run();<\/code><\/pre>\n\u2776 Configures the Ioptions object using a service from DI
\n\u2777 Registers the service with the DI container
\n\u2778 Retrieves the IOptions object, which retrieves the service from DI and runs the lambda method<\/p>\n
With the con\ufb01guration in listing 31.14, when the IOptions<CurrencyOptions><\/code> is \ufb01rst injected into the minimal API endpoint, the IOptions<CurrencyOptions><\/code> object is built as described by the OptionsBuilder. First, the "Currencies" section of the app IConfiguration is bound to a new CurrencyOptions object. Then the ICurrencyProvider is retrieved from DI and passed to the Configure<TDep><\/code> lambda, along with the options object. Finally, the IOptions object is injected into the endpoint.<\/p>\nWARNING<\/b> You must inject only singleton services using Configure<TDeps><\/code> methods. If you try to inject a scoped service, such as a DbContext, you will get an error in development warning you about a captive dependency. I describe how to work around this on my blog at http:\/\/mng.bz\/7Dve<\/a>.<\/p>\nThe OptionsBuilder<T><\/code> is a convenient way to con\ufb01gure your IOptions objects using dependencies, but you can use an alternative approach: implementing the IConfigureOptions<T><\/code> interface. You implement this interface in a con\ufb01guration class and use it to con\ufb01gure the IOptions object in any way you need, as shown in the following listing. This class can use DI, so you can easily use any other required services.<\/p>\nListing 31.15 Implementing IConfigureOptions<T><\/code> to con\ufb01gure an options object<\/p>\npublic class ConfigureCurrencyOptions : IConfigureOptions<CurrencyOptions>\n{\nprivate readonly ICurrencyProvider _currencyProvider; \u2776\npublic ConfigureCurrencyOptions(ICurrencyProvider currencyProvider)\n{\n_currencyProvider = currencyProvider; \u2776\n}\npublic void Configure(CurrencyOptions options) \u2777\n{\noptions.Currencies = _currencyProvider.GetCurrencies(); \u2778\n}\n}<\/code><\/pre>\n\u2776 You can inject services that are available only after the DI is completely configured.
\n\u2777 Configure is called when an instance of IOptions<CurrencyOptions><\/code> is required.
\n\u2778 Uses the injected service to load the values<\/p>\nAll that remains is to register the implementation in the DI container. As always, order is important, so if you want ConfigureCurrencyOptions to run after binding to con\ufb01guration, you must add it after con\ufb01guring your OptionsBuilder<T><\/code>:<\/p>\nbuilder.Services.AddOptions<CurrencyOptions>()\n.BindConfiguration("Currencies");\nbuilder.AddSingleton\n<IConfigureOptions<CurrencyOptions>, ConfigureCurrencyOptions>();<\/code><\/pre>\nTIP<\/b> The order in which you con\ufb01gure your options matters. If you want to always run your con\ufb01guration last, after all other con\ufb01guration methods, you can use the PostConfigure() method on OptionsBuilder, or the IPostConfigureOptions interface. You can read more about this approach on my blog at http:\/\/mng.bz\/mVj4<\/a>.\u200c\u200c<\/p>\nWith this con\ufb01guration, when IOptions is injected into an endpoint or service, the CurrencyOptions object is \ufb01rst bound to the "Currencies" section of your IConfiguration and then con\ufb01gured by the ConfigureCurrencyOptions class.\u200c<\/p>\nWARNING<\/b> The CurrencyConfigureOptions object is registered as a singleton, so it will capture any injected services of scoped or transient lifetimes.<\/p>\n
Whether you use the OptionsBuilder or the IConfigureOptions approach, you need to register the ICurrencyProvider dependency with the DI container. In the sample code for this chapter, I created a simple CurrencyProvider service and registered it with the DI container using\u200c\u200c<\/p>\nbuilder.Services.AddSingleton<ICurrencyProvider, CurrencyProvider>();<\/code><\/pre>\nAs your app grows and you add extra features and services, you\u2019ll probably \ufb01nd yourself writing more of these simple DI registrations, where you register a Service that implements IService. The built-in ASP.NET Core DI container requires you to explicitly register each of these services manually. If you \ufb01nd this requirement frustrating, it may be time to look at third-party DI containers that can take care of some of the boilerplate for you.<\/p>\n
31.3 Using a third-party dependency injection container\u200c<\/h2>\n
In this section I show you how to replace the default DI container with a third-party alternative, Lamar. Third-party containers often provide additional features compared with the built-in container, such as assembly scanning, automatic service registration, and property injection. Replacing the built-in container can also be useful when you\u2019re porting an existing app that uses a third-party DI container to ASP.NET Core.<\/p>\n
The .NET community had used DI containers for years before ASP.NET Core decided to include a built-in one. The ASP.NET Core team wanted a way to use DI in their own framework libraries, and they wanted to create a common abstraction1 that allows you to replace the built-in container with your favorite third-party alternative, such as Autofac, StructureMap\/Lamar, Ninject, Simple Injector, or Unity.<\/p>\n
The built-in container is intentionally limited in the features it provides, and realistically, it won\u2019t be getting many more. By contrast, third-party containers can provide a host of extra features. These are some of the features available in Lamar (https:\/\/jasperfx.github.io\/lamar\/guide\/ioc<\/a>), the spiritual successor to StructureMap (https:\/\/structuremap.github.io<\/a>):<\/p>\n\u2022 Assembly scanning for interface\/implementation pairs based on conventions<\/p>\n
\u2022 Automatic concrete class registration Property injection and constructor selection<\/p>\n
\u2022 Automatic Lazy\/Func resolution<\/p>\n\u2022 Debugging\/testing tools for viewing inside your container<\/p>\n
None of these features is a requirement for getting an application up and running, so using the built-in container makes a lot of sense if you\u2019re building a small app or are new to DI containers in general. But if at some unde\ufb01ned tipping point, the simplicity of the built-in container becomes too much of a burden, it may be worth replacing.<\/p>\n
TIP<\/b> A middle-of-the-road approach is to use the Scrutor NuGet package, which adds some features to the built-in DI container without replacing it. For an introduction and examples, see my blog post, \u201cUsing Scrutor to automatically register your services with the ASP.NET Core DI container\u201d at http:\/\/mng.bz\/MX7B<\/a>.<\/p>\nIn this section I show how you can con\ufb01gure an ASP.NET Core app to use Lamar for dependency resolution. It won\u2019t be a complex example or an in-depth discussion of Lamar itself.Instead, I\u2019ll cover the bare minimum to get you up and running.<\/p>\n
Whichever third-party container you choose to install in an existing app, the overall process is pretty much the same:<\/p>\n
\n- \n
Install the container NuGet package.<\/p>\n<\/li>\n
- \n
Register the third-party container with WebApplicationBuilder in Program.cs.<\/p>\n<\/li>\n
- \n
Con\ufb01gure the third-party container to register your services.<\/p>\n<\/li>\n<\/ol>\n
Most of the major .NET DI containers include adapters and extension methods to hook easily into your ASP.NET Core app. For details, it\u2019s worth consulting the speci\ufb01c guidance for the container you\u2019re using. For Lamar, the process looks like this:<\/p>\n
\n- \n
Install the Lamar.Microsoft.DependencyInjection NuGet package using the NuGet package manager, by running dotnet add package<\/p>\n
dotnet add package Lamar.Microsoft.DependencyInjection<\/code><\/pre>\nor by adding a to your .csproj \ufb01le:<\/p>\n<PackageReference \nInclude="Lamar.Microsoft.DependencyInjection" Version="8.1.0" \/><\/code><\/pre>\n<\/li>\n- \n
Call UseLamar() on WebApplicationBuilder.Host in Program.cs:<\/p>\n
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nbuilder.Host.UseLamar(services => {})\nWebApplication app = builder.Build();<\/code><\/pre>\n<\/li>\n- \n
Con\ufb01gure the Lamar ServiceRegistry in the lambda method passed to UseLamar(), as shown in the following listing. This is a basic con\ufb01guration, but you can see a more complex example in the source code for this chapter.<\/p>\n<\/li>\n<\/ol>\n
Listing 31.16 Con\ufb01guring Lamar as a third-party DI container<\/p>\n
builder.Host.UseLamar(services => \u2776\n{\nservices.AddAuthorization(); \u2777\nservices.AddControllers() \u2777\n.AddControllersAsServices(); \u2778\nservices.Scan(_ => { \u2779\n_.AssemblyContainingType(typeof(Program)); \u2779\n_.WithDefaultConventions(); \u2779\n}); \u2779\n}<\/code><\/pre>\n\u2776 Configures your services in UseLamar() instead of on builder.Services
\n\u2777 You can (and should) add ASP.NET Core framework services to the
\nServiceRegistry, as usual.
\n\u2778 Required so that Lamar is used to build your web API controllers
\n\u2779 Lamar can automatically scan your assemblies for services to register.<\/p>\n
In this example I\u2019ve used the default conventions to register services. This automatically registers concrete classes and services that are named following expected conventions (for example, Service implements IService). You can change these conventions or add other registrations in the UseLamar() lambda.<\/p>\n
The ServiceRegistry passed into UseLamar() implements IServiceCollection, which means you can use all the built-in extension methods, such as AddControllers() and AddAuthorization(), to add framework services to your container.\u200c<\/p>\n
WARNING<\/b> If you\u2019re using DI in your Model-View-Controller (MVC) controllers (almost certainly!), and you register those dependencies with Lamar rather than the built-in container, you may need to call AddControllersAsServices(), as shown in listing 31.16. This is due to an implementation detail in the way your MVC controllers are created by the framework. For details, see my blog entry titled \u201cController activation and dependency injection in ASP.NET Core MVC\u201d at http:\/\/mng.bz\/aogm<\/a>.<\/p>\nWith this con\ufb01guration in place, whenever your app needs to create a service, it will request it from the Lamar container, which will create the dependency tree for the class and create an instance. This example doesn\u2019t show o\ufb00 the power of Lamar, so be sure to check out the documentation (https:\/\/jasperfx.github.io\/lamar<\/a>) and the associated source code for this chapter for more examples. Even in modest-size applications, Lamar can greatly simplify your service registration code, but its party trick is showing all the services you have registered and any associated issues.<\/p>\nTIP<\/b> Third-party containers typically add con\ufb01guration approaches but don\u2019t change any of the fundamentals of how DI works in ASP.NET Core. All the techniques you\u2019ve seen in this book will work whether you\u2019re using the built-in container or a third-party container, so you can use the IConfigureOptions approach in section 31.2, for example, regardless of which container you choose.<\/p>\nThat brings us to the end of this chapter on advanced con\ufb01guration. In this chapter I focused on some of the core components of any ASP.NET Core app: middleware, con\ufb01guration, and DI. In the next chapter you\u2019ll learn about more custom components, with a focus on Razor Pages and web API controllers.\u200c<\/p>\n
Summary<\/h2>\n
Use the Run extension method to create middleware components that always return a response. You should always place the Run extension at the end of a middleware pipeline or branch, as middleware placed after it will never execute.<\/p>\n
You can create branches in the middleware pipeline with the Map extension. If an incoming request matches the speci\ufb01ed path pre\ufb01x, the request will execute the pipeline branch; otherwise, it will execute the trunk.<\/p>\n
When the Map extension matches a request path segment, it removes the segment from the request\u2019s HttpContext.Path and moves it to the PathBase property. This ensures that routing in branches works correctly.<\/p>\n
You can use the Use extension method to create generalized middleware components that can generate a response, modify the request, or pass the request on to subsequent middleware in the pipeline. This is useful for cross-cutting concerns, like adding a header to all responses.<\/p>\n
You can encapsulate middleware in a reusable class. The class should take a RequestDelegate object in the constructor and should have a public Invoke() method that takes an HttpContext and returns a Task. To call the next middleware component in the pipeline, invoke the RequestDelegate with the provided HttpContext.<\/p>\n
To create endpoints that generate a response, build a miniature pipeline containing the response- generating middleware, and call endpoints.Map(route, pipeline). Endpoint routing will be used to map incoming requests to your endpoint.<\/p>\n
You can con\ufb01gure IOptions<T><\/code> objects using a \ufb02uent builder interface. Call AddOptions<T>()<\/code> to create an OptionsBuilder<T><\/code> instance and then chain con\ufb01guration calls.<\/p>\nOptionsBuilder<T><\/code> allows easy access to dependencies for con\ufb01guration, as well as features such as validation.<\/p>\nYou can also use services from the DI container to con\ufb01gure an IOptions<T><\/code> object by creating a separate class that implements IConfigureOptions<T><\/code>. This class can use DI in the constructor and is used to lazily build a requested IOptions<T><\/code> object at runtime.<\/p>\nYou can replace the built-in DI container with a third-party container. Third-party containers often provide additional features, such as convention- based dependency registration, assembly scanning, and property injection.<\/p>\n
\n- Although the promotion of DI as a core practice has been applauded, this abstraction has seen some controversy. This post, titled \u201cWhat\u2019s wrong with the ASP.NET Core DI abstraction?\u201d, from one of the maintainers of the SimpleInjector DI library, describes many of the arguments and concerns: http:\/\/mng.bz\/yYAd<\/a>. You can also read more about the decisions at http:\/\/mng.bz\/6DnA<\/a>.<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"
31 Advanced con\ufb01guration of ASP.NET Core\u200c This chapter covers \u2022 Building custom middleware \u2022 Using dependency injection (DI) services in IOptions con\ufb01guration \u2022 Replacing the built-in DI container with a third-party container When you\u2019re building apps with ASP.NET Core, most of your creativity and specialization go into the services and models that make up your […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-633","post","type-post","status-publish","format-standard","hentry","category-csharp"],"_links":{"self":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts\/633","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=633"}],"version-history":[{"count":0,"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts\/633\/revisions"}],"wp:attachment":[{"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=633"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=633"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=633"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}