CleanCodeJN.GenericApis 3.6.0

dotnet add package CleanCodeJN.GenericApis --version 3.6.0                
NuGet\Install-Package CleanCodeJN.GenericApis -Version 3.6.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CleanCodeJN.GenericApis" Version="3.6.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CleanCodeJN.GenericApis --version 3.6.0                
#r "nuget: CleanCodeJN.GenericApis, 3.6.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install CleanCodeJN.GenericApis as a Cake Addin
#addin nuget:?package=CleanCodeJN.GenericApis&version=3.6.0

// Install CleanCodeJN.GenericApis as a Cake Tool
#tool nuget:?package=CleanCodeJN.GenericApis&version=3.6.0                

Generic Web Apis

CRUD support for WebAPIs with the power of Mediator pattern, Automapper with automatic mapping, DataRepositories and Entity Framework

This CleanCodeJN package streamlines the development of web APIs in .NET applications by providing a robust framework for CRUD operations and facilitating the implementation of complex business logic in a clean and maintainable manner.

Features

  • Paginated and filtered CRUD APIs (Minimal or Controller based) build in seconds
  • Uses Mediator to abstract build-in and custom complex business logic
  • Uses DataRepositories to abstract Entity Framework from business logic
  • Enforces IOSP (Integration/Operation Segregation Principle) for commands
  • Easy to mock and test
  • Automatic Entity to DTO mapping (no mapping config needed)
  • Built-in support for Fluent Validation
  • On latest .NET 8.0

How to use

  • Add RegisterRepositoriesCommandsWithAutomaticMapping<IDataContext>() to your Program.cs
  • Add app.RegisterApis() to your Program.cs or use AddControllers + MapControllers()
  • Start writing Apis by implementing IApi
  • Extend standard CRUD operations by specific Where() and Include() clauses
  • Use IOSP for complex business logic

Step by step explanation

Add RegisterRepositoriesCommandsWithAutomaticMapping<IDataContext>() to your Program.cs

// All Entity <=> DTO Mappings will be done automatically if the naming Convention will be applied:
// e.g.: Customer <=> CustomerGetDto 
// DTO has to start with Entity-Name and must inherits from IDto
// Entity must inherit from IEntity
builder.Services.RegisterRepositoriesCommandsWithAutomaticMapping<MyDbContext>();

You can also override specific mappings in RegisterRepositoriesCommandsWithAutomaticMapping<IDataContext>() in your Program.cs

// All other automatic mappings will be persisted
builder.Services.RegisterRepositoriesCommandsWithAutomaticMapping<MyDbContext>(cfg =>
{
    cfg.CreateMap<Customer, CustomerGetDto>()
       .ForMember(x => x.Name, opt => opt.MapFrom(x => string.Join(", ", x.Invoices.Select(x => x.Id))))
       .ReverseMap();
});

Add app.RegisterApis() when using Minimal APIs to your Program.cs

app.RegisterApis();

When using Controllers add this to your Program.cs

builder.Services.AddControllers();

// After Build()
app.MapControllers();

Start writing Minimal Apis by implementing IApi

public class CustomersV1Api : IApi
{
    public List<string> Tags => ["Customers Minimal API"];

    public string Route => $"api/v1/Customers";

    public List<Func<WebApplication, RouteHandlerBuilder>> HttpMethods =>
    [
        app => app.MapGet<Customer, CustomerGetDto, int>(
            Route,
            Tags,
            where: x => x.Name.StartsWith("Customer"),
            includes: [x => x.Invoices],
            select: x => new Customer { Name = x.Name },
            ignoreQueryFilters: true),
        app => app.MapGetPaged<Customer, CustomerGetDto, int>(Route, Tags),
        app => app.MapGetFiltered<Customer, CustomerGetDto, int>(Route, Tags),
        app => app.MapGetById<Customer, CustomerGetDto, int>(Route, Tags),
        app => app.MapPut<Customer, CustomerPutDto, CustomerGetDto>(Route, Tags),
        app => app.MapPost<Customer, CustomerPostDto, CustomerGetDto>(Route, Tags),

        // Or use a custom Command with MapRequest
        app => app.MapDeleteRequest(Route, Tags, async (int id, [FromServices] ApiBase api) =>
                await api.Handle<Customer, CustomerGetDto>(new SpecificDeleteRequest { Id = id }))
    ];
}

