TCM.Core 1.0.21

TCM.Core

Shared infrastructure library for the TCM ecosystem. Provides the foundational data access, authentication, caching, validation, auditing, logging, and utility layers consumed by all TCM services.

Features

• Generic Repository Pattern — CRUD operations with paging, stored procedure support, and bulk extensions
• MediatR Pipeline Behaviors — Automatic request validation (FluentValidation) and response caching
• Distributed Caching — Unified interface supporting both Redis and in-memory backends
• Keycloak Integration — OAuth2/OIDC authentication, user management, and UMA permission checks
• JWT Authentication — Pre-configured JWT Bearer setup with API versioning and Swagger
• Audit Logging — Automatic create/update/delete audit trail on all entities
• Excel Import/Export — EPPlus and NPOI based helpers with column attribute mapping
• Barcode Generation — Code128 barcode rendering via ZXing.Net and SkiaSharp
• Serilog Logging — Structured logging to SQL Server and Elasticsearch
• REST Client Helper — Typed HTTP client wrapper for external service calls
• Type Discovery — Reflection-based discovery of classes by interface or base type
• System Settings Module — Shared DB-backed key/value settings with cache, CRUD service, and common controller

Installation

dotnet add package TCM.Core

Requirements

• .NET 7.0 or .NET 9.0
• SQL Server
• Redis (optional — falls back to in-memory cache)
• Keycloak server (optional — for OAuth2/OIDC)

Getting Started

Register Services

// Program.cs
builder.Services.AddTCMCore(builder.Configuration);

This registers:

• EF Core DbContext
• Generic repositories
• Caching services (Redis or memory based on config)
• Keycloak / JWT authentication
• MediatR with validation and caching behaviors
• FluentValidation
• AutoMapper
• Serilog

Shared System Settings

TCM.Core now includes a reusable SystemSetting module for cross-service runtime configuration.

Data model

SystemSetting stores:

• FieldName (unique key, ex: Claude.PrimaryModel)
• FieldValue (string, supports primitive values or JSON payload)
• Description (optional admin hint)
• SettingGroup (admin grouping, ex: Claude, Extraction)
• IsSecret (when true, values are masked in API responses)

Contracts

• ISystemSettingResolver for runtime reads:
  • GetStringAsync, GetIntAsync, GetDecimalAsync, GetBoolAsync, GetJsonAsync<T>
  • GetGroupAsync
• ISystemSettingCrudService for admin CRUD/upsert operations
• ISystemSettingDbContext for host DbContext integration

Registration

In host modules, register shared settings once:

services.AddSystemSettingShared(configuration);
services.AddScoped<ISystemSettingDbContext>(sp => sp.GetRequiredService<YourDbContext>());

AddSystemSettingShared registers:

• SystemSettingService
• ISystemSettingResolver
• ISystemSettingCrudService
• SystemSettingOptions (SystemSetting:CacheMinutes, default 30)

Common API Controller

TCM.Core.Controllers.v1.SystemSettingsController provides:

• GET /api/v1/SystemSettings
• GET /api/v1/SystemSettings/{fieldName}
• POST /api/v1/SystemSettings
• PUT /api/v1/SystemSettings/{fieldName}
• DELETE /api/v1/SystemSettings/{fieldName}
• POST /api/v1/SystemSettings/upsert

To expose shared controller assembly in host apps:

builder.Services.AddControllers()
    .AddCoreSharedControllers();

Cache behavior

• Cache key pattern:
  • SystemSetting:Key:{fieldName}
  • SystemSetting:Group:{settingGroup}
• Reads are cache-first, then DB fallback
• Writes invalidate related key/group cache entries

Configuration

{
  "CacheSettings": {
    "RedisUrl": "localhost:6379",
    "Password": "",
    "Ssl": false,
    "UseMemoryCache": false
  },
  "KeycloakSettings": {
    "ServerUrl": "https://auth.example.com",
    "Realm": "tcm",
    "ClientId": "tcm-api",
    "AdminUsername": "admin",
    "AdminPassword": "admin"
  }
}

Define an Entity

public class Product : BaseEntity
{
    public string Name { get; set; }
    public decimal Price { get; set; }
}

BaseEntity provides: Id (Guid), IsActive, CreatedDate, CreatedUserId, ModifiedDate, ModifiedUserId.

Use a Repository

public class ProductService
{
    private readonly IGenericRepositoryAsync<Product> _repository;

    public ProductService(IGenericRepositoryAsync<Product> repository)
    {
        _repository = repository;
    }

    public async Task<Product> GetByIdAsync(Guid id)
        => await _repository.GetByIdAsync(id);

    public async Task<IReadOnlyList<Product>> GetAllAsync()
        => await _repository.GetAllAsync();
}

Cacheable MediatR Query

public class GetProductQuery : IRequest<Response<ProductDto>>, ICacheableMediatrQuery
{
    public Guid Id { get; set; }
    public bool BypassCache { get; set; }
    public string CacheKey => $"Product_{Id}";
    public TimeSpan? SlidingExpiration => TimeSpan.FromMinutes(10);
}

Excel Export

public class ProductExcelModel : BaseExcelModel
{
    [ExcelColumn("Product Name", 1)]
    public string Name { get; set; }

    [ExcelColumn("Price", 2)]
    public decimal Price { get; set; }
}

var bytes = ExportExcelHelper.Export(products);

Project Structure

TCM.Core/
├── Controllers/        # Shared API controllers (e.g. SystemSettingsController)
├── Attributes/         # Custom ASP.NET attributes (Permission, ForbidError)
├── Audits/             # Audit trail service
├── Behaviours/         # MediatR pipeline behaviors (Validation, Caching)
├── Caching/            # ICachingService, Redis/Memory implementation
├── Contexts/           # TCDbContext (abstract EF Core base), ElasticContext
├── Converters/         # JSON converters (DateOnly, TimeOnly)
├── Definitions/        # Business enums and constants
├── EntityConfigurations/ # EF Core Fluent API base configurations
├── Exceptions/         # ApiException, ValidationException
├── Extensions/         # String, DateTime, QueryableExtensions + DI setup
├── Helpers/            # Excel, Barcode, REST client, TypeFinder, etc.
├── Logging/            # TCLog static facade
├── Middlewares/        # ErrorHandlerMiddleware
├── Models/             # BaseEntity, Response<T>, PagedResponse<T>, DTOs
├── Repositories/       # IGenericRepositoryAsync + implementations
├── Services/           # IAuthenticatedUserService, IKeycloakService, system setting services
└── Settings/           # CacheSettings, KeycloakSettings, SystemSettingOptions

Key Dependencies