Make pure source generator

Author: futurum-dev

.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
         uses: actions/checkout@v2
         with:
           fetch-depth: 100
-        
+
       - name: Setup .NET 7
         uses: actions/setup-dotnet@v1
         with:
@@ -28,7 +28,7 @@ jobs:
       - name: Test
         run: dotnet test --no-restore --verbosity normal
 
-      - name: Pack Futurum.Core
+      - name: Pack Futurum.WebApiEndpoint.Micro
         run: dotnet pack ./src/Futurum.WebApiEndpoint.Micro/Futurum.WebApiEndpoint.Micro.csproj --output nuget-packages --configuration Release
       - name: NuGet publish
         run: find nuget-packages -name 'Futurum.WebApiEndpoint.Micro*.nupkg' | xargs -i dotnet nuget push {} --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json
@@ -37,4 +37,4 @@ jobs:
         uses: actions/upload-artifact@v2
         with:
           name: nuget-packages
-          path: nuget-packages/**/*
+          path: nuget-packages/**/*

README.md

@@ -9,9 +9,9 @@ A dotnet library that allows you to build WebApiEndpoints using a vertical slice
 
 ```csharp
 [WebApiEndpoint("greeting")]
-public class GreetingWebApiEndpoint : IWebApiEndpoint
+public class GreetingWebApiEndpoint
 {
-    public void Register(IEndpointRouteBuilder builder)
+    protected override void Build(IEndpointRouteBuilder builder)
     {
         builder.MapGet("/hello", HelloHandler);
         builder.MapGet("/goodbye", GoodbyeHandler);
@@ -82,6 +82,9 @@ app.Run();
 
 #### AddWebApiEndpoints
 Allows you to configure:
+- GlobalRoutePrefix *(optional)*
+  - This is used if you want to specify a global route prefix for all WebApiEndpoint
+  - e.g. "/api"
 - DefaultApiVersion *(mandatory)*
   - This is used if a specific ApiVersion is not provided for a specific WebApiEndpoint
 - DefaultOpenApiInfo *(optional)*
@@ -132,17 +135,17 @@ Register the OpenApi UI (Swagger and SwaggerUI) middleware
 app.UseWebApiEndpointsOpenApi();
 ```
 
-### IWebApiEndpoint
-### Register
-You can *map* your minimal apis for this WebApiEndpoint in the *Register* method.
+### WebApiEndpoint
+### Build
+You can *map* your minimal apis for this WebApiEndpoint in the *Build* method.
 
 The *IEndpointRouteBuilder* parameter is already:
 - configured with the API versioning
 - configured with the route prefix
 - been through the *optional* *Configure* method in the same class
 
 ```csharp
-public void Register(IEndpointRouteBuilder builder)
+protected override void Build(IEndpointRouteBuilder builder)
 {
 }
 ```
@@ -151,14 +154,14 @@ public void Register(IEndpointRouteBuilder builder)
 #### Weather
 ```csharp
 [WebApiEndpoint("weather")]
-public class WeatherWebApiEndpoint : IWebApiEndpoint
+public class WeatherWebApiEndpoint
 {
     private static readonly string[] Summaries =
     {
         "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
     };
 
-    public void Register(IEndpointRouteBuilder builder)
+    protected override void Build(IEndpointRouteBuilder builder)
     {
         builder.MapGet("/", GetHandler);
     }
@@ -173,9 +176,9 @@ public class WeatherWebApiEndpoint : IWebApiEndpoint
 #### File download
 ```csharp
 [WebApiEndpoint("bytes", "feature")]
