Docs improvements (#1024)

* Use the WebApplicationBuilder style

* Update snippets

* Update snippets

* typos

* Explain the difference between the filter types

* Update snippets

* typos, leftobvers, and update snippets

* Fix link, remove reference to JSON.NET, update snippets

* update snippets

* Update snippets

* typo, update snippets

* typos

* Update snippets

* typos

* Use snippets

Author: mauroservienti

README.md

@@ -31,22 +31,15 @@ To start using ServiceComposer, follow the outlined steps:
 <!-- snippet: sample-startup -->
 <a id='snippet-sample-startup'></a>
 ```cs
-public class Startup
-{
-    public void ConfigureServices(IServiceCollection services)
-    {
-        services.AddRouting();
-        services.AddViewModelComposition();
-    }
+var builder = WebApplication.CreateBuilder();
+builder.Services.AddRouting();
+builder.Services.AddViewModelComposition();
 
-    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
-    {
-        app.UseRouting();
-        app.UseEndpoints(builder => builder.MapCompositionHandlers());
-    }
-}
+var app = builder.Build();
+app.MapCompositionHandlers();
+app.Run();
 ```
-<sup><a href='/src/Snippets/BasicUsage/Startup.cs#L8-L23' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample-startup' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Snippets/BasicUsage/Startup.cs#L11-L19' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample-startup' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 - Add a new .NET 10 class library project named `Sales.ViewModelComposition`.

docs/README.md

@@ -43,13 +43,13 @@ MVC Action results support allows composition handlers to set custom response re
 
 ### Serialization
 
-By default, ServiceComposer serializes responses using the Newtonsoft JSON serializer. The built-in serialization support can be configured to serialize responses using a camel case or pascal case approach on a per-request basis by adding to the request an `Accept-Casing` custom HTTP header. For more information, refer to the [response serialization casing](response-serialization-casing.md) section. Or it's possible to take full control over the [response serialization settings on a case-by-case](custom-json-response-serialization-settings.md) by supplying at configuration time a customization function.
+By default, ServiceComposer serializes responses using `System.Text.Json`. The built-in serialization support can be configured to serialize responses using a camel case or pascal case approach on a per-request basis by adding to the request an `Accept-Casing` custom HTTP header. For more information, refer to the [response serialization casing](response-serialization-casing.md) section. Or it's possible to take full control over the [response serialization settings on a case-by-case](custom-json-response-serialization-settings.md) by supplying at configuration time a customization function.
 
 Starting with version 1.9.0, regular MVC Output Formatters can be used to serialize the response model and honor the `Accept` HTTP header set by clients. When using output formatters, the serialization casing is controlled by the formatter configuration and not by ServiceComposer. For more information on using output formatters refers to the [output formatters serialization section](output-formatters-serialization.md).
 
 ### Authentication and Authorization
 
-By leveraging ASP.NET Core 3.x Endpoints, ServiceComposer automatically supports authentication and authorization metadata attributes to express authentication and authorization requirements for routes. For more information, refer to the [Authentication and Authorization](authentication-authorization.md) section.
+By leveraging ASP.NET Core Endpoints, ServiceComposer automatically supports authentication and authorization metadata attributes to express authentication and authorization requirements for routes. For more information, refer to the [Authentication and Authorization](authentication-authorization.md) section.
 
 ### Endpoint filters
 

docs/action-results.md

@@ -34,12 +34,12 @@ Using MVC action results require enabling output formatters support:
 <!-- snippet: action-results-required-config -->
 <a id='snippet-action-results-required-config'></a>
 ```cs
-services.AddViewModelComposition(options =>
+builder.Services.AddViewModelComposition(options =>
 {
     options.ResponseSerialization.UseOutputFormatters = true;
 });
 ```
-<sup><a href='/src/Snippets/ActionResult/UseSetActionResultHandler.cs#L37-L42' title='Snippet source file'>snippet source</a> | <a href='#snippet-action-results-required-config' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Snippets/ActionResult/UseSetActionResultHandler.cs#L39-L44' title='Snippet source file'>snippet source</a> | <a href='#snippet-action-results-required-config' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 > [!NOTE]

docs/authentication-authorization.md

@@ -1,6 +1,6 @@
 # Authentication and Authorization
 
-By virtue of leveraging ASP.NET Core 3.x Endpoints ServiceComposer automatically supports authentication and authorization metadata attributes to express authentication and authorization requirements on routes. For example, it's possible to use the `Authorize` attribute to specify that a handler requires authorization. The authorization process is the regular ASP.NET Core 3.x process and no special configuration is needed to plugin ServiceComposer:
+By virtue of leveraging ASP.NET Core Endpoints, ServiceComposer automatically supports authentication and authorization metadata attributes to express authentication and authorization requirements on routes. For example, it's possible to use the `Authorize` attribute to specify that a handler requires authorization. The authorization process is the regular ASP.NET Core process and no special configuration is needed to plug in ServiceComposer:
 
 <!-- snippet: sample-handler-with-authorization -->
 <a id='snippet-sample-handler-with-authorization'></a>
@@ -17,3 +17,58 @@ public class SampleHandlerWithAuthorization : ICompositionRequestsHandler
 ```
 <sup><a href='/src/Snippets/SampleHandler/SampleHandler.cs#L10-L20' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample-handler-with-authorization' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
+
+## How it works
+
+ServiceComposer registers composition endpoints using ASP.NET Core's endpoint routing system. Any endpoint metadata attributes — `[Authorize]`, `[AllowAnonymous]`, `[RequireAuthorization]`, custom policy attributes — are collected from all handlers registered for a route and merged onto the composed endpoint.
+
+This means authorization is evaluated **before** composition handlers execute, as part of the standard ASP.NET Core middleware pipeline. If the request is not authorized, it is rejected and no composition handlers run.
+
+## Multiple handlers with different authorization requirements
+
+When multiple handlers are registered for the same route, their authorization metadata is merged. If any handler declares `[Authorize]`, the route requires authorization. The most restrictive combination applies.
+
+For example, if one handler requires an authenticated user and another requires a specific policy, both requirements are enforced:
+
+<!-- snippet: multiple-handlers-different-auth-requirements -->
+<a id='snippet-multiple-handlers-different-auth-requirements'></a>
+```cs
+public class SalesHandler : ICompositionRequestsHandler
+{
+    [Authorize]
+    [HttpGet("/product/{id}")]
+    public Task Handle(HttpRequest request) { /* ... */ return Task.CompletedTask; }
+}
+
+public class InventoryHandler : ICompositionRequestsHandler
+{
+    [Authorize(Policy = "WarehouseStaff")]
+    [HttpGet("/product/{id}")]
+    public Task Handle(HttpRequest request) { /* ... */ return Task.CompletedTask; }
+}
+```
+<sup><a href='/src/Snippets/Authentication/AuthenticationSnippets.cs#L11-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-multiple-handlers-different-auth-requirements' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Both `[Authorize]` and `[Authorize(Policy = "WarehouseStaff")]` are collected and applied to the route, so callers must satisfy both requirements.
+
+## Setup
+
+No special configuration is required beyond the standard ASP.NET Core authentication/authorization setup. Add authentication and authorization middleware before `app.MapCompositionHandlers()`:
+
+<!-- snippet: auth-middleware-setup -->
+<a id='snippet-auth-middleware-setup'></a>
+```cs
+var builder = WebApplication.CreateBuilder();
+builder.Services.AddViewModelComposition();
+builder.Services.AddAuthentication(); // configure your scheme here
+builder.Services.AddAuthorization();
+
+var app = builder.Build();
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapCompositionHandlers();
+app.Run();
+```
+<sup><a href='/src/Snippets/Authentication/AuthenticationSnippets.cs#L31-L42' title='Snippet source file'>snippet source</a> | <a href='#snippet-auth-middleware-setup' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->

docs/composition-filters.md

@@ -10,7 +10,7 @@ Composition requests filter can be defined as attributes or as classes.
 
 ### Defining composition requests filters as attributes
 
-Create an attribute that inherites from `CompositionRequestFilterAttribute` like in the following snippet:
+Create an attribute that inherits from `CompositionRequestFilterAttribute` like in the following snippet:
 
 <!-- snippet: composition-filter-attribute -->
 <a id='snippet-composition-filter-attribute'></a>
@@ -49,7 +49,7 @@ public class SampleHandler : ICompositionRequestsHandler
 
 ### Defining composition requests filters as classes
 
-Create a class te implements the `ICompositionRequestFilter<T>` interface, where the generic `T` parameter is the composition handler type to intercept:
+Create a class that implements the `ICompositionRequestFilter<T>` interface, where the generic `T` parameter is the composition handler type to intercept:
 
 <!-- snippet: composition-filter-class -->
 <a id='snippet-composition-filter-class'></a>
@@ -68,4 +68,22 @@ public class SampleCompositionFilter : ICompositionRequestFilter<SampleHandler>
 The above snippet defines a filter intercepting requests to the `SampleHandler` composition handler.
 
 > [!NOTE]
-> Filters defined as classes implementing the `ICompositionRequestFilter<T>` interface will be automatically registered in DI as transiten, and can use DI to resolve dependencies.
+> Filters defined as classes implementing the `ICompositionRequestFilter<T>` interface will be automatically registered in DI as transient, and can use DI to resolve dependencies.
+
+## When to use composition filters vs endpoint filters
+
+ServiceComposer provides two filter extension points. Choosing the right one depends on the scope of interception needed.
+
+**Use [endpoint filters](endpoint-filters.md) when:**
+
+- The logic applies to the entire composed request regardless of which handlers are involved (e.g. request logging, timing, global validation).
+- You want to short-circuit the whole composition before any handler runs.
+- The logic is independent of specific handler types.
+
+**Use composition filters when:**
+
+- The logic is specific to one particular composition handler type.
+- Different handlers on the same route need different pre/post processing (e.g. handler-specific authorization checks, handler-specific input validation).
+- You want to use the attribute form (`[SampleCompositionFilter]`) to keep the filter declaration co-located with the handler method.
+
+In short: endpoint filters are coarse-grained (the whole endpoint), composition filters are fine-grained (a specific handler).

docs/composition-over-controllers.md

@@ -5,12 +5,12 @@ ServiceComposer can be used to enhance a MVC web application by adding compositi
 <!-- snippet: enable-composition-over-controllers -->
 <a id='snippet-enable-composition-over-controllers'></a>
 ```cs
-services.AddViewModelComposition(options =>
+builder.Services.AddViewModelComposition(options =>
 {
     options.EnableCompositionOverControllers();
 });
 ```
-<sup><a href='/src/Snippets/CompositionOverController.cs#L10-L15' title='Snippet source file'>snippet source</a> | <a href='#snippet-enable-composition-over-controllers' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Snippets/CompositionOverController.cs#L12-L17' title='Snippet source file'>snippet source</a> | <a href='#snippet-enable-composition-over-controllers' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Once composition over controllers is enabled, ServiceComposer will inject a MVC filter to intercept all controllers invocations. If a route matches a regular controller and a set of composition handlers ServiceComposer will invoke the matching handlers after the controller and before the view is rendered.

docs/contract-less-composition-requests-handlers.md

@@ -2,7 +2,7 @@
 
 _Available starting version 4.2.0-beta.1_
 
-Contract-less composition handlers allow to write composition handlers using a syntax like the following:
+Contract-less composition handlers allow writing composition handlers using a syntax like the following:
 
 <!-- snippet: contract-less-handler-sample -->
 <a id='snippet-contract-less-handler-sample'></a>
@@ -81,9 +81,11 @@ Both classes will be registered in DI, allowing the injection of dependencies in
 
 Parameters decorated with `[FromServices]` are resolved from the DI container at request time. For example:
 
-```csharp
+<!-- snippet: contract-less-handler-from-services -->
+<a id='snippet-contract-less-handler-from-services'></a>
+```cs
 [CompositionHandler]
-class SampleCompositionHandler
+class SampleCompositionHandlerWithServices
 {
     [HttpGet("/sample/{id}")]
     public Task SampleMethod(int id, [FromServices] IMyService myService)
@@ -92,20 +94,34 @@ class SampleCompositionHandler
     }
 }
 ```
+<sup><a href='/src/Snippets/Contractless.CompositionHandlers/SampleCompositionHandlerWithServices.cs#L13-L23' title='Snippet source file'>snippet source</a> | <a href='#snippet-contract-less-handler-from-services' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
 
 The source generator will emit a `[BindFromServices<T>]` attribute for the parameter and resolve it via the DI container when the request is handled:
 
-```csharp
-[HttpGetAttribute("/sample/{id}")]
-[BindFromRoute<Int32>("id")]
-[BindFromServices<IMyService>("myService")]
-public Task Handle(HttpRequest request)
+<!-- snippet: contract-less-handler-from-services-generated -->
+<a id='snippet-contract-less-handler-from-services-generated'></a>
+```cs
+// <auto-generated/>
+#pragma warning disable SC0001
+[EditorBrowsable(EditorBrowsableState.Never)]
+class SampleCompositionHandlerWithServices_SampleMethod_int_id_IMyService_myService(
+    SampleCompositionHandlerWithServices userHandler) : ICompositionRequestsHandler
 {
-    var ctx = HttpRequestExtensions.GetCompositionContext(request);
-    var arguments = ctx.GetArguments(this);
-    var p0_id = ModelBindingArgumentExtensions.Argument<Int32>(arguments, "id", BindingSource.Path);
-    var p1_myService = ModelBindingArgumentExtensions.Argument<IMyService>(arguments, "myService", BindingSource.Services);
+    [HttpGetAttribute("/sample/{id}")]
+    [BindFromRoute<int>("id")]
+    [BindFromServices<IMyService>("myService")]
+    public Task Handle(HttpRequest request)
+    {
+        var ctx = HttpRequestExtensions.GetCompositionContext(request);
+        var arguments = ctx.GetArguments(this);
+        var p0_id = ModelBindingArgumentExtensions.Argument<int>(arguments, "id", BindingSource.Path);
+        var p1_myService = ModelBindingArgumentExtensions.Argument<IMyService>(arguments, "myService", BindingSource.Services);
 
-    return userHandler.SampleMethod(p0_id, p1_myService);
+        return userHandler.SampleMethod(p0_id, p1_myService);
+    }
 }
+#pragma warning restore SC0001
 ```
+<sup><a href='/src/Snippets/Contractless.CompositionHandlers/SampleCompositionHandlerWithServices.cs#L25-L46' title='Snippet source file'>snippet source</a> | <a href='#snippet-contract-less-handler-from-services-generated' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->

docs/custom-http-status-codes.md

@@ -1,6 +1,6 @@
-# Custom HTTP status codes in ASP.NET Core 3.x
+# Custom HTTP status codes
 
-The response status code can be set in requests handlers and it'll be honored by the composition pipeline. To set a custom response status code the following snippet can be used:
+The response status code can be set in composition handlers and it will be honored by the composition pipeline. To set a custom response status code the following snippet can be used:
 
 <!-- snippet: sample-handler-with-custom-status-code -->
 <a id='snippet-sample-handler-with-custom-status-code'></a>
@@ -20,5 +20,36 @@ public class SampleHandlerWithCustomStatusCode : ICompositionRequestsHandler
 <sup><a href='/src/Snippets/SampleHandler/SampleHandler.cs#L22-L34' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample-handler-with-custom-status-code' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
-> [!NOTE]
-> Requests handlers are executed in parallel in a non-deterministic way, setting the response code in more than one handler can have unpredictable effects.
+> [!WARNING]
+> Composition handlers execute in parallel in a non-deterministic order. If more than one handler sets the response status code, the final code written to the response is unpredictable. Only one handler in a composition group should set the status code.
+
+## Recommended approach: use action results instead
+
+For error scenarios (validation failures, not found, forbidden), prefer using [MVC Action results](action-results.md) via `request.SetActionResult(result)`. Action results are designed for exactly this case — ServiceComposer guarantees only the first handler to call `SetActionResult` takes effect, making the behavior deterministic:
+
+<!-- snippet: set-action-result-preferred -->
+<a id='snippet-set-action-result-preferred'></a>
+```cs
+public class SampleHandler : ICompositionRequestsHandler
+{
+    [HttpGet("/sample/{id}")]
+    public Task Handle(HttpRequest request)
+    {
+        if (!IsValid(request))
+        {
+            request.SetActionResult(new BadRequestResult());
+            return Task.CompletedTask;
+        }
+
+        var vm = request.GetComposedResponseModel();
+        vm.Data = "...";
+        return Task.CompletedTask;
+    }
+
+    bool IsValid(HttpRequest request) => request.RouteValues["id"] != null;
+}
+```
+<sup><a href='/src/Snippets/SampleHandler/SetActionResultHandler.cs#L8-L27' title='Snippet source file'>snippet source</a> | <a href='#snippet-set-action-result-preferred' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Setting a status code directly on `HttpContext.Response` is appropriate only when a handler is the sole authority on the response code for its route, or when using a non-MVC endpoint where action results are not available.