Muonroi.BaseTemplate 1.9.5

Muonroi.BaseTemplate

A .NET solution template for building ASP.NET Core applications using Clean/Onion Architecture with the Muonroi.BuildingBlock library.

Quick Start

# 1. Install template
dotnet new install Muonroi.BaseTemplate

# 2. Create new project
dotnet new mr-base-sln -n MyProject -C MyCore

# 3. Setup
cd MyProject
dotnet restore

# 4. Run migrations (optional)
./scripts/ef.sh add InitialCreate
./scripts/ef.sh update

# 5. Run
cd src/MyProject.API
dotnet run

Open: https://localhost:5001/swagger

Prerequisites

• .NET 9.0 SDK or later
• (Optional) EF Core CLI: dotnet tool install --global dotnet-ef

Installation

From NuGet (recommended)

dotnet new install Muonroi.BaseTemplate

From source

git clone <your-private-url>/Muonroi.BaseTemplate.git
cd Muonroi.BaseTemplate
dotnet new install ./

Verify installation

dotnet new list | grep "mr-base-sln"

Usage

Create new project

dotnet new mr-base-sln -n <ProjectName> [-C <ClassName>] [--ui <angular|react|mvc|none>] [--tier <oss|licensed|enterprise>] [--cpu <control-plane-url>]

Generated UI shells use Muonroi hybrid UI engine:

• Backend metadata endpoints: GET /api/v1/auth/ui-engine/{userId}, GET /api/v1/auth/ui-engine/current
• FE runtime packages: @muonroi/ui-engine-core, @muonroi/ui-engine-angular, @muonroi/ui-engine-react
• MVC runtime package: Muonroi.Ui.Engine.Mvc
• Optional UI-kit adapter package: @muonroi/ui-engine-primeng

Template boundary:

• Muonroi.BaseTemplate keeps scaffold/wiring for dotnet new.
• Shared UI runtime core is maintained in Muonroi.Ui.Engine.
• Runtime verification should be executed on freshly generated projects under _tmp/verify-runs, not by treating template source as production app.

Sync helper:

./scripts/sync-ui-engine.sh --ui-engine-path ../Muonroi.Ui.Engine --openapi http://localhost:5000/swagger/v1/swagger.json --framework all

Examples

# Basic
dotnet new mr-base-sln -n MyApp

# With custom class name
dotnet new mr-base-sln -n TruyenTM -C TruyenTM
# Generates: TruyenTMDbContext, TruyenTMRepository, etc.

# With Angular shell starter
dotnet new mr-base-sln -n MyApp -C MyApp --ui angular

# Licensed tier (commercial feed required)
dotnet new mr-base-sln -n MyLicensedApp --tier licensed

# Enterprise tier with control plane URL
dotnet new mr-base-sln -n MyEnterpriseApp --tier enterprise --cpu https://cp.myorg.com

Project Structure

MyProject/
├── MyProject.sln
├── scripts/
│   └── ef.sh                    # Cross-platform migration helper
├── src/
│   ├── MyProject.API/           # Presentation Layer
│   │   ├── appsettings.json
│   │   ├── appsettings.Development.json
│   │   ├── appsettings.Production.json
│   │   ├── appsettings.Example.json   # Configuration reference
│   │   ├── Program.cs
│   │   ├── Controllers/
│   │   └── Application/
│   ├── MyProject.Core/          # Domain Layer
│   │   ├── Entities/
│   │   └── Interfaces/
│   └── MyProject.Data/          # Infrastructure Layer
│       ├── MyDbContext.cs
│       └── Repositories/
└── README.md

Configuration

Supported Database Types

Example Configuration

{
  "DatabaseConfigs": {
    "DbType": "Sqlite",
    "ConnectionStrings": {
      "SqliteConnectionString": "Data Source=app.db"
    }
  },
  "TokenConfigs": {
    "Issuer": "https://localhost:5001",
    "Audience": "https://localhost:5001",
    "SigningKeys": "your-secret-key-minimum-32-characters!",
    "UseRsa": false,
    "ExpiryMinutes": 60
  },
  "EnableEncryption": false
}

