From c429a55e8ee3e88b5081f6fdfbfcfb31485cdfdb Mon Sep 17 00:00:00 2001
From: Alex Macocian <amacocian@yahoo.com>
Date: Wed, 16 Apr 2025 13:49:37 +0200
Subject: [PATCH] Update README.md

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/README.md b/README.md
index 5761e93..29d9051 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
 .NET library extending functionality for web applications
 
 # Features
+- [MVC Source Generators](#mvc-source-generators)
 - [Improved Websocket Support](#better-websocket-support)
 - [Improved request tracing](#request-tracing-using-correlationvectors)
 - [Improved client IP handling](#client-ip-extraction)
@@ -10,6 +11,64 @@
 - [Mockable IHttpClient builder](#mockable-httpclient)
 - [Support for base64 encoded certificates in configuration](#base64-to-x509certificate2-converter-for-options)
 
+## MVC Source Generators
+
+Net.Sdk.Web.Extensions provides a set of source generators to replicate the MVC functionality of Asp while being compatible with NativeAOT compilation.
+
+### Usage
+1) Add the `Net.Sdk.Web.Extensions.SourceGenerators` package to your project
+2) Create a controller class
+```csharp
+[GenerateController("api/v1/accounts")]
+public sealed class AccountsController(
+    IAccountService accountService)
+{
+    private readonly IAccountService accountService = accountService;
+
+    [GenerateGet("{accountId}")]
+    [RouteFilter<AuthenticatedFilter>]
+    public async Task<IResult> GetAccount(HttpContext context, [FromRoute] string accountId, CancellationToken cancellationToken)
+    {
+        var account = await this.accountService.GetAccountById(accountId, cancellationToken);
+        if (account is null)
+        {
+            return Results.NotFound();
+        }
+
+        return Results.Ok(account);
+    }
+
+    [GeneratePost]
+    public async Task<IResult> PostAccount([FromBody] PostAccountRequest request, CancellationToken cancellationToken)
+    {
+        if (await this.accountService.CreateAccount(request.Email, request.Email, request.Password, cancellationToken))
+        {
+            return Results.Created();
+        }
+
+        return Results.BadRequest();
+    }
+}
+```
+3) Register the routes in the `WebApplicationBuilder` using `WithRoutes()` extension. This extension is generated by the source generator and is available under the `Net.Sdk.Web` namespace in `WebApplicationBuilderExtensions` class.
+```csharp
+builder.WithRoutes();
+```
+
+4) Use the routes in your `WebApplication` class using `UseRoutes()` extension. This extension is generated by the source generator and is available under the `Net.Sdk.Web` namespace in `WebApplicationExtensions` class.
+```csharp
+app.UseRoutes();
+```
+
+### Functionality
+- `GenerateController` attribute allows you to define a controller class and its route.
+- `GenerateGet`, `GeneratePost`, `GeneratePut`, `GenerateDelete` attributes allow you to define the HTTP methods and their routes.
+- `FromRoute`, `FromBody`, `FromQuery` attributes allow you to define the parameters of the methods.
+- `RouteFilter` attribute allows you to define the filters for the methods. Filters must be of type `Microsoft.AspNetCore.Http.IEndpointFilter`.
+- `HttpContext` can be accessed by requesting it as a parameter of your route method. The generator will automatically fetch it from the context and pass it to your method.
+- Controllers are registered as services in the DI container, so you can inject any service into them.
+- There is no restriction on the modifiers of your controllers. You can freely use inheritance for shared functionality between controllers.
+
 ## Better WebSocket support
 
 Net.Sdk.Web.Extensions provides a streamlined implementation of WebSockets to be used in a web app, in a syntax similar to Asp Mvc