Skip to main content

immediate.apis by Stuart Turner

Nuget / site data​

Nuget GitHub last commit GitHub Repo stars

Details​

Info​

info

Name: immediate.apis

An implementation of the mediator pattern in .NET using source-generation.

Author: Stuart Turner

NuGet: https://www.nuget.org/packages/immediate.apis/

You can find more details at https://github.com/immediateplatform/immediate.apis

Source : https://github.com/immediateplatform/immediate.apis

Original Readme​

note

Immediate.Apis

NuGet GitHub release GitHub license GitHub issues GitHub issues-closed

GitHub Actions​

Immediate.Apis is a source generator for minimal APIs, for Immediate.Handlers handlers. Simply add a [MapGet] to the [Handler] class and an endpoint will automatically be added.

Examples​

Installing Immediate.Apis​

You can install Immediate.Apis with NuGet:

Install-Package Immediate.Apis

Or via the .NET Core command line interface:

dotnet add package Immediate.Apis

Either commands, from Package Manager Console or .NET Core CLI, will download and install Immediate.Handlers.

Using Immediate.Apis​

Creating an Endpoint​

Create a Handler and an endpoint by adding the following code:

[Handler]
[MapGet("/users")]
public static partial class GetUsersQuery
{
    public record Query;

    private static ValueTask<IEnumerable<User>> HandleAsync(
        Query _,
        UsersService usersService,
        CancellationToken token)
    {
        return usersService.GetUsers();
    }
}

Registering the endpoints​

In your Program.cs, add a call to app.MapXxxEndpoints(), where Xxx is the shortened form of the project name.

  • For a project named Web, it will be app.MapWebEndpoints()
  • For a project named Application.Web, it will be app.MapApplicationWebEndpoints()

Customizing the endpoints​

AsParameters​

By default on POST and PUT requests Immediate.Apis will assume that your request class should be treated as a [FromBody]. Sometimes, however, this is not desired. For example imagine a PUT request that sits at a route /api/todos/{id} and updates a TODO with a given ID. We would want to get the id from the route and the properties to update from the body. To do so, we need to create the following request command class:

public sealed record Command
{
    public sealed record CommandBody
    {
        // props here;
    }
    
    [FromRoute]
    public required int Id { get; init; }
    
    [FromBody]
    public required CommandBody Body { get; init; }
}

...and modify the HandleAsync method to let Immediate.Apis know we want to treat the outer Command class as [AsParameters], like so:

private static async ValueTask<Results<NoContent, NotFound>> HandleAsync(
    [AsParameters] Command command,
    ExampleDbContext dbContext,
    CancellationToken ct
) 
{
    // ...
}

Authorization​

The [AllowAnonymous] and [Authorized("Policy")] attributes are supported and will be applied to the endpoint.

[Handler]
[MapGet("/users")]
[AllowAnonymous]
public static partial class GetUsersQuery
{
    public record Query;

    private static ValueTask<IEnumerable<User>> HandleAsync(
        Query _,
        UsersService usersService,
        CancellationToken token)
    {
        return usersService.GetUsers();
    }
}

Additional Customization of Endpoint Registration​

Additional customization of the endpoint registration can be done by adding a CustomizeEndpoint method.

[Handler]
[MapGet("/users")]
[Authorize(Policies.UserManagement)]
public static partial class GetUsersQuery
{
    internal static void CustomizeGetFeaturesEndpoint(IEndpointConventionBuilder endpoint)
        => endpoint
            .Produces<IEnumerable<User>>(StatusCodes.Status200OK)
            .ProducesValidationProblem()
            .ProducesProblem(StatusCodes.Status500InternalServerError)
            .WithTags(nameof(User));

    public record Query;

    private static ValueTask<IEnumerable<User>> HandleAsync(
        Query _,
        UsersService usersService,
        CancellationToken token)
    {
        return usersService.GetUsers();
    }
}

Transforming the handler result into a different type​

In some cases, you may wish to transform the result of the handler into a different type; for example, you may wish to return a Results<> type which will work with asp.net core to return various status codes.

You can transform the result of your handler into a different type by adding a TransformResult method, like so:

[Handler]
[MapGet("/users")]
[Authorize(Policies.UserManagement)]
public static partial class GetUsersQuery
{
    internal static Results<Ok<IEnumerable<User>>, NotFound> TransformResult(IEnumerable<User> result)
    {
        return TypedResults.Ok(result);
    }

    public record Query;

    private static ValueTask<IEnumerable<User>> HandleAsync(
        Query _,
        UsersService usersService,
        CancellationToken token
    )
    {
        return usersService.GetUsers();
    }
}

About​

note

Defining APIs in classes instead of in minimal API or controllers

How to use​

Example ( source csproj, source files )​

This is the CSharp Project that references immediate.apis

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Immediate.Apis" Version="1.3.0" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.4" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>
    <PropertyGroup>
        <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
        <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
    </PropertyGroup>
</Project>

Generated Files​

Those are taken from $(BaseIntermediateOutputPath)\GX

using System.Threading;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Routing;

#pragma warning disable CS1591

namespace Microsoft.AspNetCore.Builder
{
    public static partial class APIDemoRoutesBuilder
    {
        private static void MapAPIDemo_PersonAPIEndpoint(IEndpointRouteBuilder app)
        {
            var endpoint = app
                .MapGet(
                    "/users",
                    async (
                        [AsParameters] global::APIDemo.PersonAPI.Query parameters,
                        [FromServices] global::APIDemo.PersonAPI.Handler handler,
                        CancellationToken token
                    ) =>
                    {
                        var ret = await handler.HandleAsync(parameters, token);
                        return ret;
                    }
                );
        }
    }
}

namespace APIDemo
{

    /// <remarks><see cref="global::APIDemo.PersonAPI.Query" /> registered using <c>[AsParameters]</c></remarks>
    partial class PersonAPI;
}

Usefull​

Download Example (.NET C# )​

tip

Download Example project immediate.apis

Share immediate.apis​

https://ignatandrei.github.io/RSCG_Examples/v2/docs/immediate.apis

In the same category (API) - 9 other generators​

Microsoft.Extensions.Configuration.Binder​

MinimalApiBuilder​

MinimalApis.Discovery​

MinimalHelpers.Routing.Analyzers​

RDG​

Refit​

RSCG_WebAPIExports​

SafeRouting​

SkinnyControllersCommon​