See appsettings.Example.json for all available options with documentation.

Feature Flags

Toggle optional features to reduce startup time:

{
  "FeatureFlags": {
    "UseGrpc": false,
    "UseServiceDiscovery": false,
    "UseMessageBus": false,
    "UseBackgroundJobs": false,
    "UseEnsureCreatedFallback": true
  }
}

Enterprise Operations (E4/E5)

Enable management endpoints only when needed:

{
  "EnterpriseOps": {
    "EnableComplianceEndpoints": false,
    "EnableOperationsEndpoints": false
  }
}

When enabled:

• EnableComplianceEndpoints: maps MapMComplianceEndpoints()
• EnableOperationsEndpoints: maps MapMEnterpriseOperationsEndpoints()

Ops scripts included in scripts/:

• check-enterprise-upgrade-compat.ps1
• check-enterprise-slo-gates.ps1

SLO presets included in deploy/enterprise/slo-presets/:

• balanced.json
• strict.json
• regulated.json

Note: if your Muonroi.BuildingBlock package version does not include E4/E5 endpoint extensions yet, these toggles are ignored safely.

Database Migrations

Using helper script (recommended)

Linux/macOS (or Git Bash on Windows):

./scripts/ef.sh add InitialCreate
./scripts/ef.sh update
./scripts/ef.sh list
./scripts/ef.sh help

Windows Command Prompt/PowerShell:

scripts\ef add InitialCreate
scripts\ef update
scripts\ef list
scripts\ef help

Using dotnet ef directly

dotnet ef migrations add "InitialCreate" \
    -p ./src/MyProject.Data \
    --startup-project ./src/MyProject.API \
    -o Persistence/Migrations

dotnet ef database update \
    -p ./src/MyProject.Data \
    --startup-project ./src/MyProject.API

Features

• Clean Architecture - Separate layers: API, Core, Data
• CQRS with MediatR - Command/Query separation
• Authentication & Authorization - JWT, permissions, roles
• Entity Framework Core - Multiple database support
• Structured Logging - Serilog with Console/Elasticsearch
• Caching - Memory, Redis, or Multi-level
• Multi-tenancy - Data isolation by tenant
• Service Discovery - Consul integration
• Message Bus - Kafka/RabbitMQ via MassTransit
• Background Jobs - Hangfire/Quartz

Rule Engine

The template includes practical rule examples for validation and orchestration.

Quick Start

See Rule Engine Quick Start.

Examples in this template

• src/Muonroi.BaseTemplate.API/Rules/B2B/B2BRegistrationRules.cs
• src/Muonroi.BaseTemplate.API/Rules/ContainerValidationRule.cs
• src/Muonroi.BaseTemplate.API/Rules/ContainerExistenceRule.cs
• src/Muonroi.BaseTemplate.API/Rules/LoggingHook.cs

Centralized docs

• Rule Engine Guide
• Rule Engine Configuration Reference
• Rule Engine Testing Guide

Documentation

Private docs are centralized in Muonroi.Docs:

• License Capability Model
• Control Plane MVP
• Enterprise Secure Profile (E2)
• Enterprise Centralized Authorization (E3)
• Enterprise Compliance (E4)
• Enterprise Operations (E5)

Troubleshooting

"Connection string is not provided"

Ensure DbType matches the connection string key:

{
  "DatabaseConfigs": {
    "DbType": "MySql",  // Must match key below
    "ConnectionStrings": {
      "MySqlConnectionString": "..."  // ✓ Correct key
    }
  }
}

"The input is not a valid Base-64 string"

Set "EnableEncryption": false in appsettings.

API slow on startup

Disable unused features in FeatureFlags.

Edition Notes

• Template package is MIT.
• Generated projects run in Free mode by default (LicenseConfigs:LicenseFilePath = null).
• If you enable premium modules in FeatureFlags (for example UseGrpc, UseMessageBus, strict multi-tenant/RBAC+ flows), provide a paid Muonroi license with matching feature keys.

License

MIT License. See LICENSE.txt for details.