StorageGenerics 3.0.0-rc2

StorageGenerics

StorageGenerics is a small set of .NET libraries for building reusable CRUD data layers and ASP.NET Core APIs on top of Entity Framework Core. It provides generic repository services, queryable repositories, base API controllers, DTO mapping abstractions, and a matching HTTP client.

The library supports entities with any equatable ID type. Convenience APIs are included for the common long ID case.

License

This repository is licensed under the GNU Affero General Public License, version 3, or (at your option) any later version (AGPL-3.0-or-later).

Full license text is available in https://www.gnu.org/licenses/agpl-3.0.html.

Packages

All projects currently target .NET 10.

Installation

Install only the packages required by your application:

dotnet add package StorageGenerics.Core
dotnet add package StorageGenerics
dotnet add package StorageGenerics.AspNetCore
dotnet add package StorageGenerics.Client

Define an entity

Entities implement IEntity<TId>. Use IEntity when the ID is a long.

using StorageGenerics.Core.Contracts;

public sealed class Product : IEntity
{
    public long Id { get; set; }
    public required string Name { get; set; }
    public decimal Price { get; set; }
}

Register a repository

Repository services use Entity Framework Core's IDbContextFactory<TContext> to create a context for individual CRUD operations. QueryableRepositoryService additionally uses a scoped context for composable queries.

using Microsoft.EntityFrameworkCore;
using StorageGenerics.Core.Contracts;
using StorageGenerics.Services;

builder.Services.AddDbContextFactory<AppDbContext>(options =>
    options.UseSqlite("Data Source=app.db"));

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite("Data Source=app.db"));

builder.Services.AddScoped<IQueryableRepositoryService<Product>,
    QueryableRepositoryService<AppDbContext, Product>>();

You can then inject the repository contract and use its CRUD or query APIs:

public sealed class ProductService(IQueryableRepositoryService<Product> repository)
{
    public ValueTask<Product?> FindAsync(long id, CancellationToken cancellationToken = default) =>
        repository.GetAsync(id, cancellationToken);

    public Task<List<Product>> FindInStockAsync(CancellationToken cancellationToken = default) =>
        repository.QueryAll()
            .Where(product => product.Price > 0)
            .OrderBy(product => product.Name)
            .ToListAsync(cancellationToken);
}

Create a CRUD API

Derive a controller from CrudBaseController<TEntity> to expose conventional endpoints under api/[controller]:

using StorageGenerics.AspNetCore.Controllers;
using StorageGenerics.Core.Contracts;

public sealed class ProductsController(
    IQueryableRepositoryService<Product> repository,
    ILogger<CrudBaseController<Product>> logger)
    : CrudBaseController<Product>(repository, logger)
{
}

The controller provides count, list, page, get-by-ID, exists, create, update, and delete endpoints. Use the ReadCrudBaseController variants for read-only APIs or the CrudDTOBaseController and ReadDTOBaseController variants when API models should be mapped through IMapper<TDto, TEntity>.

Authentication and authorization are intentionally left to the host application. Apply authorization policies to derived controllers before exposing write endpoints.

Use the HTTP client

Register CrudClient<TEntity, TId> with an HttpClient whose base address points to the API:

using StorageGenerics.Client.Clients;
using StorageGenerics.Client.Contracts;

builder.Services.AddHttpClient<ICrudClient<Product, long>, CrudClient<Product, long>>(client =>
    client.BaseAddress = new Uri("https://api.example.com"));

The default route is inferred from the entity name. Override ControllerName or Path in a derived client when the API uses a different route.

Polymorphic entity queries

For Entity Framework Core table-per-hierarchy models, OfOnlyType and ApplyOnlyTypeQueryFilter filter against the Discriminator column so a query returns only the exact requested type rather than its derived types.

Building locally

dotnet restore StorageGenerics.sln
dotnet build StorageGenerics.sln --configuration Release