DotNetBrightener.WebApi.GenericCRUD.Generator 2024.0.14.1-preview

Snippet

Code Generator for Centralized CRUD WebAPI in ASP.NET Core Applications

© 2024 DotNet Brightener. admin@dotnetbrightener.com

Instruction

Most applications rely on CRUD operations. This tool aids in generating WebAPI controllers and DataService interfaces/classes using the DotNetBrightener.WebApi.GenericCRUD and DotNetBrightener.DataAccess.Abstractions libraries.

Specifically, DotNetBrightener.WebApi.GenericCRUD provides core CRUD functionalities, exposing them as WebAPI controllers, while DotNetBrightener.DataAccess.Abstractions facilitates the database access layer performing these CRUD operations.

Using this generator tool eliminates the need for manually implementing CRUD WebAPI controllers and Data Access Service classes/interfaces for each domain entity in your application. Upon building the application in Visual Studio, the necessary classes are automatically generated for your project, streamlining your workflow.

Getting Started

Create new project

You can create the project in Visual Studio for your convenience. You can put everything into one single WebAPI project, but it's recommended not to do that, instead, you should separate the project into different libraries. The suggestion is as the following table

If you like CLI, you can follow the instruction below.

1. Create a new .NET 8 WebAPI project:

dotnet new webapi -n {your-project-name} -f net8.0
dotnet new classlib -n {your-project-name}.Database -f net8.0
dotnet new sln --name {your-project-name}
dotnet sln {your-project-name}.sln add {your-project-name}\\{your-project-name}.csproj
dotnet sln {your-project-name}.sln add {your-project-name}.Database\\{your-project-name}.Database.csproj

2. If needed to separate the entity definitions to a different library, create new class library project

dotnet new classlib -n {your-project-name}.Core -f net8.0
dotnet sln {your-project-name}.sln add {your-project-name}.Core\\{your-project-name}.Core.csproj

3. If needed to separate the service layer, create new class library project

dotnet new classlib -n {your-project-name}.Services -f net8.0
dotnet sln {your-project-name}.sln add {your-project-name}.Services\\{your-project-name}.Services.csproj

Now you can open the solution in Visual Studio.

Add Generic CRUD and its Generator Library

1. Add needed libraries

Add the following packages to the projects, following the instruction below

2. Update the settings to enable code generator

Open the csproj file where you referenced the DotNetBrightener.WebApi.GenericCRUD.Generator library, and update the <PackageReference> of that package with the following

<ItemGroup>
	<PackageReference Include="DotNetBrightener.WebApi.GenericCRUD.Generator"
					  Version="{current-version-of-the-library}"
					  OutputItemType="Analyzer"
					  ReferenceOutputAssembly="false" />
</ItemGroup>

The change is to add

	OutputItemType="Analyzer"
	ReferenceOutputAssembly="false"

to the XML tag, which enables the auto generate code for the project.

Create first entity

The entities must inherit from BaseEntity or BaseEntityWithAuditInfo from the DotNetBrightener.DataAccess.Abstractions library. Create any entity into the Core or Entity project.

Example:

using DotNetBrightener.DataAccess.Models;
 
namespace CRUDWebApiWithGeneratorDemo.Core.Entities;
 
public class Product: BaseEntity
{
    [MaxLength(255)]
    public string Name { get; set; }
 
	// omitted code
}

The Entity/Core project should only contain the entities without any other logics

Configure Code Generator for Service Project

Define auto-generate entities registration class

At the root of Service project, create a class CRUDDataServiceGeneratorRegistration.cs with the following content

using CRUDWebApiWithGeneratorDemo.Core.Entities;
 
namespace CRUDWebApiWithGeneratorDemo.Services;
 
public class CRUDDataServiceGeneratorRegistration
{
    public List<Type> Entities =
    [
		// provide all entities that need to generate CRUD data service for
        typeof(Product),
        typeof(ProductCategory)
    ];
}

The class name CRUDDataServiceGeneratorRegistration is vital as the generator library relies on it to discern what needs generating.

In the Entities property of this class, ensure to include all entities for which CRUD data service interfaces and classes are required.

Configure Code Generator for WebAPI Project

Define auto-generate entities registration class

At the root of WebAPI project, create a class CRUDWebApiGeneratorRegistration.cs with the following content

public class CRUDWebApiGeneratorRegistration
{
	// reference the CRUDDataServiceGeneratorRegistration from Service project
    Type DataServiceRegistrationType = typeof(CRUDDataServiceGeneratorRegistration);
 
    public List<Type> Entities =
    [
		// provide all entities that need to generate CRUD API Controllers for
		// Some entities related to Authorization / Authentication / Security should be ignored
        typeof(Product),
        typeof(ProductCategory)
    ];
}

The class name CRUDWebApiGeneratorRegistration is vital as the generator library relies on it to discern what needs generating.

In the Entities property of this class, ensure to include all entities for which CRUD Web API Controllers are required.

Other configurations for Web API Project

In Program.cs or Startup.cs, you'll need to add the registration for the generated DataService interfaces into the ServiceCollection or Dependencies Container of your choice.

// register the generated data services
builder.Services.AddScoped<IProductCategoryDataService, ProductCategoryDataService>();
builder.Services.AddScoped<IProductDataService, ProductDataService>();
// other service registration

One good approach is to implement a mechanism in your application to automatically detect the DataService classes in your Service project and register them automatically to the ServiceCollection or your dependencies container.

Database Migration

This code generator instruction does not cover how to implement database migration. You will need to follow instruction from Microsoft Entity Framework or the ORM library that you use for your project.

Build and Run Project

As you followed the instruction so far, upon building and running the project, the needed classes will be automatically generated. By default, .NET WebAPI project includes the OpenAPI library, which will detect the available APIs and you can see the following when the project is launch:

![[swagger_screenshot.png]]

Auto-Generated Web APIs

The generator will generate the following APIs for each entity type registered in the registration.

GET /api/{entity}

• Retrieve list of records of the entity type, and satisfies the filter, if provided

This API accepts the following query string parameters:

column_name is case-sensitive. You will need to obtain the correct name of the column from the response body.

There is no OR operator supported at the moment, because the nature of HTTP query strings combined by & operator. Therefore, only AND operator can be supported.

You can use custom queries for the {column_name} parameter with different operators. Here's a table explaining how to use them:

The follow operators are supported in most of all data types, string, int, long, float, double

The following operators are supported for string data type.

The following operators are supported for int, float, double, decimal, datetime and datetimeoffset data type.

GET /api/{entity}/{id}

• Get the record of the entity type by id

This API accepts the following query string parameters

POST /api/{entity}

• Create a new record of the entity type

PUT /api/{entity}/{id}

• Update entity by id

The body of the request can be part of the entity. Only the provided fields in the body will be updated to the entity specified by the id

DELETE /api/{entity}/{id}

• Delete entity by id

PUT /api/{entity}/{id}/undelete

• Restore the deleted record of the entity by id