Extend standard CRUD operations by specific Where(), Include() or Select() clauses

public class CustomersV1Api : IApi
{
    public List<string> Tags => ["Customers Minimal API"];

    public string Route => $"api/v1/Customers";

    public List<Func<WebApplication, RouteHandlerBuilder>> HttpMethods =>
    [
         app => app.MapGet<Customer, CustomerGetDto, int>(Route, Tags, where: x => x.Name.StartsWith("a"), select: x => new Customer { Name = x.Name }),
    ];
}

Or use ApiCrudControllerBase for CRUD operations in controllers

[Tags("Customers Controller based")]
[Route($"api/v2/[controller]")]

public class CustomersController(IMediator commandBus, IMapper mapper)
    : ApiCrudControllerBase<Customer, CustomerGetDto, CustomerPostDto, CustomerPutDto, int>(commandBus, mapper)
{
}

You can also override your Where, Include or Select clauses

[Tags("Customers Controller based")]
[Route($"api/v2/[controller]")]

public class CustomersController(IMediator commandBus, IMapper mapper)
    : ApiCrudControllerBase<Customer, CustomerGetDto, CustomerPostDto, CustomerPutDto, int>(commandBus, mapper)
{
    public override Expression<Func<Customer, bool>> GetWhere => x => x.Name.StartsWith("a");

    public override List<Expression<Func<Customer, object>>> GetIncludes => [x => x.Invoices];

    public override Expression<Func<Customer, Customer>> GetSelect => x => new Customer { Name = x.Name };
}

For using the /filtered api with a filter, just provide a serialized json as filter parameter, like this:

{
    "Condition" : 0, // 0 = AND; 1 = OR
    "Filters": [
        {
            "Field": "Name",
            "Value": "aac",
            "Type": 0
        },
        {
            "Field": "Id",
            "Value": "3",
            "Type": 1
        }
    ]
}

Which means: Give me all Names which CONTAINS "aac" AND have Id EQUALS 3. So string Types use always CONTAINS and integer types use EQUALS. All filters are combined with ANDs.

The Type can be specified with these values:

public enum FilterTypeEnum
{
    STRING = 0,
    INTEGER = 1,
    DOUBLE = 2,
    INTEGER_NULLABLE = 3,
    DOUBLE_NULLABLE = 4,
    DATETIME = 5,
    DATETIME_NULLABLE = 6,
    GUID = 7,
    GUID_NULLABLE = 8,
}

More Advanced Topics

Built-in Support for Fluent Validation:

Just write your AbstractValidators<T>. They will be automatically executed on generic POST and generic PUT actions:

public class CustomerPostDtoValidator : AbstractValidator<CustomerPostDto>
{
    public CustomerPostDtoValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(10);
    }
public class CustomerPutDtoValidator : AbstractValidator<CustomerPutDto>
{
    public CustomerPutDtoValidator()
    {
        RuleFor(x => x.Id)
            .GreaterThan(0);

        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(10)
            .CreditCard();
    }
}

Implement your own specific Request:

public class SpecificDeleteRequest : IRequest<BaseResponse<Customer>>
{
    public required int Id { get; init; }
}

Requests can also be marked as ICachableRequest, which uses IDistributedCache to cache the Response:

public class SpecificDeleteRequest : IRequest<BaseResponse<Customer>>, ICachableRequest
{
    public required int Id { get; init; }

    public bool BypassCache { get; }

    public string CacheKey => "Your Key";

    public TimeSpan? CacheDuration => TimeSpan.FromHours(168);
}

With your own specific Command using CleanCodeJN.Repository

