Muonroi Building Block

Introduction

This library provides entities such as User, Role, Permission, and Language, along with built-in dependency injection, bearer token management, JSON handling utilities, string conversion, and localization for multiple languages. It also sets up linking tables like MUserRoles and MRolePermissions together with token and audit tables. See Database Structure for the full schema. It now also includes a lightweight rule engine that supports strongly typed rules and dynamic JSON workflows. See the Rule Engine Guide for details. The package is designed to accelerate the development of .NET applications following a clean architecture.

Rule Engine Features

• Compose strongly typed IRule<T> classes with dependency ordering and feature toggles.
• Run versioned JSON workflows via RulesEngineService and IRuleSetStore.
• Hook into rule execution with RuleOrchestrator and IHookHandler for logging or audits.
• Sign and verify rule artifacts while emitting OpenTelemetry metrics.
• Generate workflows from existing code with the MR.RuleGen CLI.
• Execute generated workflows at runtime through MR.RuleRuntime.

Prerequisites

• .NET SDK 9.0 or higher must be installed. You can download it from the official website.

Installation

Install the package from NuGet:

dotnet add package Muonroi.BuildingBlock

The command above installs the latest available version. You can also browse the NuGet Gallery to select a specific version or install it via the Visual Studio package manager.

Building from source

If you'd like to contribute or customize the library locally, clone this repository and run:

dotnet build dotnet pack

Quick Start

You can also use the muonroibase.template dotnet template:

dotnet new install muonroibase.template dotnet new muonroibase -n YourNewProjectName -C MyCoreName

See the Samples/Program.cs file for a minimal setup example. Additional samples are provided in the Samples folder:

• MemoryCache demonstrates basic in-memory caching.
• MultiLevelCache shows how to combine memory and distributed caches.
• RedisCache illustrates using Redis as a distributed cache.
• MultipleCache demonstrates using both IMemoryCache and IMultiLevelCacheService.
• HelloRules highlights the built-in rule engine.
• ImportExportRules shows versioned JSON workflows.
• PaymentApproval orchestrates multiple rules for a business scenario.
• AuthAuthzBff shows how to combine authentication, authorization and the BFF pattern.

Project Structure

MuonroiBuildingBlock/ ├── src/ │ ├── Muonroi.BuildingBlock/ │ ├── Muonroi.RuleEngine/ │ ├── Muonroi.Tenancy/ │ ├── Muonroi.Bff/ │ └── Muonroi.Base.Template/ ├── Samples/ ├── docs/ ├── tests/ ├── db/ ├── deploy/ ├── k8s/ └── tools/

Folder	Description
src/	Core source code for the library and related packages. Key projects include Muonroi.BuildingBlock, Muonroi.RuleEngine, Muonroi.Tenancy, Muonroi.Bff, and Muonroi.Base.Template.
Samples/	Standalone examples demonstrating caching, rule engine workflows, BFF patterns, and more.
docs/	DocFX documentation and guides covering configuration, permissions, rules, and other topics.
tests/	Unit and integration tests for each module.
db/	Database migration scripts and schema definitions.
deploy/	Deployment scripts and release tooling.
k8s/	Kubernetes manifests and configuration files.
tools/	Development utilities and helper scripts.

Usage Guide

1. Configuring Program.cs

Here's how to configure your Program.cs file to use the library's features:

