ef.qore.BaseQuc 1.0.22

# BaseQuc Consumer Guide

A lightweight .NET Core framework for CRUD, caching, audit-trail, and message-broker integration. 
This guide shows how to **install**, **configure**, and **consume** BaseQuc in the own microservice.

---

## Prerequisites

- [.NET 8.0 SDK+](https://dotnet.microsoft.com/download)  
- A relational database (e.g. PostgreSQL, SQL Server, MySQL)  
- (Optional) Redis for caching  
- (Optional) Kafka (or other MQ) for events  

---

## 1. Install NuGet Packages

```bash
dotnet add package ef.qore.basequc --version 1.0.20
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package StackExchange.Redis
dotnet add package Confluent.Kafka

2. appsettings.json

{
  "ConnectionStrings": {
    "MasterConnection": "<YOUR_DB_CONN>",
    "SlaveConnection" : "<YOUR_DB_CONN>",
    "Redis"           : "redis:6379"
  },

  "CacheSettings": {
    "Enabled": true,
    "Provider": "Redis",
    "DefaultExpiryMinutes": 30
  },

  "FileLoggingSettings": {
    "EnableFileLogging": true,
    "LogFilePath": "Logs/audit.log"
  },

  "MessageBrokerSettings": {
    "Enabled": true,
    "Provider": "Kafka",
    "ConnectionString": "kafka:9092"
  },

  "KafkaProducerConfig": {
    "bootstrap.servers"        : "kafka:9092",
    "client.id"                : "my-app-producer",
    "acks"                     : "all",
    "enable.idempotence"       : true,
    "message.send.max.retries" : 3,
    "retry.backoff.ms"         : 1000,
    "linger.ms"                : 5
  },

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },

  "AllowedHosts": "*"
}

3. Register Services (Program.cs)

using BaseQuc.Extensions;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

// 1) EF Core DbContexts
builder.Services
    .AddDbContext<MasterDbContext>(opts =>
        opts.UseNpgsql(builder.Configuration.GetConnectionString("MasterConnection")))
    .AddDbContext<SlaveDbContext>(opts =>
        opts.UseNpgsql(builder.Configuration.GetConnectionString("SlaveConnection")));

// 2) BaseQuc Core (Repos & Services)
builder.Services.AddBaseQucCore<MasterDbContext>();

// 3) Caching
builder.Services.AddBaseQucCaching(builder.Configuration);

// 4) Message Broker (default no-op + Kafka override)
builder.Services
    .AddBaseQucMessageBroker(builder.Configuration)
    .AddBaseQucKafkaBroker();

// 5) Your domain registrations
builder.Services
    .AddScoped<IProductsRepository, ProductsRepository>()
    .AddScoped<ProductsCacheService>()
    .AddScoped<IProductsService, ProductsService>();

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

4. Define Your Entity

using BaseQuc.Attributes;
using BaseQuc.Entity;
using BaseQuc.Enums;

namespace MyApp.Entities
{
    [Auditable]
    [Cacheable]
    [Publish(PublishOn = Action.Create | Action.Update | Action.Delete)]
    public class Products : BaseEntity
    {
        public string Name        { get; set; } = "";
        public string Code        { get; set; } = "";
        public ProductType Type   { get; set; }
    }
}

• [Auditable] → writes audit trail
• [Cacheable] → enables read/update/delete caching
• [Publish] → sends events on Create/Update/Delete

5. Repository Implementation

using BaseQuc.Repositories.Interface;
using Microsoft.EntityFrameworkCore;
using MyApp.Entities;

namespace MyApp.Repositories
{
    public class ProductsRepository
        : IBaseRepository<Products, ProductsFilter, MasterDbContext, SlaveDbContext>
    {
        // Inject MasterDbContext & SlaveDbContext
        // Implement GetByIdAsync, AddAsync, UpdateAsync, DeleteAsync,
        // MarkAsDeletedAsync, UpdateStatusAsync, GetAllAsync, GetPagedAsync, etc.
    }
}

6. Cache Service

using BaseQuc.Cache;
using BaseQuc.Cache.Interface;
using MyApp.Entities;

namespace MyApp.Cache
{
    public class ProductsCacheService
        : BaseEntityCacheService<Products>
    {
        protected override string CacheKeyPrefix => nameof(Products);
        public ProductsCacheService(ICacheService cacheService)
            : base(cacheService) { }
    }
}

7. Domain Service

using BaseQuc.Cache.Interface;
using BaseQuc.MessageBroker.Interface;
using BaseQuc.Services;
using Microsoft.Extensions.Options;
using MyApp.Cache;
using MyApp.Entities;
using MyApp.Repositories;
using BaseQuc.Settings;
using BaseQuc.Utilities;

namespace MyApp.Services
{
    public class ProductsService
        : BaseService<
            Products,
            ProductsFilter,
            MasterDbContext,
            SlaveDbContext>,
          IProductsService
    {
        public ProductsService(
            IProductsRepository               repo,
            IStringLocalizer<LanguageResponse> loc,
            IAuditTrailService                auditSvc,
            MasterDbContext                   mCtx,
            SlaveDbContext                    sCtx,
            IOptions<FileLoggingSettings>     logOpts,
            ICacheService                     cacheSvc,
            IOptions<CacheSettings>           cacheOpts,
            ProductsCacheService              cacheEntitySvc,
            IBrokerService                    brokerSvc,
            IOptions<MessageBrokerSettings>   brokerOpts
        ) : base(
                repo, loc, auditSvc, mCtx, sCtx,
                logOpts, cacheSvc, cacheOpts,
                cacheEntitySvc,
                brokerSvc, brokerOpts
            )
        { }
    }
}

8. Web API Controller

using Microsoft.AspNetCore.Mvc;
using MyApp.Entities;
using MyApp.Services;

namespace MyApp.Controllers
{
    [ApiController]
    [Route("api/products")]
    public class ProductsController : ControllerBase
    {
        private readonly IProductsService _svc;
        public ProductsController(IProductsService svc) => _svc = svc;

        [HttpGet("{id}")]
        public async Task<IActionResult> Get(int id)
            => Ok(await _svc.GetByIdAsync(id));

        [HttpPost]
        public async Task<IActionResult> Create(Products p)
        {
            var created = await _svc.SaveAsync(p);
            return CreatedAtAction(nameof(Get), new { id = created.Id }, created);
        }

        [HttpPut("{id}")]
        public async Task<IActionResult> Update(int id, Products p)
        {
            await _svc.UpdateAsync(p, id);
            return NoContent();
        }

        [HttpDelete("{id}")]
        public async Task<IActionResult> Delete(int id)
        {
            await _svc.DeleteAsync(id, user: "system", modifiedByIp: "127.0.0.1");
            return NoContent();
        }
    }
}

9. Run & Verify

1. Start your DB, Redis, and Kafka (e.g. via Docker Compose).
2. dotnet run your API.
3. Test endpoints with Postman or cURL:
   • GET → reads (caches on first hit)
   • PUT → updates (refreshes cache & publishes event)
   • DELETE → deletes (evicts cache & publishes event)
4. Check Redis keys (Products:{id}) and Kafka topic Products for JSON messages.

Enjoy rapid CRUD + caching + messaging with minimal boilerplate!