-public class BytesWebApiEndpoint : IWebApiEndpoint
+public class BytesWebApiEndpoint
 {
-    public void Register(IEndpointRouteBuilder builder)
+    protected override void Build(IEndpointRouteBuilder builder)
     {
         builder.MapGet("download", DownloadHandler);
     }
@@ -204,7 +207,7 @@ public class BytesWebApiEndpoint : IWebApiEndpoint
 You can *optionally* configure the WebApiEndpoint in the *Configure* method
 
 ```csharp
-public void Configure(RouteGroupBuilder groupBuilder, WebApiEndpointVersion webApiEndpointVersion)
+protected override RouteGroupBuilder Configure(RouteGroupBuilder groupBuilder, WebApiEndpointVersion webApiEndpointVersion)
 {
 }
 ```
@@ -233,16 +236,16 @@ groupBuilder.RequireAuthorization(Authorization.Permission.Admin);
 ```
 
 ## Sandbox runner
-### Run and RunAsync - Results<...> -> Results<..., BadRequest<ProblemDetails>>
-Comprehensive set of extension methods - *WebApiEndpointRunner.Run* and *WebApiEndpointRunner.RunAsync* - to run a method that returns *Results<...>* in a sandbox. If an unhandled *exception* is thrown it will be caught and transformed it into a *BadRequest<ProblemDetails>*.
+### Run and RunAsync - If your code returns an *IResult*
+Comprehensive set of extension methods, to run your code in a sandbox
+- If your code **does not** throw an unhandled exception, then the existing return remains the same.
+- If your code **does** throw an unhandled exception, then a *BadRequest<ProblemDetails>* will be returned, with the appropriate details set on the ProblemDetails.
 
-The *Run* and *RunAsync* methods will:
-- If the method passed in **does not** throw an unhandled exception, then the existing return remains the same.
-- If the method passed in **does** throw an unhandled exception, then a *BadRequest<ProblemDetails>* will be returned, with the appropriate details set on the ProblemDetails. The *error message* will be safe to return to the client, that is, it will not contain any sensitive information e.g. StackTrace.
-
-The returned *Results<...>* type from *Run* and *RunAsync* is always augmented to additionally include *BadRequest<ProblemDetails>*
+The returned *Results<...>* type is always augmented to additionally include *BadRequest<ProblemDetails>*
 
 ```csharp
+TIResult1 -> Results<TIResult1, BadRequest<ProblemDetails>>
+
 Results<TIResult1, TIResult2> -> Results<TIResult1, TIResult2, BadRequest<ProblemDetails>>
 
 Results<TIResult1, TIResult2, TIResult3> -> Results<TIResult1, TIResult2, TIResult3, BadRequest<ProblemDetails>>
@@ -275,7 +278,7 @@ private static Results<NotFound, FileStreamHttpResult, BadRequest<ProblemDetails
 }
 ```
 
-In this example the *Execute* method will return:
+In this example the *Execute* method is being wrapped by the runner. It returns:
 - a *NotFound* if the file does not exist
 - a *FileStreamHttpResult* if the file exists
 
@@ -296,26 +299,24 @@ global using static Futurum.WebApiEndpoint.Micro.WebApiEndpointRunner;
 
 This means you can use the helper functions without having to specify the namespace. As in the examples.
 
-### Run and RunAsync - (T, Func&lt;T, IResult&gt;) -> Results&lt;IResult, BadRequest&lt;ProblemDetails&gt;&gt;
-Extension methods - *WebApiEndpointRunner.Run* and *WebApiEndpointRunner.RunAsync* - to run a method that returns *T* in a sandbox. If an unhandled *exception* is thrown it will be caught and transformed it into a *BadRequest&lt;ProblemDetails&gt;*.
-
-The *Run* and *RunAsync* methods will:
-- If the method passed in **does not** throw an unhandled exception, then the *Func&lt;T, IResult&gt;* will be called with the return value.
-- If the method passed in **does** throw an unhandled exception, then a *BadRequest&lt;ProblemDetails&gt;* will be returned, with the appropriate details set on the ProblemDetails. The *error message* will be safe to return to the client, that is, it will not contain any sensitive information e.g. StackTrace.
+### RunToOk and RunToOkAsync - If your code returns an *T* (not a *IResult*)
+Comprehensive set of extension methods, to run your code in a sandbox
+- If your code **does not** throw an unhandled exception, then the existing return remains the same, *but* will be wrapped in an *Ok*.
+- If your code **does** throw an unhandled exception, then a *BadRequest&lt;ProblemDetails&gt;* will be returned, with the appropriate details set on the ProblemDetails.
 
-The returned *T* type from *Run* and *RunAsync* is always augmented to additionally include *BadRequest&lt;ProblemDetails&gt;*
+The returned type from *Run* and *RunAsync* is always augmented to additionally include *BadRequest&lt;ProblemDetails&gt;*
 
 ```csharp
