DotnetForge

Production-ready .NET 10 project templates. One NuGet package, three templates.

Install

dotnet new install DotnetForge.Templates

Templates

Template	Command	What you get
Forge API	dotnet new forge-api -n MyApp	Standalone Minimal API with OpenTelemetry, health checks, resilience
Forge Aspire	dotnet new forge-aspire -n MyApp	API + .NET Aspire orchestration + Azure deployment
Forge Full-Stack	dotnet new forge-fullstack -n MyApp	API + Aspire + React frontend (Vite/Bun) + Docker deployment

Quick Start

# Create a new project (Keycloak — default) dotnet new forge-aspire -n MyApp # Or with Microsoft Entra ID dotnet new forge-aspire -n MyApp --auth-provider entra # Optionally provide Entra IDs upfront dotnet new forge-api -n MyApp --auth entra --entra-tenant-id abc123 --entra-client-id def456 # Build and run cd MyApp dotnet run --project src/MyApp.AppHost

Parameters

Flag	Default	Description
-n, --name	MyApp	Project name (PascalCase). Auto-generates lowercase variants for config.
--auth-provider / --auth	keycloak	Identity provider: keycloak or entra
--entra-tenant-id	common	Microsoft Entra ID tenant ID (only when --auth entra)
--entra-client-id	YOUR_CLIENT_ID	Microsoft Entra ID application (client) ID (only when --auth entra)
--entra-domain	yourtenant.onmicrosoft.com	Microsoft Entra ID tenant domain (only when --auth entra)

What's Included

API (forge-api / forge-aspire / forge-fullstack)

• .NET 10 Minimal APIs with feature-slice architecture
• Keycloak or Microsoft Entra ID authentication + role-based authorization
• PostgreSQL with EF Core, migrations, Ulid primary keys
• FusionCache L1 memory + L2 Redis with backplane
• JSON:API compliant responses via JsonApiKit (cursor + offset pagination)
• MediaKit file storage (Local, S3, SeaweedFS, RustFS, Azure Blob/Azurite) with image conversions
• Scalar API docs with OAuth2 Authorization Code flow
• Rate limiting (Global, PublicRead, Authenticated, AdminWrite policies)
• FluentValidation + ErrorOr result pattern
• Domain events via EF Core interceptors
• xUnit v3 unit tests + k6 performance tests

Aspire Orchestration (forge-aspire / forge-fullstack)

• PostgreSQL, Redis containers with data volumes (Keycloak container when using Keycloak auth)
• DbGate web-based database management (persistent, for Postgres and Redis)
• Configurable storage — S3-compatible (RustFS, SeaweedFS) or Azure Blob (Azurite emulator)
• Enterprise publisher for deployment documentation
• Aspire Dashboard with seed data command
• Azure Container Apps deployment via azd up
• Feature/integration tests with Aspire.Hosting.Testing

React Frontend (forge-fullstack only)

• React 19 + TypeScript + Vite + Bun (auto-installed via WithBunPackageInstallation())
• TanStack Router + Query
• Radix UI + Tailwind CSS 4
• oidc-spa OIDC integration (Keycloak or Entra ID)
• i18n via i18next
• Orval API client generation from OpenAPI
• Docker multi-stage build with nginx

Setting up Microsoft Entra ID

When using --auth-provider entra, you need an Azure App Registration:

1. Create App Registration in Azure Portal → Microsoft Entra ID → App registrations
2. Add App Roles (e.g., admin, author, reader) under App roles → Create app role
3. Configure API Permissions → Expose an API → Add a scope (e.g., api://<client-id>/access_as_user)
4. For the React frontend (forge-fullstack): Create a second App Registration (SPA type) with redirect URI http://localhost:5173
5. Update appsettings.json with your Tenant ID, Client ID, and Domain

The Entra parameters are optional at project creation — you can leave the defaults and configure appsettings.json later:

# Minimal — configure in appsettings.json after project creation dotnet new forge-api -n MyApp --auth entra # Or provide values upfront dotnet new forge-api -n MyApp --auth entra \ --entra-tenant-id your-tenant-id \ --entra-client-id your-client-id \ --entra-domain yourtenant.onmicrosoft.com

Architecture

MyApp/ ├── src/ │ ├── MyApp.Api/ # Minimal API │ │ ├── Data/ # Repositories + cached decorators │ │ ├── Entities/ # Domain entities (Book, Author, Category) │ │ ├── Features/ # Feature slices (Admin, Public, Dev) │ │ ├── Infrastructure/ # Auth, caching, validation, etc. │ │ ├── Migrations/ # EF Core migrations │ │ └── Services/ # Cross-cutting services │ ├── MyApp.AppHost/ # Aspire orchestrator (aspire/fullstack) │ ├── MyApp.AppHost.Extensions/ # Enterprise publisher │ ├── MyApp.ServiceDefaults/ # Shared OTel + health + resilience │ ├── MyApp.Web/ # React frontend (fullstack) │ └── MyApp.KeycloakTheme/ # Keycloakify theme (fullstack, Keycloak only) ├── tests/ │ ├── MyApp.Api.UnitTests/ # xUnit v3 + NSubstitute │ ├── MyApp.Api.FeatureTests/ # Aspire integration tests (aspire/fullstack) │ └── MyApp.PerformanceTests/ # k6 load tests ├── MyApp.slnx # Solution file ├── docker-compose.api.yml # Production API deployment └── docker-compose.api.build.yml # Local API build

Deployment Options

Azure (Aspire + Full-Stack)

azd init azd up

Docker Compose (all templates)

docker compose -f docker-compose.api.build.yml up -d

GitHub Actions

• deploy-azure.yml — Azure Container Apps via azd (aspire/fullstack)
• deploy-docker.yml — Multi-arch Docker build + webhook deploy (fullstack)

Sample Domain

The template includes a Books Management sample domain with:

• Book — title, ISBN, description, cover image, gallery
• Author — name, biography, avatar
• Category — name, description, icon

This gives you working CRUD endpoints, relationships, media uploads, caching, and search — all wired up and ready to extend. See SAMPLE_DOMAIN.md for details.

Development (Template Authors)

Repository Structure

dotnet-forge/ ├── shared/ # Common files across all templates (edit here) ├── overrides/ # Template-specific file variants (edit here) │ ├── forge-api/ │ ├── forge-aspire/ │ └── forge-fullstack/ ├── template-configs/ # .template.config per template ├── templates/ # BUILD OUTPUT (git-ignored) ├── build.ps1 # Assembles templates from shared + overrides └── DotnetForge.Templates.csproj

Build & Test

# Assemble templates ./build.ps1 # Install locally dotnet new install ./templates/forge-api dotnet new install ./templates/forge-aspire dotnet new install ./templates/forge-fullstack # Test dotnet new forge-aspire -n TestApp cd TestApp && dotnet build # Package dotnet pack DotnetForge.Templates.csproj

Uninstall

dotnet new uninstall DotnetForge.Templates