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.
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 AddCleanCodeJN() to your Program.cs
Add app.UseCleanCodeJNWithMinimalApis() to your Program.cs for minimal APIs 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 AddCleanCodeJN() 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.AddCleanCodeJN<MyDbContext>(options => {});
These are the CleanCodeJN Options
public class CleanCodeOptions
{
/// <summary>
/// The assemblies that contain the command types.
/// </summary>
public List<Assembly> ApplicationAssemblies { get; set; } = [];
/// <summary>
/// The assembly that contains the validators types.
/// </summary>
public Assembly ValidatorAssembly { get; set; }
/// <summary>
/// The assembly that contains the mapping profiles.
/// </summary>
public Action<IMapperConfigurationExpression> MappingOverrides { get; set; }
/// <summary>
/// If true: Use distributed memory cache.
/// </summary>
public bool UseDistributedMemoryCache { get; set; } = true;
}
Add app.UseCleanCodeJNWithMinimalApis() when using Minimal APIs to your Program.cs
app.UseCleanCodeJNWithMinimalApis();
When using Controllers add this to your Program.cs
builder.Services.AddControllers()
.AddNewtonsoftJson(); // this is needed for "http patch" only. If you do not need to use patch, you can remove this line
// 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),
app => app.MapPatch<Customer, CustomerGetDto, int>(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:
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.
Just write your AbstractValidators. 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);
}