using System.Reflection; using Muonroi.BuildingBlock.External; using Muonroi.BuildingBlock.External.Common.Constants; using Muonroi.BuildingBlock.External.Cors; using Muonroi.BuildingBlock.External.DI; using Muonroi.BuildingBlock.External.Entity; using Muonroi.BuildingBlock.External.Entity.DataSample; using Muonroi.BuildingBlock.External.Logging; using Muonroi.BuildingBlock.External.Messaging; using Muonroi.BuildingBlock.External.Caching.Distributed.MultiLevel; using Muonroi.BuildingBlock.External.Grpc; using Muonroi.BuildingBlock.External.Consul; using Serilog; // Replace with your project's using statements // using YourProject.Data; // using YourProject.Permissions; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); Assembly assembly = Assembly.GetExecutingAssembly(); ConfigurationManager configuration = builder.Configuration; builder.AddAppConfiguration(); builder.AddAutofacConfiguration(); builder.Host.UseSerilog((context, services, loggerConfiguration) => { MSerilogAction.Configure(context, services, loggerConfiguration, false); }); Log.Information("Starting {ApplicationName} API up", builder.Environment.ApplicationName); try { IServiceCollection services = builder.Services; // Register services services.AddApplication(assembly); services.AddInfrastructure(configuration); services.SwaggerConfig(builder.Environment.ApplicationName); services.AddScopeServices(typeof(<YourDbContext>).Assembly); services.AddValidateBearerToken<<YourDbContext>, MTokenInfo, <YourPermissionEnum>>(configuration); services.AddDbContextConfigure<<YourDbContext>, <YourPermissionEnum>>(configuration); services.AddCors(configuration); services.AddPermissionFilter<<YourPermissionEnum>>(); services.ConfigureMapper(); // Optional Integrations services.AddMultiLevelCaching(configuration); services.AddMessageBus(configuration, assembly); services.AddGrpcServer(); services.AddServiceDiscovery(configuration, builder.Environment); services.AddObservability(configuration); WebApplication app = builder.Build(); await app.UseServiceDiscoveryAsync(builder.Environment); app.UseCors("MAllowDomains"); app.UseDefaultMiddleware<<YourDbContext>, <YourPermissionEnum>>(); app.AddLocalization(assembly); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.ConfigureEndpoints(); app.MigrateDatabase<<YourDbContext>>(); await app.RunAsync(); } catch (Exception ex) { Log.Fatal(ex, "Unhandled exception: {Message}", ex.Message); } finally { Log.Information("Shut down {ApplicationName} complete", builder.Environment.ApplicationName); await Log.CloseAndFlushAsync(); }

2. Example appsettings.json Configuration

Here's a comprehensive example of the appsettings.json configuration:

