Muonroi.Microservices.Template 1.8.0

Muonroi.Microservices.Template

A .NET solution template for building distributed Microservices applications using ASP.NET Core, YARP Gateway, and the Muonroi.BuildingBlock library. Ideal for large-scale systems requiring independent scalability and deployment.

Quick Start

# 1. Install template
dotnet new install Muonroi.Microservices.Template

# 2. Create new project
dotnet new mr-micro-sln -n MyMicroservices

# 3. Setup
cd MyMicroservices/MyMicroservices
dotnet restore

# 4. Run Catalog service migrations
cd src/Services/MyMicroservices.Catalog
dotnet ef migrations add InitialCreate --project ../MyMicroservices.Data
dotnet ef database update --project ../MyMicroservices.Data

# 5. Run Catalog service
dotnet run

# 6. (Optional) Run Gateway
cd ../../Gateways/MyMicroservices.Gateway
dotnet run

Catalog Service: https://localhost:5001/swagger Gateway: https://localhost:7001

Prerequisites

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

Installation

From NuGet (recommended)

dotnet new install Muonroi.Microservices.Template

From source

git clone https://github.com/muonroi/MuonroiBuildingBlock.git
cd MuonroiBuildingBlock/src/Muonroi.Microservices.Template
dotnet new install ./

Verify installation

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

Usage

Create new project

dotnet new mr-micro-sln -n <ProjectName>

Examples

# Create microservices solution
dotnet new mr-micro-sln -n ECommerceServices

# Creates: CatalogService, Gateway, docker-compose

Project Structure

MyMicroservices/
├── MyMicroservices.sln
├── docker-compose.yml                      # Multi-service orchestration
├── docker-compose.override.yml
├── src/
│   ├── Gateways/                           # API Gateway Layer
│   │   └── MyMicroservices.Gateway/        # YARP Reverse Proxy
│   │       ├── appsettings.json
│   │       ├── Program.cs
│   │       └── yarp-config.json           # Route configuration
│   └── Services/                           # Microservices
│       ├── MyMicroservices.Catalog/        # Catalog Service
│       │   ├── appsettings.json
│       │   ├── appsettings.Development.json
│       │   ├── Controllers/
│       │   ├── Program.cs
│       │   └── Dockerfile
│       ├── MyMicroservices.Core/           # Shared domain
│       │   ├── Entities/
│       │   └── Interfaces/
│       └── MyMicroservices.Data/           # Data layer
│           ├── CatalogDbContext.cs
│           └── Repositories/
└── README.md

Configuration

Per-Service Configuration

Each microservice has its own appsettings:

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

Supported Database Types

Gateway Configuration (YARP)

Configure service routes in yarp-config.json:

{
  "ReverseProxy": {
    "Routes": {
      "catalog-route": {
        "ClusterId": "catalog-cluster",
        "Match": {
          "Path": "/catalog/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "catalog-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5001"
          }
        }
      }
    }
  }
}

Feature Flags

Toggle features per service:

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

Database Migrations

Each service manages its own database:

# Catalog service migration
cd src/Services/MyMicroservices.Catalog
dotnet ef migrations add "InitialCreate" \
    -p ../MyMicroservices.Data \
    -o Persistence/Migrations

dotnet ef database update \
    -p ../MyMicroservices.Data

Running Services

Development Mode

Run each service individually:

# Terminal 1 - Catalog Service
cd src/Services/MyMicroservices.Catalog
dotnet run

# Terminal 2 - Gateway
cd src/Gateways/MyMicroservices.Gateway
dotnet run

Docker Compose (recommended)

# Build and run all services
docker-compose up --build

# Run in background
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f catalog

Services will be available at:

• Gateway: http://localhost:7000
• Catalog: http://localhost:5000

Microservices Architecture

Why Microservices?

• Independent Scalability - Scale services based on demand
• Technology Diversity - Use different tech stacks per service
• Fault Isolation - Service failures don't affect others
• Independent Deployment - Deploy services independently

Service Communication

Services communicate via:

1. HTTP/REST - Synchronous via API Gateway
2. gRPC - High-performance inter-service calls
3. Message Bus - Asynchronous events (Kafka/RabbitMQ)
4. Service Discovery - Dynamic service location (Consul)

Adding New Service

1. Create service folder under src/Services/:

   src/Services/
   └── MyMicroservices.Orders/        # New service
       ├── Controllers/
       ├── Program.cs
       ├── Dockerfile
       └── appsettings.json
   

2. Add service to docker-compose.yml:

   orders:
     build:
       context: .
       dockerfile: src/Services/MyMicroservices.Orders/Dockerfile
     ports:
       - "5002:80"
     environment:
       - ASPNETCORE_ENVIRONMENT=Development
   

3. Add route to Gateway yarp-config.json

4. Create separate database for the service

Features

• Microservices Architecture - Independent, scalable services
• YARP API Gateway - Modern reverse proxy with dynamic routing
• Docker Support - Full containerization with docker-compose
• Service-per-Database - Each service owns its data
• Authentication & Authorization - JWT with distributed auth
• Structured Logging - Service-specific log files
• Caching - Redis for distributed caching
• Multi-tenancy - Tenant isolation per service
• Service Discovery - Consul integration
• Message Bus - Kafka/RabbitMQ via MassTransit
• gRPC Communication - High-performance inter-service calls
• Health Checks - Service health monitoring
• Distributed Tracing - OpenTelemetry support

Best Practices

✅ DO:

• Design services around business capabilities
• Use API Gateway for external clients
• Implement circuit breakers for resilience
• Use message bus for async communication
• Monitor service health and metrics
• Use separate databases per service

❌ DON'T:

• Share databases between services
• Create chatty inter-service calls
• Make synchronous calls for non-critical operations
• Deploy all services together
• Skip health checks and monitoring

Deployment

Docker Deployment

# Build images
docker-compose build

# Push to registry
docker tag myservices-catalog:latest myregistry/catalog:1.0
docker push myregistry/catalog:1.0

# Deploy to production
docker-compose -f docker-compose.prod.yml up -d

Kubernetes Deployment

See k8s/README.md for Kubernetes manifests.

Documentation

• Architecture Overview
• Microservices Guide
• API Gateway Guide
• Appsettings Guide
• Docker & K8s Guide

Troubleshooting

"Connection string is not provided"

Ensure each service has correct DbType and connection string:

{
  "DatabaseConfigs": {
    "DbType": "PostgreSql",
    "ConnectionStrings": {
      "PostgreSqlConnectionString": "..."
    }
  }
}

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

Set "EnableEncryption": false in each service's appsettings.

Gateway not routing

Check yarp-config.json routes and ensure service URLs are correct.

Docker services not communicating

Ensure services use docker-compose network names:

"Address": "http://catalog:80"  // Not localhost

Migration errors

Always specify -p and startup project for each service separately.

License

MIT License. See LICENSE.txt for details.