Kodevy.Templates.Microservice.Add 9.1.4

Kodevy Add Microservice Template

Adds a new .NET 8 microservice to an existing Kodevy monorepo or creates a standalone microservice — using Clean Architecture and Kodevy Platform NuGet packages (Kodevy.Platform.* 4.3.*).

Documentation

Always open the README.md inside the generated microservice folder before deploying — it documents every setting and operational step.

What This Template Creates

A complete microservice with four Clean Architecture layers:

Contoso.Platform.Payments/
├── Contoso.Platform.Payments.sln
├── nuget.config
├── Dockerfile
├── azure-pipelines.service.yml
├── add-migration.sh / add-migration.ps1
├── db-init/
│   ├── database-setup.sql
│   ├── database-setup.postgresql.sql
│   ├── database-setup.sqlserver.sql
│   ├── database-setup.mysql.sql
│   └── bootstrap-db.sh / bootstrap-db.ps1
├── tests/
│   └── Contoso.Platform.Payments.Tests/
└── src/
    ├── Contoso.Platform.Payments.API/
    ├── Contoso.Platform.Payments.Application/
    ├── Contoso.Platform.Payments.Domain/
    └── Contoso.Platform.Payments.Infra/

• API — Controllers, middleware, configuration, startup
• Application — Use cases, DTOs, services, contracts
• Domain — Entities, domain logic
• Infrastructure — Data access, repositories, external services

Installation

dotnet new install Kodevy.Templates.Microservice.Add

Usage

Add to an Existing Monorepo

If you created your solution with kodevy-microservice-init, navigate to the services/ directory:

cd MyProject/services

dotnet new kodevy-microservice-add \
  --organization Contoso \
  --system Platform \
  --microservice Payments

This places Contoso.Platform.Payments/ alongside your existing services, sharing the same Directory.Build.props and nuget.config.

Create a Standalone Microservice

Run from any directory — no existing solution required:

dotnet new kodevy-microservice-add \
  --organization Contoso \
  --system Platform \
  --microservice Payments

This creates Contoso.Platform.Payments/ in the current directory as a self-contained microservice with its own .sln, nuget.config, and Dockerfile.

Parameters

Getting Started

Run the Service

cd Contoso.Platform.Payments/src/Contoso.Platform.Payments.API
dotnet run

Database Migrations

The microservice ships with a User model in the Domain layer, but no migration has been created. Create one if needed:

Linux/Mac:

cd Contoso.Platform.Payments
chmod +x add-migration.sh  # First time only
./add-migration.sh AddUserTable

Windows (PowerShell):

cd Contoso.Platform.Payments
.\add-migration.ps1 -Name AddUserTable

Migration Behavior:

• Development — Migrations are automatically applied on startup
• Production — Migrations are not applied automatically. Set RUN_MIGRATIONS_ONLY=true to apply pending migrations and exit

Docker

Build:

cd Contoso.Platform.Payments
docker build -t contoso-platform-payments:latest .

Run:

docker run -p 8080:8080 contoso-platform-payments:latest

Run migrations only:

docker run -e RUN_MIGRATIONS_ONLY=true contoso-platform-payments:latest

Testing

Each generated microservice includes a ready xUnit test project:

• tests/Contoso.Platform.Payments.Tests
• Sample Domain test (UserTests)
• Sample Application test (UserServiceTests)

Run all tests from service root:

cd Contoso.Platform.Payments
dotnet test

Configuration

Authentication & Authorization

AuthenticationStrategy:

• Jwt — JWT token-based authentication

AuthorizationStrategy:

• Claims — Authorization based on JWT claims

API Versioning & Swagger

Generated APIs follow URL-segment versioning conventions:

• Controller route pattern: api/v{version:apiVersion}/[controller]
• Controller version attribute: [ApiVersion("1.0")]

Swagger is configured via Platform and exposes versioned documents (for example /swagger/v1/swagger.json) with multi-version support.

JWT Settings

JwtSettings supports two validation modes:

• HS256 (default):

  • SigningAlgorithm = HS256 (or omitted)
  • Secret, Issuer, Audience
  • for token issuing services, also set AccessTokenExpirationMinutes and RefreshTokenExpirationMinutes

• RS256 (opt-in):

  • SigningAlgorithm = RS256
  • Issuer, Audience
  • configure one of Authority or JwksUri
  • Secret is not required in RS256 mode

Optional controls:

• RequireHttpsMetadata (default true)
• RefreshOnIssuerKeyNotFound (default true)
• ValidAlgorithms (defaults to mode-appropriate values)
• issuer-only: PrivateKeyPem, KeyId (for services that issue RS256 tokens)

OpenTelemetry

Generated services include optional OpenTelemetry config and Platform AddBaseOpenTelemetry wiring for traces + metrics. Set OpenTelemetry:Enabled=true and configure OtlpEndpoint to export telemetry.

OAuth redirect (OAuthRedirect)

The API project scaffolds OAuthRedirect for safe browser redirects after OAuth. Configure origins and path prefixes per environment. Details: generated service README.md.

Security headers & rate limiting (Platform 4.3)

The pipeline includes security headers and base rate limiting. Optional SecurityHeaders / AuthRateLimit keys in appsettings override defaults — see the generated service README.md.

Database

Edit appsettings.json in the API project. When running through Docker locally, use host.docker.internal as the database host.

For provider-agnostic bootstrap, use scripts in db-init/ for PostgreSQL, SQL Server, or MySQL.

Dependencies

This template uses Kodevy Platform NuGet packages:

• Kodevy.Platform.API — Middleware, auth, Swagger, health checks
• Kodevy.Platform.Application — Application layer primitives and clients
• Kodevy.Platform.Domain — Domain abstractions
• Kodevy.Platform.Infra — EF Core, Serilog sinks

Generated services reference Kodevy.Platform.* version 4.3.*.

Related

• Kodevy Microservice Init — Creates the initial monorepo solution with your first microservice