Muonroi.BuildingBlock 1.6.21

.NET 9.0 This package targets .NET 9.0. The package is compatible with this framework or higher. 
dotnet add package Muonroi.BuildingBlock --version 1.6.21
                    


                    

                
NuGet\Install-Package Muonroi.BuildingBlock -Version 1.6.21
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Muonroi.BuildingBlock" Version="1.6.21" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Muonroi.BuildingBlock" Version="1.6.21" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Muonroi.BuildingBlock" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Muonroi.BuildingBlock --version 1.6.21
                    


                    

                
#r "nuget: Muonroi.BuildingBlock, 1.6.21"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Muonroi.BuildingBlock@1.6.21
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Muonroi.BuildingBlock&version=1.6.21
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Muonroi.BuildingBlock&version=1.6.21
                    


                            Install as a Cake Tool

Muonroi Building Block

Ask DeepWiki

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"
  },
  "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",
    "SigningKeys": "",
    "UseRsa": true,
    "ExpiryMinutes": 30,
    "EnableCookieAuth": true,
    "CookieName": "AuthToken",
    "CookieSameSite": "Lax",
    "PublicKey": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----",
    "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...-----END RSA PRIVATE KEY-----"
  },
  "PaginationConfigs": {
    "DefaultPageIndex": 1,
    "DefaultPageSize": 10,
    "MaxPageSize": 100
  },
  "ResourceSetting": {
    "ResourceName": "Resources.ErrorMessages",
    "lang": "vi-VN"
  },
  "Serilog": {
    "Using": [ "Serilog.Sinks.Console", "Elastic.Serilog.Sinks" ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft.AspNetCore": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": { "path": "logs/log-.json", "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.
  • 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.

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.

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:

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.

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.

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
1.6.21 45 1/4/2026
1.6.20 50 1/2/2026
1.6.19 50 1/2/2026
1.6.16 48 1/1/2026
1.6.15 46 12/29/2025
1.6.14 48 12/29/2025
1.6.13 43 12/29/2025
1.6.12 42 12/29/2025
1.6.11 42 12/29/2025
1.6.10 45 12/29/2025
1.6.9 41 12/28/2025
1.6.8 43 12/27/2025
1.6.7.1 125 8/17/2025
1.6.7 121 8/17/2025
1.6.6 113 8/17/2025
1.6.5 151 7/27/2025
1.6.4 550 7/23/2025
1.6.3 229 7/20/2025
1.6.2 140 6/22/2025
1.6.1 318 6/10/2025
1.6.0 150 6/7/2025
1.5.11 258 4/29/2025
1.5.10 245 4/17/2025
1.5.9.9 286 3/31/2025
1.5.9.8 526 3/25/2025
1.5.9.7 238 3/17/2025
1.5.9.6 222 3/13/2025
1.5.9.5 205 3/9/2025
1.5.9.4 276 3/6/2025
1.5.9.3 275 3/5/2025
1.5.9.2 187 2/23/2025
1.5.9.1 257 2/18/2025
1.5.9 169 2/17/2025 1.5.9 is deprecated.
1.5.8 173 2/11/2025 1.5.8 is deprecated.
1.5.7 196 2/11/2025 1.5.7 is deprecated.
1.5.6 198 2/9/2025 1.5.6 is deprecated.
1.5.5 211 2/9/2025 1.5.5 is deprecated.
1.5.4 247 2/5/2025 1.5.4 is deprecated.
1.5.3 228 2/3/2025 1.5.3 is deprecated.
1.5.2 237 2/3/2025 1.5.2 is deprecated.
1.5.1.1 254 2/2/2025 1.5.1.1 is deprecated.
1.5.1 210 2/2/2025 1.5.1 is deprecated.
1.5.0 229 1/24/2025 1.5.0 is deprecated.
1.4.9 205 1/24/2025 1.4.9 is deprecated.
1.4.8 188 1/23/2025 1.4.8 is deprecated.
1.4.7 231 11/30/2024 1.4.7 is deprecated.
1.4.6 188 11/30/2024 1.4.6 is deprecated.
1.4.5 219 11/30/2024 1.4.5 is deprecated.
1.4.4 197 11/26/2024 1.4.4 is deprecated.
1.4.3 221 11/23/2024 1.4.3 is deprecated.
1.4.2 194 11/19/2024 1.4.2 is deprecated.
1.4.1 207 11/16/2024 1.4.1 is deprecated.
1.4.0 197 11/16/2024 1.4.0 is deprecated.
1.3.9 222 11/15/2024 1.3.9 is deprecated.
1.3.8 219 11/15/2024 1.3.8 is deprecated.
1.3.7 224 11/15/2024 1.3.7 is deprecated.
1.3.6 215 11/11/2024 1.3.6 is deprecated.
1.3.5 205 11/11/2024 1.3.5 is deprecated.
1.3.4 205 11/11/2024 1.3.4 is deprecated.
1.3.3 227 11/10/2024 1.3.3 is deprecated.
1.3.2 188 11/10/2024 1.3.2 is deprecated.
1.3.1 214 11/10/2024 1.3.1 is deprecated.
1.3.0 229 11/10/2024 1.3.0 is deprecated.
1.2.9 221 11/8/2024 1.2.9 is deprecated.
1.2.8 250 10/27/2024 1.2.8 is deprecated.
1.2.7 244 10/27/2024 1.2.7 is deprecated.
1.2.6 281 10/27/2024 1.2.6 is deprecated.
1.2.5 258 10/27/2024 1.2.5 is deprecated.
1.2.4 281 10/26/2024 1.2.4 is deprecated.
1.2.3 267 10/25/2024 1.2.3 is deprecated.
1.2.2 263 10/18/2024 1.2.2 is deprecated.
1.2.1 302 10/1/2024 1.2.1 is deprecated.
1.2.0 292 9/8/2024 1.2.0 is deprecated.
1.1.9 294 9/2/2024 1.1.9 is deprecated.
1.1.8 269 9/2/2024 1.1.8 is deprecated.
1.1.7 261 9/1/2024 1.1.7 is deprecated.
1.1.6 254 9/1/2024 1.1.6 is deprecated.
1.1.5 292 9/1/2024 1.1.5 is deprecated.
1.1.4 279 9/1/2024 1.1.4 is deprecated.
1.1.3 286 9/1/2024 1.1.3 is deprecated.
1.1.2 287 9/1/2024 1.1.2 is deprecated.
1.1.1 277 8/31/2024 1.1.1 is deprecated.
1.1.0 249 8/29/2024 1.1.0 is deprecated.
1.0.9 266 8/29/2024 1.0.9 is deprecated.
1.0.8 357 8/27/2024 1.0.8 is deprecated.
1.0.7 320 8/26/2024 1.0.7 is deprecated.
1.0.6 281 8/26/2024 1.0.6 is deprecated.
1.0.5 284 8/25/2024 1.0.5 is deprecated.
1.0.4 288 8/25/2024 1.0.4 is deprecated.
1.0.3 300 8/25/2024 1.0.3 is deprecated.
1.0.2 279 8/25/2024 1.0.2 is deprecated.
1.0.1 272 8/25/2024 1.0.1 is deprecated.
1.0.0 445 8/25/2024 1.0.0 is deprecated.

v1.6.9: SECURITY FIX - removed sensitive data from template. Fixed Redis Enable flag, added RSA PEM file support for JWT, health check endpoints.