-(T, Func<T, TResult>) -> Results<TResult, BadRequest<ProblemDetails>> where TResult : IResult
-```
+_ -> Results<Ok, BadRequest<ProblemDetails>>
 
-For the *Func&lt;T, IResult&gt;*, there are a number of built-in [success helper functions](#success-helper-functions) that can be used. Or you can use your own.
+T -> Results<Ok<T>, BadRequest<ProblemDetails>>
+```
 
 #### Example use
 ```csharp
 private static Results<Ok<IAsyncEnumerable<Todo>>, BadRequest<ProblemDetails>> GetAllHandler(HttpContext context, SqliteConnection db)
 {
-    return Run(Execute, context, ToOk, "Failed to get todos");
+    return RunToOk(Execute, context, "Failed to get todos");
 
     IAsyncEnumerable<Todo> Execute() =>
         db.QueryAsync<Todo>("SELECT * FROM Todos");
@@ -328,7 +329,9 @@ In this example the *Execute* method returns *IAsyncEnumerable&lt;Todo&gt;*
 IAsyncEnumerable<Todo>
 ```
 
-The *Run* / *RunAsync* extension method with *ToOk* [success helper function](#success-helper-functions) passed in will change this to:
+The *RunToOk* / *RunToOkAsync* extension method will
+- change the *T* to *Ok&lt;T&gt;*
+- add *BadRequest&lt;ProblemDetails&gt;*.
 
 ```csharp
 Results<Ok<IAsyncEnumerable<Todo>>, BadRequest<ProblemDetails>>
@@ -346,51 +349,49 @@ This means you can use the helper functions without having to specify the namesp
 Use the *FormFileWithPayload* type to upload a single file and a JSON payload
 
 ```csharp
-    private static Task<Results<Ok<FileDetailsWithPayloadDto>, BadRequest<ProblemDetails>>> UploadWithPayloadHandler(HttpContext context, FormFileWithPayload<PayloadDto> fileWithPayload)
-    {
-        return Result.TryAsync(Execute, () => "Failed to read file")
-                     .ToWebApiAsync(context, ToOk);
+private static Task<Results<Ok<FileDetailsWithPayloadDto>, BadRequest<ProblemDetails>>> UploadWithPayloadHandler(HttpContext context, FormFileWithPayload<PayloadDto> fileWithPayload)
+{
+    return RunAsync(Execute, context, ToOk, "Failed to read file");
 
-        async Task<FileDetailsWithPayloadDto> Execute()
-        {
-            var tempFile = Path.GetTempFileName();
-            await using var stream = File.OpenWrite(tempFile);
-            await fileWithPayload.File.CopyToAsync(stream);
+    async Task<FileDetailsWithPayloadDto> Execute()
+    {
+        var tempFile = Path.GetTempFileName();
+        await using var stream = File.OpenWrite(tempFile);
+        await fileWithPayload.File.CopyToAsync(stream);
 
-            return new FileDetailsWithPayloadDto(fileWithPayload.File.FileName, fileWithPayload.Payload.Name);
-        }
+        return new FileDetailsWithPayloadDto(fileWithPayload.File.FileName, fileWithPayload.Payload.Name);
     }
+}
 ```
 
 ### Upload multiple files and payload
 Use the *FormFilesWithPayload* type to upload multiple files and a JSON payload
 
 ```csharp
-    private static Task<Results<Ok<IEnumerable<FileDetailsWithPayloadDto>>, BadRequest<ProblemDetails>>> UploadsWithPayloadHandler(
-        HttpContext context, FormFilesWithPayload<PayloadDto> filesWithPayload)
+private static Task<Results<Ok<IEnumerable<FileDetailsWithPayloadDto>>, BadRequest<ProblemDetails>>> UploadsWithPayloadHandler(
+    HttpContext context, FormFilesWithPayload<PayloadDto> filesWithPayload)
+{
+    return RunAsync(Execute, context, ToOk, "Failed to read file");
+
+    async Task<IEnumerable<FileDetailsWithPayloadDto>> Execute()
     {
-        return Result.TryAsync(Execute, () => "Failed to read file")
-                     .ToWebApiAsync(context, ToOk);
+        var fileDetails = new List<FileDetailsWithPayloadDto>();
 
-        async Task<IEnumerable<FileDetailsWithPayloadDto>> Execute()
+        foreach (var file in filesWithPayload.Files)
         {
-            var fileDetails = new List<FileDetailsWithPayloadDto>();
-
-            foreach (var file in filesWithPayload.Files)
-            {
-                var tempFile = Path.GetTempFileName();
-                await using var stream = File.OpenWrite(tempFile);
-                await file.CopyToAsync(stream);
-
-                fileDetails.Add(new FileDetailsWithPayloadDto(file.FileName, filesWithPayload.Payload.Name));
-            }
+            var tempFile = Path.GetTempFileName();
+            await using var stream = File.OpenWrite(tempFile);
+            await file.CopyToAsync(stream);
 
-            return fileDetails;
+            fileDetails.Add(new FileDetailsWithPayloadDto(file.FileName, filesWithPayload.Payload.Name));
         }
+
+        return fileDetails;
     }
+}
 ```
 
-### Success helper functions
+### Additional helper functions
 #### ToOk
 Converts a *T* to an *Ok&lt;T&gt;*.
 
@@ -452,12 +453,29 @@ There are examples showing the following:
 - [x] OpenApi versioning
 - [x] Output Caching
 - [x] Rate Limiting
-- [x] Security with a basic JWT example on a specific WebApiEndpoint
+- [x] [Security](#security-example) with a basic JWT example on a specific WebApiEndpoint
 - [x] Weather Forecast
 - [x] Addition project containing WebApiEndpoints
 
 ![Futurum.WebApiEndpoint.Micro.Sample-openapi.png](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/raw/main/docs/Futurum.WebApiEndpoint.Micro.Sample-openapi.png)
 
+### Security example
+How to use in Swagger UI:
+1. Run the Sample project
+2. In the Swagger UI, go to the 'Security' 'Login' endpoint
+3. Set the following
+Username = user1
+Password = password1
+SetPermissions = true
+SetClaim = true
+SetRole = true
+4. Copy the value returned without double quotes.
+5. Go to the 'Security' 'Protected' endpoint
+6. Click on the padlock
+7. In the value textbox, enter "Bearer " (don't forget the space at the end) + the value returned from the 'Login' endpoint that you copied in step 4.
+8. Click "Authorize"
+9. Run the 'Protected' endpoint
+
 ## Convention Customisation
 Although the default conventions are good enough for most cases, you can customise them.
 
@@ -488,33 +506,6 @@ Use this instead
 builder.Services.AddWebApiEndpoints();
 ```
 
-### IWebApiEndpointMetadataStrategy
-This is used to get the *metadata* for each *WebApiEndpoint*.
-
-The *metadata* contains:
-- PrefixRoute
-- Tag
-- WebApiEndpointVersion
-
-```csharp
-serviceCollection.AddWebApiEndpointMetadataStrategy<WebApiEndpointMetadataAttributeStrategy>();
-```
-
-The default strategy is *WebApiEndpointMetadataAttributeStrategy*.
-
-#### WebApiEndpointMetadataAttributeStrategy
-This uses the following attributes:
-- WebApiEndpointAttribute - for 'PrefixRoute' and 'Tag'
-- WebApiEndpointVersionAttribute - for 'WebApiEndpointVersion', can have multiple
-
-```csharp
-[WebApiEndpoint("weather")]
-```
-
-```csharp
-[WebApiEndpointVersion(1)]
-```
-
 ## Roslyn Analysers
 - FWAEM0001 - Non empty constructor found on WebApiEndpoint
 - FWAEM0002 - BadRequest without 'ProblemDetails' use found on WebApiEndpoint

sample/Futurum.WebApiEndpoint.Micro.Sample.Addition/AdditionWebApiEndpoint.cs

@@ -2,10 +2,10 @@
 
 namespace Futurum.WebApiEndpoint.Micro.Sample.Addition;
 
-[WebApiEndpoint(prefixRoute: "addition")]
-public class AdditionWebApiEndpoint : IWebApiEndpoint
+[WebApiEndpoint("addition")]
+public partial class AdditionWebApiEndpoint
 {
-    public void Register(IEndpointRouteBuilder builder)
+    protected override void Build(IEndpointRouteBuilder builder)
     {
         builder.MapGet("/", GetHandler);
     }

sample/Futurum.WebApiEndpoint.Micro.Sample/Analyzers/MethodReturningBadRequestWithoutProblemDetails.cs

@@ -1,13 +1,13 @@
 namespace Futurum.WebApiEndpoint.Micro.Sample.Analyzers;
 
 [WebApiEndpoint(prefixRoute: "method-returning-BadRequest-without-ProblemDetails", group: "analyzer")]
-public class MethodReturningBadRequestWithoutProblemDetails : IWebApiEndpoint
+public partial class MethodReturningBadRequestWithoutProblemDetails
 {
-    public void Register(IEndpointRouteBuilder builder)
+    protected override void Build(IEndpointRouteBuilder builder)
     {
         builder.MapGet("/", ResultErrorHandler);
     }
-    
+
     private static Results<Ok<string>, BadRequest<string>> ResultErrorHandler(HttpContext context) =>
         "This WebApiEndpoint has a non-empty constructor and will raise a warning.".ToOk();
-}
+}

sample/Futurum.WebApiEndpoint.Micro.Sample/Analyzers/NonEmptyConstructorOnWebApiEndpoint.cs

@@ -1,17 +1,17 @@
 namespace Futurum.WebApiEndpoint.Micro.Sample.Analyzers;
 
 [WebApiEndpoint("non-empty-constructor", "analyzer")]
-public class NonEmptyConstructorOnWebApiEndpoint : IWebApiEndpoint
+public partial class NonEmptyConstructorOnWebApiEndpoint
 {
     public NonEmptyConstructorOnWebApiEndpoint(IConfiguration configuration)
     {
     }
-    
-    public void Register(IEndpointRouteBuilder builder)
+
+    protected override void Build(IEndpointRouteBuilder builder)
     {
         builder.MapGet("/", GetHandler);
     }
 
     private static Ok<string> GetHandler(HttpContext context) =>
         "This WebApiEndpoint has a non-empty constructor and will raise a warning.".ToOk();
-}
+}

sample/Futurum.WebApiEndpoint.Micro.Sample/Blog/BlogMapper.cs

@@ -3,5 +3,5 @@ namespace Futurum.WebApiEndpoint.Micro.Sample.Blog;
 public static class BlogMapper
 {
     public static BlogDto MapToDto(Blog domain) =>
-        new(domain.Id.GetValueOrDefault(x => x.Value, 0), domain.Url);
-}
+        new(domain.Id?.Value ?? 0, domain.Url);
+}