{ "DatabaseConfigs": { "DbType": "Sqlite", "ConnectionStrings": { "SqliteConnectionString": "Your encrypted connection string by secret key", "MongoDbConnectionString": "Your encrypted connection string by secret key", "SqlServerConnectionString": "Your encrypted connection string by secret key", "MySqlConnectionString": "Your encrypted connection string by secret key", "PostgreSqlConnectionString": "Your encrypted connection string by secret key" } }, "ApiKey": "", "CacheConfigs": { "CacheType": "MultiLevel" }, "RuleStore": { "RootPath": "rules", "UseContentRoot": true }, "LicenseConfigs": { "Mode": "Offline", "LicenseFilePath": "licenses/license.json", "PublicKeyPath": "licenses/public.pem", "FingerprintSalt": "your-salt-here", "EnableChain": true, "ChainStorage": "File", "ChainFilePath": "logs/license-chain.log", "FailMode": "Hard", "EnforceOnDatabase": true, "EnforceOnMiddleware": true, "Online": { "Endpoint": "https://license.example.com/validate", "TimeoutSeconds": 10, "RefreshMinutes": 1440 } }, "RedisConfigs": { "Enable": true, "Host": "Your host encrypted by secret key", "Port": "Your port encrypted by secret key", "Password": "Your password encrypted by secret key", "Expire": 30, "KeyPrefix": "Your prefix encrypted by secret key", "AllMethodsEnableCache": false }, "TokenConfigs": { "Issuer": "https://exampledomain.com", "Audience": "https://searchpartners.exampledomain.com", "SymmetricSecretKey": "Your secret key (at least 32 chars) encrypted by secret key", "UseRsa": true, "ExpiryMinutes": 30, "EnableCookieAuth": true, "CookieName": "AuthToken", "CookieSameSite": "Lax", "PublicKeyPath": "keys/public.pem", "PrivateKeyPath": "keys/private.pem" }, "PaginationConfigs": { "DefaultPageIndex": 1, "DefaultPageSize": 10, "MaxPageSize": 100 }, "ResourceSetting": { "ResourceName": "Resources.ErrorMessages", "lang": "vi-VN" }, "Serilog": { "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File", "Elastic.Serilog.Sinks" ], "MinimumLevel": { "Default": "Information", "Override": { "Microsoft.AspNetCore": "Warning", "System": "Warning" } }, "WriteTo": [ { "Name": "Console" }, { "Name": "File", "Args": { "path": "logs/log-.txt", "rollingInterval": "Day", "formatter": "Serilog.Formatting.Elasticsearch.ElasticsearchJsonFormatter, Serilog.Formatting.Elasticsearch" } }, { "Name": "Elasticsearch", "Args": { "bootstrapMethod": "Silent", "nodes": [ "http://localhost:9200" ], "dataStream": "logs-muonroi-default", "ilmPolicy": "muonroi-policy" } } ], "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ], "Properties": { "Application": "MyApplication" } }, "MAllowDomains": "https://localhost:52182,http://localhost:4200", "GrpcServices": { "Services": { "YourService1": { "Uri": "http://localhost:5001" }, "YourService2": { "Uri": "http://localhost:5002" } } }, "ConsulConfigs": { "ServiceName": "MyService", "ConsulAddress": "http://localhost:8500", "ServiceAddress": "http://localhost", "ServicePort": 5000 }, "MessageBusConfigs": { "BusType": "RabbitMq", "RabbitMq": { "Host": "localhost", "VirtualHost": "/", "Username": "guest", "Password": "guest" }, "Kafka": { "Host": "localhost:9092", "Topic": "sample-topic", "GroupId": "sample-group" } }, "BackgroundJobConfigs": { "JobType": "Hangfire", "ConnectionString": "Your job storage connection string" }, "KubernetesConfigs": { "ClusterType": "K8s", "ClusterEndpoint": "https://your-cluster-api" }, "OpenTelemetry": { "ServiceName": "MyService", "OtlpEndpoint": "http://localhost:4317" }, "SecretKey": "Your secret key used to encrypt important values", "EnableEncryption": true }

3. Providing Resource Files

Create a Resources directory in your project and place localization JSON files inside it. Each file should follow the pattern ErrorMessages-<culture>.json (e.g., ErrorMessages-en-US.json) and contain key-value pairs of error codes and messages. Ensure the ResourceSetting.ResourceName value in appsettings.json matches the base file name.

Main Components

• Entities: Core data models like MUser, MRole, MPermission, and MLanguage.
• Dependency Injection: Pre-configured DI using Autofac for managing application services and lifecycles.
• Authentication & Authorization: Robust token-based security with JWT, refresh tokens, and a flexible permission system.
• Data Access: Generic repositories (MRepository<T>) and query classes (MQuery<T>) for Entity Framework Core, along with Dapper integration for performance-critical queries.
• Auto-CRUD API: Automatically generates standard CRUD endpoints (GET, POST, PUT, DELETE) for any entity inheriting from MEntity.
• Caching: Multi-level caching support (in-memory and Redis) to improve performance.
• Rule Engine: Compose strongly typed IRule<T> classes and dynamic JSON workflows with dependency ordering and feature toggles.
• Service Discovery: Consul integration for registering and discovering services in a microservices environment.
• Message Bus: MassTransit integration for both RabbitMQ and Kafka to enable asynchronous communication and Saga patterns.
• Background Jobs: Configuration helpers for background job schedulers like Hangfire or Quartz.
• gRPC: Helpers to easily configure gRPC servers and clients.
• Logging: Centralized logging with Serilog, including out-of-the-box support for Elasticsearch.
• Cryptography: MCryptographyExtension uses SHA-256 for secure hashing and AES for configuration encryption.
• Localization: Built-in support for multiple languages using JSON resource files.
• License (preview): Optional offline/online license validation with fingerprint-based action chaining.

Rule Engine

The Muonroi.RuleEngine packages provide a flexible way to evaluate business rules. Rules implement IRule<T> and can declare dependencies, hook points, and optional feature flags. JSON workflows can be loaded at runtime through RulesEngineService, and results are collected in a FactBag for later rules.

For projects with existing conditional logic, the MR.RuleGen CLI can generate workflow definitions automatically. At runtime, MR.RuleRuntime loads these workflows, registers custom types and actions, and executes them against supplied parameters.

services.AddRuleEngine().AddRulesFromAssemblies(typeof(Program).Assembly);

For practical examples see the HelloRules, ImportExportRules, and PaymentApproval samples or read the Rule Engine Guide.

Integrations

Redis Caching

Configure caching via CacheConfigs and RedisConfigs in your settings.

// In Program.cs services.AddMultiLevelCaching(configuration);

gRPC Integration

Use helpers in External/Grpc to configure gRPC. The GrpcHandler class provides extension methods for registering servers and clients from appsettings.json.

Consul Integration

Service discovery support is provided in External/Consul. The ConsulHandler registers and deregisters your service with Consul automatically. Call AddServiceDiscovery and UseServiceDiscoveryAsync in Program.cs.

License System

The library includes a flexible license system with three tiers. By default, the library runs in FREE mode with no configuration required.

License Tiers Comparison

Feature	Free	Licensed	Enterprise
Price	Free	Paid	Paid
Database Operations	✅ Full CRUD	✅ Full CRUD	✅ Full CRUD
HTTP Requests	✅ Unlimited	✅ Unlimited	✅ Unlimited
Authentication/JWT	✅ Full	✅ Full	✅ Full
Multi-Tenancy	❌	✅	✅
Advanced Auth (RBAC+)	❌	✅	✅
Rule Engine	❌	✅	✅
gRPC Integration	❌	✅	✅
Message Bus (Kafka/RabbitMQ)	❌	✅	✅
Distributed Cache	❌	✅	✅
Audit Trail (Chain Logging)	❌	✅	✅
Anti-Tampering Protection	❌	Optional	✅
All Future Features	❌	❌	✅ (* wildcard)
License Validation	None	Offline/Online	Offline/Online

Configuration Examples

1. FREE Mode (Default - No configuration needed)

{ "LicenseConfigs": { // Empty or omit entirely - FREE mode is automatic }, "EnableEncryption": false }

2. Licensed Mode (Offline - with license file)

{ "LicenseConfigs": { "Mode": "Offline", "LicenseFilePath": "licenses/license.json", "PublicKeyPath": "licenses/public.pem", "EnableChain": true, "ChainStorage": "File", "ChainFilePath": "logs/license-chain.log", "FailMode": "Hard", "EnforceOnDatabase": true, "EnforceOnMiddleware": true } }

3. Licensed Mode (Online - with license server)

{ "LicenseConfigs": { "Mode": "Online", "LicenseFilePath": "licenses/license.json", "EnableChain": true, "FailMode": "Hard", "EnforceOnDatabase": true, "EnforceOnMiddleware": true, "Online": { "Endpoint": "https://license.muonroi.com/api", "TimeoutSeconds": 10, "RefreshMinutes": 1440 } } }

4. Enterprise Mode (Full features)

{ "LicenseConfigs": { "Mode": "Online", "LicenseFilePath": "licenses/license.json", "EnableChain": true, "ChainStorage": "File", "FailMode": "Hard", "EnforceOnDatabase": true, "EnforceOnMiddleware": true, "EnableAntiTampering": true, "Online": { "Endpoint": "https://license.muonroi.com/api", "TimeoutSeconds": 10, "RefreshMinutes": 60 } } }

License File Format (license.json)

{ "LicenseId": "LIC-XXXX-XXXX-XXXX", "ProjectId": "your-project-id", "TenantId": "your-tenant-id", "AllowedFeatures": ["multi-tenant", "advanced-auth", "rule-engine", "grpc", "message-bus", "distributed-cache"], "NotBefore": "2024-01-01T00:00:00Z", "ExpiresAt": "2025-01-01T00:00:00Z", "Signature": "base64-encoded-signature" }

For Enterprise tier, use "AllowedFeatures": ["*"] to enable all features.

Configuration Options Reference

Option	Type	Default	Description
Mode	Offline/Online	Offline	License validation mode
LicenseFilePath	string	null	Path to license.json file
PublicKeyPath	string	null	Path to public key for signature verification
EnableChain	bool	false	Enable action audit trail
ChainStorage	None/File	None	Where to store audit logs
FailMode	Soft/Hard	Soft	Soft: log only, Hard: throw exception
EnforceOnDatabase	bool	false	Check license on DB operations
EnforceOnMiddleware	bool	false	Check license on HTTP requests
EnableAntiTampering	bool	false	Enable runtime integrity checks
Online.Endpoint	string	null	License server URL
Online.TimeoutSeconds	int	10	Server request timeout
Online.RefreshMinutes	int	1440	License refresh interval

Obtaining a License

Visit https://muonroi.com/pricing for license options.

Message Bus (Kafka/RabbitMQ)

Configure your message broker via MessageBusConfigs. The helper in External/Messaging uses MassTransit to select the broker. Register consumers and sagas easily:

// In Program.cs services.AddMessageBus(configuration, Assembly.GetExecutingAssembly(), cfg => { /* Optional Saga/Consumer configuration */ });

Use PublishWithAuthContext on IPublishEndpoint to automatically include authentication headers when publishing messages.

Background Job Configuration

Configure background jobs using the BackgroundJobConfigs section. Choose Hangfire or Quartz and specify a connection string for job storage.

// Example for Hangfire with SQL Server services.AddHangfire(x => x.UseSqlServerStorage(configuration["BackgroundJobConfigs:ConnectionString"])); app.UseHangfireDashboard(); BackgroundJob.Enqueue(() => Console.WriteLine("Hello from Hangfire"));

Kubernetes Integration

Specify deployment details for k8s or k3s clusters under KubernetesConfigs, including the cluster type and API endpoint.

Documentation

This project uses DocFX to generate documentation.

• To build the documentation, run: docfx build
• To preview the documentation locally, run: docfx serve _site

For more details, see the guides in the docs directory:

• Permission System Guide
• Permission Tree Guide
• Rule Engine Guide
• Rule Rollout Guide
• Rule Governance Guide
• Data Layer Guide
• Database Structure
• Gateway Configuration
• Multi-Tenant Guide
• Cache Guide
• Token Guide
• Appsettings Guide
• Background Jobs Guide
• Quickstart: Multi-Tenant API with JWT & RBAC
• CI/CD with Docker and Kubernetes
• NRules Integration
• ASVS Checklist

ASVS Pre-Merge Checklist

• Security Configuration (V14) – verify secure configuration and secret management.
• Input Validation (V5) – validate and sanitize all inputs.
• Authorization (V4) – enforce RBAC and deny by default.

For a detailed checklist see docs/asvs-checklist.md.

Documentation Index

For a complete list of guides, visit the Documentation Hub.

• Essentials: Getting Started | Appsettings | Architecture
• Security: Auth Module | Permissions | Multi-Tenant
• Features: Auto-CRUD | Rule Engine | Auto-CRUD + Rules | Caching
• Ops: Docker & K8s | Observability

Formatting

Run dotnet format Muonroi.BuildingBlock.sln to apply the coding style defined in .editorconfig.

Contribution

Please read CONTRIBUTING.md for detailed guidelines on how to fork the project, run tests, and format your code. Feel free to submit pull requests or open issues on GitHub to contribute or report bugs for this project.

License

This library is licensed under the MIT License. Please see the LICENSE file for more details.