CleanCodeJN.GenericApis
3.6.0
dotnet add package CleanCodeJN.GenericApis --version 3.6.0
NuGet\Install-Package CleanCodeJN.GenericApis -Version 3.6.0
<PackageReference Include="CleanCodeJN.GenericApis" Version="3.6.0" />
paket add CleanCodeJN.GenericApis --version 3.6.0
#r "nuget: CleanCodeJN.GenericApis, 3.6.0"
// 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
Product | Versions 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. |
-
net8.0
- AutoMapper (>= 13.0.1)
- CleanCodeJN.GenericApis.Abstractions (>= 2.3.0)
- CleanCodeJN.Repository.EntityFramework (>= 1.1.7)
- FluentValidation (>= 11.11.0)
- FluentValidation.AspNetCore (>= 11.3.0)
- MediatR (>= 12.4.1)
- Microsoft.Extensions.Caching.Memory (>= 8.0.1)
- System.Formats.Asn1 (>= 8.0.1)
- System.Text.Json (>= 8.0.5)
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.