Telluria.Utils.Crud
1.0.13
See the version list below for details.
dotnet add package Telluria.Utils.Crud --version 1.0.13
NuGet\Install-Package Telluria.Utils.Crud -Version 1.0.13
<PackageReference Include="Telluria.Utils.Crud" Version="1.0.13" />
paket add Telluria.Utils.Crud --version 1.0.13
#r "nuget: Telluria.Utils.Crud, 1.0.13"
// Install Telluria.Utils.Crud as a Cake Addin #addin nuget:?package=Telluria.Utils.Crud&version=1.0.13 // Install Telluria.Utils.Crud as a Cake Tool #tool nuget:?package=Telluria.Utils.Crud&version=1.0.13
Telluria.Utils.Crud
Generic library for easy creation of CRUD rest APIs with dotnet and EntityFrameworkCore.
Dependencies
- .NET 6.0 (go to site).
- AutoMapper (>= 10.1.1) (go to package).
- Flunt (>= 2.0.5) (go to package).
- LinqKit.Core (>= 1.1.27) (go to package).
- Microsoft.AspNetCore.Mvc.Core (>= 2.2.5) (go to package).
- Microsoft.EntityFrameworkCore.Relational (>= 6.0.0) (go to package).
Instalation:
This package is available through Nuget Packages: https://www.nuget.org/packages/Telluria.Utils.Crud
Nuget
Install-Package Telluria.Utils.Crud
.NET CLI
dotnet add package Telluria.Utils.Crud
How to use:
1. Creating Entity Models
Extend your entities from the "BaseEntity" class located in namespace "Telluria.Utils.Crud.Entities":
using System;
using System.Collections.Generic;
// Import Library
using Telluria.Utils.Crud.Entities;
// Sample Customer Entity (simple)
public class Customer : BaseEntity
{
public string Name { get; set; }
public string Email { get; set; }
public string Address { get; set; }
public string PhoneNumber { get; set; }
...
}
// Sample enum Type
public enum EProductType
{
FEEDSTOCK = 1,
FINAL_PRODUCT,
...
}
// Sample Product Entity (with enum type property)
public class Product : BaseEntity
{
public string Name { get; set; }
public decimal Price { get; set; }
public EProductType Type { get; set; }
...
}
// Sample Order Entity (with relationships)
public class Order : BaseEntity
{
public Guid CustomerId { get; set; }
public Customer Customer { get; set; }
public List<OrderItem> Items { get; set; }
...
}
// Sample OrderItem Entity (with relationships)
public class OrderItem : BaseEntity
{
public Guid OrderId { get; set; }
public Order Order { get; set; }
public Guid ProductId { get; set; }
public Product Product { get; set; }
...
}
2. Mapping Entities
Extend your mapping classes from the "BaseEntityMap<T>" class located in namespace "Telluria.Utils.Crud.Mapping":
// Import Library
using Telluria.Utils.Crud.Mapping;
// Simple mapping
public class CustomerMap : BaseEntityMap<Customer> {}
// Mapping Entity wuth enum type property
public class ProductMap : BaseEntityMap<Product>
{
public override void Configure(EntityTypeBuilder<Product> builder)
{
base.Configure(builder);
// use EnumConverter<T> to map the enum property
builder.Property(t => t.Type)
.HasConversion(EnumConverter<EProductType>());
}
}
// Mapping multiple relationships
public class OrderMap : BaseEntityMap<Order>
{
public override void Configure(EntityTypeBuilder<Order> builder)
{
base.Configure(builder);
// simple relationship
builder.HasOne(t => t.Customer)
.WithMany()
.HasForeignKey(t => t.CustomerId)
.IsRequired();
// list relationship
builder.HasMany(t => t.Items)
.WithOne()
.HasForeignKey(t => t.OrderId)
.IsRequired();
}
}
// Mapping simple relationship
public class OrderItemMap : BaseEntityMap<OrderItem>
{
public override void Configure(EntityTypeBuilder<OrderItem> builder)
{
base.Configure(builder);
// simple relationship
builder.HasOne(t => t.Product)
.WithMany()
.HasForeignKey(t => t.ProductId)
.IsRequired();
}
}
3. Creating an AppDbContext
Extend your AppDbContext classes from the "DbContext" class located in namespace "Microsoft.EntityFrameworkCore", override "OnModelCreating" method and add your Mapping classes to the modelBuilder:
using Microsoft.EntityFrameworkCore;
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) {}
// In this sample we are using Sqlite, but you can use any database you want
protected override void OnConfiguring(DbContextOptionsBuilder options)
=> options.UseSqlite("DataSource=app.db;Cache=Shared");
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.ApplyConfiguration(new CustomerMap());
modelBuilder.ApplyConfiguration(new ProductMap());
modelBuilder.ApplyConfiguration(new OrderMap());
modelBuilder.ApplyConfiguration(new OrderItemMap());
...
}
}
4. Creating the Controllers
Extend your Controllers classes from the "BaseCrudController" class located in namespace "Telluria.Utils.Crud.Controllers":
// Import Library
using Telluria.Utils.Crud.Controllers;
// Customers CRUD controller sample
public class CustomersController : BaseCrudController<Customer> {}
// Products CRUD controller sample
public class ProductsController : BaseCrudController<Product> {}
// Orders CRUD controller sample
public class OrdersController : BaseCrudController<Order> {}
// OrderItems CRUD controller sample
public class OrderItemsController : BaseCrudController<OrderItem> {}
5. Configuring services
In your "Startup.cs" file, import namespace "Telluria.Utils.Crud" and in "ConfigureServices" method add the following:
/* Startup.cs */
// Import Library
using Telluria.Utils.Crud;
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
...
/* --- ADD THIS 3 LINES --- */
services.AddDbContext<AppDbContext>();
services.AddScoped<DbContext, AppDbContext>();
services.AddCrud();
/* ---------------------- */
services.AddControllers();
...
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
...
}
}
Ready to go!
Note: Before running the project, remember to create the database using migrations (or manually, if you prefer)
Using DTOs
This package allows you to implement "RequestDTO" templates for the Create and Update CRUD operations, along with a "ResponseDTO" for all returns:
1. Implementing "RequestDTOs"
Extend your RequestDTOs classes from the "BaseNotifiableRequestDTO<T>" class located in namespace "Telluria.Utils.Crud.DTOs" and override the "Validate" method:
// Import Library
using Telluria.Utils.Crud.DTOs;
// Lets implement a CreateDTO for Customer:
public class CustomerCreateRequestDTO : BaseNotifiableRequestDTO<Customer>
{
// declare properties that you want for the DTO:
public string Name { get; set; }
public string Email { get; set; }
public string Address { get; set; }
public string PhoneNumber { get; set; }
...
public override void Validate()
{
// this library uses Flunt package for validation.
// call "AddNotifications" end use the property "_contract" of
// the base class to generate a Flunt validation contract:
AddNotifications(
_contract
.IsEmail(Email, nameof(Email))
.IsNotEmpty(Name, nameof(Name))
);
}
}
// Same concepts here, but is a UpdateDTO for Customer:
public class CustomerUpdateRequestDTO : BaseNotifiableRequestDTO<Customer>
{
public Guid Id { get; set; }
public string Name { get; set; }
public string Email { get; set; }
public string Address { get; set; }
public string PhoneNumber { get; set; }
public override void Validate()
{
AddNotifications(
_contract
.IsEmail(Email, nameof(Email))
.IsNotEmpty(Name, nameof(Name))
);
}
}
2. Implementing "ResponseDTO"
Extend your ResponseDTO class from the "IResponseDTO<Customer><T>" interface located in namespace "Telluria.Utils.Crud.DTOs":
// Import Library
using Telluria.Utils.Crud.DTOs;
public class CustomerResponseDTO : IResponseDTO<Customer>
{
// declare properties that you want for the DTO:
public Guid Id { get; set; }
public string Name { get; set; }
public string Email { get; set; }
...
}
3. Entering the DTO types in the controller definition
Same as previous Controller definition, but with DTO type parameters:
// Import Library
using Telluria.Utils.Crud.Controllers;
// Pay attention to the order of parameters
public class CustomersController
: BaseCrudController<Customer, CustomerCreateRequestDTO, CustomerUpdateRequestDTO, CustomerResponseDTO>
{
}
Once again, you are ready to go!
Querying and Pagination
The API generated by this library has many features available like: Querying, Pagination and Nested Includes for child Entities/Lists:
Pagination samples
GET /customers?page=2&perPage=20
GET /customers?page=1&perPage=35
Querying samples
- The query has to start with "$(" and ends whith ")"
- The clauses must be separated by ";"
- Operators: "=="" (Equal) ">="" (GreaterThanOrEqual) "<="" (LessThanOrEqual) ">>"" (GreaterThan) "<<"" (LessThan) "%="" (Contains) "%>"" (In) (for this option, values must be separeted by "|")
GET /customers?where=$(email==jhondoe@gmail.com)
GET /customers?where=$(email%=jhon;name%=jhon)
GET /products?where=$(price>=10;type==FEEDSTOCK)
GET /products?where=$(price<<10)
Nested Includes
You can use this if there are foreign key constraints for the related items:
GET /orders?include=items
GET /orders?include=items.product
GET /orders?include=customer
GET /orders?include=items.product&include=customer
All previous itens can be used together
GET /orders?page=1&perPage=35&include=items.product&include=customer&where=$(customerId==<SOME_GUID>)
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. 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. |
-
net6.0
- AutoMapper (>= 10.1.1)
- Flunt (>= 2.0.5)
- LinqKit.Core (>= 1.1.27)
- Microsoft.AspNetCore.Mvc.Core (>= 2.2.5)
- Microsoft.EntityFrameworkCore.Relational (>= 6.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.0.12 | 848 | 5/24/2024 |
2.0.11 | 122 | 5/22/2024 |
2.0.10 | 99 | 5/21/2024 |
2.0.9 | 124 | 4/30/2024 |
2.0.8 | 88 | 4/30/2024 |
2.0.7 | 92 | 4/29/2024 |
2.0.6 | 95 | 4/27/2024 |
2.0.5 | 100 | 4/25/2024 |
2.0.4 | 90 | 4/24/2024 |
2.0.3 | 283 | 4/16/2024 |
2.0.2 | 144 | 4/9/2024 |
2.0.1 | 538 | 2/5/2024 |
2.0.0 | 264 | 1/24/2024 |
1.27.11 | 573 | 10/31/2023 |
1.27.10 | 667 | 9/28/2023 |
1.27.9 | 850 | 8/18/2023 |
1.27.8 | 689 | 7/12/2023 |
1.27.7 | 538 | 7/12/2023 |
1.27.6 | 535 | 7/7/2023 |
1.27.4 | 2,468 | 6/20/2023 |
1.27.3 | 496 | 6/19/2023 |
1.27.2 | 513 | 6/15/2023 |
1.27.1 | 465 | 6/15/2023 |
1.26.0 | 3,185 | 9/13/2022 |
1.25.15 | 861 | 7/15/2022 |
1.24.15 | 798 | 7/13/2022 |
1.23.15 | 802 | 6/23/2022 |
1.22.15 | 766 | 6/22/2022 |
1.21.15 | 807 | 6/20/2022 |
1.20.15 | 758 | 6/17/2022 |
1.19.15 | 744 | 6/17/2022 |
1.18.15 | 789 | 6/16/2022 |
1.17.15 | 758 | 6/16/2022 |
1.16.15 | 702 | 6/16/2022 |
1.15.15 | 741 | 6/16/2022 |
1.14.15 | 738 | 6/15/2022 |
1.13.15 | 701 | 6/15/2022 |
1.12.15 | 786 | 6/7/2022 |
1.11.15 | 744 | 5/31/2022 |
1.10.15 | 758 | 5/11/2022 |
1.9.15 | 770 | 5/2/2022 |
1.8.15 | 876 | 4/12/2022 |
1.7.15 | 757 | 4/6/2022 |
1.6.15 | 785 | 3/4/2022 |
1.5.14 | 791 | 3/3/2022 |
1.4.14 | 775 | 3/2/2022 |
1.3.14 | 812 | 2/28/2022 |
1.2.14 | 739 | 2/28/2022 |
1.1.13 | 1,136 | 12/1/2021 |
1.0.13 | 2,965 | 11/25/2021 |
1.0.12 | 3,000 | 11/25/2021 |
1.0.5 | 3,275 | 11/25/2021 |
1.0.0 | 681 | 11/9/2021 |