CleanAdmin.Template 1.0.0

CleanAdmin

A CleanDDD-based full-stack admin template built with .NET 10, Aspire, and Blazor.

English | 简体中文

CleanAdmin is an open-source admin template based on .NET 10, designed for lightweight, fast, and maintainable enterprise web application development. It integrates FastEndpoints, Aspire, and Scalar to provide a modern API development and documentation experience.

CleanAdmin focuses on clear architecture and simple implementation. In a single solution, it combines backend APIs, frontend UI, infrastructure orchestration, migration services, and test projects. It also supports Microsoft.Kiota to auto-generate strongly typed API clients, reducing integration and maintenance costs while improving team delivery efficiency.

👀 Project Preview

• Live preview: https://cleanadmin.azurewebsites.net
• Note: The preview site is currently powered by mock data generated with Apifox.

🌟 Why Choose CleanAdmin

Compared with traditional admin templates, CleanAdmin puts stronger emphasis on maintainability and a modern developer experience:

• Built on netcorepal-cloud-framework: Implements DDD tactical patterns and includes core architecture capabilities such as CQRS, event-driven workflows, distributed transactions (eventual consistency), multi-tenancy, multi-environment deployment (including canary), and database sharding.
• Aspire cloud-native zero-config development environment: One command can orchestrate API, Web, database, and middleware services without complex local setup.
• Minimal API style with FastEndpoints: Uses REPR and vertical slices instead of traditional controllers for higher cohesion and better execution efficiency.
• Modern API docs with Scalar: Provides a modern API document and debugging UI for browsing, integration, and team collaboration.
• Kiota strongly typed API clients: Auto-generates strongly typed API clients from OpenAPI to reduce development overhead.
• Blazor full-stack development: Uses a unified C# stack across frontend and backend, and provides a backend-friendly frontend development experience based on Ant Design Blazor and Tailwind CSS.

🏗️ Architecture

The solution includes the following projects:

🧰 Tech Stack

🚀 Quick Start

1) ✅ Prerequisites

• .NET SDK 10.0.100
• Docker Desktop
• Node.js 18+

2) 📦 Create a new project from template

CleanAdmin is available as a dotnet new template. Install it and create your project:

# Install the template (from NuGet)
dotnet new install CleanAdmin.Template

# Or install from local source
dotnet new install .

# Create a new project (replace CleanAdmin with your desired name)
dotnet new cleanadmin -n CleanAdmin -o CleanAdmin
cd CleanAdmin

3) 📦 Restore dependencies

dotnet restore

4) 📦 Install frontend dependencies

Tailwind CSS build requires Node.js dependencies:

cd src/CleanAdmin.Web
npm install
cd ../..

5) ▶️ Run the full stack with Aspire

dotnet run --project src/CleanAdmin.AppHost

AppHost will orchestrate PostgreSQL, Redis, RabbitMQ, MigrationService, ApiService, and the Web frontend.

🛠️ Backend Development Notes

For backend development conventions, refer to the guideline files under .github/instructions (such as endpoint.instructions.md, command.instructions.md, query.instructions.md, and aggregate.instructions.md).

💻 Local Development

During development, build ApiService in Release mode to generate API clients:

dotnet build src/CleanAdmin.ApiService -c Release

Watch CSS for hot reload during development:

cd src/CleanAdmin.Web
npm run watch:css

🔗 Common Endpoints

• Scalar (development): /scalar
• Health check: /health
• Liveness: /alive
• Prometheus metrics: /metrics
• CAP dashboard: /cap
• Hangfire dashboard: /hangfire
• Code analysis visualization: /code-analysis

⚙️ Configuration

• Default local settings are in each project's appsettings*.json
• Aspire parameters are in src/CleanAdmin.AppHost/appsettings.json
• Use environment variables or user secrets for sensitive values

Example:

dotnet user-secrets set "Auth:Jwt:TokenSigningKey" "your-long-random-signing-key" --project src/CleanAdmin.ApiService
dotnet user-secrets set "Auth:ApiKey" "your-api-key" --project src/CleanAdmin.ApiService

🗄️ Database Migration

When starting with AppHost, CleanAdmin.MigrationService runs migrations automatically.

If you need EF CLI manually:

dotnet tool install --global dotnet-ef
dotnet ef migrations add <MigrationName> -p src/CleanAdmin.MigrationService
dotnet ef database update -p src/CleanAdmin.MigrationService

🧪 Testing

Run all tests:

dotnet test

✨ IDE Snippets

This repository includes productivity snippets for common DDD patterns:

• VS Code: .vscode/csharp.code-snippets — type prefixes like epp, ncpcmd, ncpar, ncprepo etc.
• Visual Studio: vs-snippets/NetCorePalTemplates.snippet — run vs-snippets/Install-VSSnippets.ps1 to install

📚 Related Projects

• NetCorePal Cloud Framework
• Ant Design Blazor
• FastEndpoints

🤝 Contributing

Contributions are welcome in many forms. Code submissions, suggestions, and issue reports are all appreciated.

📄 License

MIT License. See LICENSE for details.