public class SpecificDeleteCommand(IRepository<Customer, int> repository) : IRequestHandler<SpecificDeleteRequest, BaseResponse<Customer>>
{
    public async Task<BaseResponse<Customer>> Handle(SpecificDeleteRequest request, CancellationToken cancellationToken)
    {
        var deletedCustomer = await repository.Delete(request.Id, cancellationToken);

        return await BaseResponse<Customer>.Create(deletedCustomer is not null, deletedCustomer);
    }
}

Use IOSP for complex business logic

Derive from BaseIntegrationCommand:

public class YourIntegrationCommand(ICommandExecutionContext executionContext)
    : BaseIntegrationCommand(executionContext), IRequestHandler<YourIntegrationRequest, BaseResponse>

Write Extensions on ICommandExecutionContext with Built in Requests or with your own

public static ICommandExecutionContext CustomerGetByIdRequest(
    this ICommandExecutionContext executionContext, int customerId) 
    => executionContext.WithRequest(
            () => new GetByIdRequest<Customer>
            {
                Id = customerId,
                Includes = [x => x.Invoices, x => x.OtherDependentTable],
            },
            CommandConstants.CustomerGetById);

See the how clean your code will look like in the end

public class YourIntegrationCommand(ICommandExecutionContext executionContext)
    : BaseIntegrationCommand(executionContext), IRequestHandler<YourIntegrationRequest, BaseResponse<Customer>>
{
    public async Task<BaseResponse<Customer>> Handle(YourIntegrationRequest request, CancellationToken cancellationToken) =>
        await ExecutionContext
            .CandidateGetByIdRequest(request.Dto.CandidateId)
            .CustomerGetByIdRequest(request.Dto.CustomerIds)
            .GetOtherStuffRequest(request.Dto.XYZType)
            .PostSomethingRequest(request.Dto)
            .SendMailRequest()
            .Execute<Customer>(cancellationToken);
}

Sample Code

GitHub Full Sample

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on CleanCodeJN.GenericApis:

Package Downloads
CleanCodeJN.GenericApis.ServiceBusConsumer

This CleanCodeJN package for Service Bus simplifies the development of asynchronous microservices by providing a framework that leverages the power of MediatR and IOSP to consume service bus events from topics and execute commands to process these events.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.6.0 113 12/12/2024
3.5.1 87 12/7/2024
3.5.0 97 11/19/2024
3.4.1 108 11/10/2024
3.4.0 98 11/10/2024
3.3.0 123 10/21/2024
3.2.2 120 10/20/2024
3.2.1 127 10/20/2024
3.2.0 120 10/20/2024
3.1.9 146 10/18/2024
3.1.8 107 10/9/2024
3.1.7 97 10/8/2024
3.1.6 104 10/8/2024
3.1.5 111 9/25/2024
3.1.4 129 9/12/2024
3.1.3 108 9/12/2024
3.1.2 105 9/12/2024
3.1.1 120 9/11/2024
3.1.0 102 9/9/2024
3.0.4 105 9/6/2024
3.0.3 107 9/6/2024
3.0.2 118 9/3/2024
3.0.1 84 7/30/2024
3.0.0 137 5/24/2024
2.2.0 111 5/23/2024
2.1.1 113 5/22/2024
2.1.0 119 5/15/2024
2.0.8 103 5/14/2024
2.0.7 112 5/14/2024
2.0.6 101 5/14/2024
2.0.5 104 5/13/2024
2.0.4 91 5/13/2024
2.0.3 96 5/12/2024
2.0.2 105 5/11/2024
2.0.1 108 5/8/2024
2.0.0 121 5/7/2024
1.1.1 120 5/7/2024
1.1.0 115 5/7/2024
1.0.6 132 5/7/2024
1.0.5 117 5/7/2024
1.0.4 118 5/7/2024
1.0.3 143 5/7/2024
1.0.2 115 5/6/2024
1.0.1 125 5/6/2024
1.0.0 124 5/6/2024

Add Caching Behavior to support Distributed Caching for Requests.