SmartAdmin.AspNetCore 10.0.0

English | 简体中文

<p align="center"> <img src="web/design-mockups/brand/icon-128.png" width="80" height="80" alt="SmartAdmin"> </p>

<h1 align="center">SmartAdmin</h1>

<p align="center"> <em>Three lines of code to add a complete, extensible RBAC access-management layer to your ASP.NET Core project.</em> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a> <a href="https://github.com/SmartCode-X/SmartAdmin/stargazers"><img src="https://img.shields.io/github/stars/SmartCode-X/SmartAdmin" alt="Stars"></a> <a href="https://github.com/SmartCode-X/SmartAdmin/network/members"><img src="https://img.shields.io/github/forks/SmartCode-X/SmartAdmin" alt="Forks"></a> <a href="https://www.nuget.org/packages/SmartAdmin"><img src="https://img.shields.io/nuget/v/SmartAdmin" alt="NuGet"></a> <img src="https://img.shields.io/badge/.NET-10-512BD4" alt=".NET 10"> </p>

<p align="center"> <a href="https://smartadmin.smart.com"><strong>📖 Docs</strong></a>  ·  <a href="CHANGELOG.md"><strong>📋 Changelog</strong></a> </p>

🎨 What is this?

SmartAdmin packages the common back-office machinery as NuGet packages. Users, roles, menus, multi-org data permissions, dictionaries, config, operation logs, file uploads — everything every back office ends up rebuilding — comes in via dotnet add package. Three lines in Program.cs give you a complete admin API:

builder.Services.AddSmartAdmin(builder.Configuration);
var app = builder.Build();
app.MapSmartAdmin();

• Runs by default — zero-config start: tables auto-created, seed data loaded, SQLite as the fallback. First run doesn't even need a database server.
• Replace what you don't like — every built-in service is interface-based and registered with TryAdd. Register your own implementation and the built-in one steps aside. No forking.
• Upgrading = bumping a package version — bug fixes and new features arrive as package updates; your business code doesn't move.

The usual approach is cloning a template repo: hundreds of files become yours to maintain, business code and framework code end up tangled together, and when the framework ships a new version you're stuck merging diffs by hand. SmartAdmin flips that — the common machinery is a package dependency, and your business code stays your business code.

The frontend is covered too: a self-contained Vue 3 template. Degit a copy and it's the starting point of your own project.

🗺️ Runtime architecture

Primary request path: SPA template → Host (with SignalR) → auth & data-scope → domain services → SqlSugar → DB. Side path: in-kernel job scheduler, plus an optional standalone Worker process.

<p align="center"> <a href="docs/architecture/smart-runtime.en.architecture.html"> <img src="docs/architecture/smart-runtime.en.readme.png" alt="SmartAdmin runtime architecture" width="100%"> </a> </p>

<p align="center"> <a href="docs/architecture/smart-runtime.en.architecture.html"><strong>Open interactive architecture diagram</strong></a> </p>

🚀 Quick Start

Requirements

• .NET 10 SDK
• Node.js 20+ (only if you run a frontend template)

Take it for a spin

Clone the repo, then one command for the backend:

dotnet run --project backend/samples/MinimalHost

First startup creates the database and tables, loads seed data, and prints a randomly generated super-admin password to the console (account superAdmin). API is up at http://localhost:5100.

Start the frontend:

cd web && npm install && npm run dev            # → http://localhost:5173

Open the browser, log in with the credentials from the console, and there's your full back office. On Windows it's even lazier: double-click dev.bat in the repo root and the backend plus the frontend start in one go.

Plug it into your own project

dotnet add package SmartAdmin

Add the three lines above to Program.cs, and JWT auth, RBAC, data permissions, and every management endpoint register themselves on startup. Different database? One config block:

// appsettings.json
"SmartAdmin": {
  "Database": {
    "DbType": "MySql",          // Sqlite / MySql / SqlServer / PostgreSQL
    "ConnectionString": "..."
  }
}

Don't like a built-in implementation? Swap it

Every built-in service is interface-based and registered with TryAdd — register yours first and the built-in one steps aside:

// e.g. swap the password hashing algorithm: register yours before AddSmartAdmin
builder.Services.AddSingleton<IPasswordHasher, MyPasswordHasher>();
builder.Services.AddSmartAdmin(builder.Configuration);

It goes finer than that: long service methods are split into small virtual steps, so you can subclass a built-in service and override just the one step you care about instead of copying the whole method. And this replaceability isn't a slogan — a dedicated set of contract tests locks it in place.

✨ Backend features

• Auth — Account/password + captcha, JWT + refresh-token rotation, login lockout, online sessions & force-logout; optional TOTP self-enrollment / Cookie sessions (off by default — see docs/agents/security-optional-config.md). Not an MLPS certification product
• RBAC — Roles, three-level menus (directory / page / button), button-level permission codes, role-menu authorization
• Data permissions — All / this org / org & children / self only / custom orgs, enforced by ORM global filters — zero filtering code in your business logic
• Multi-app portal — App management, independent menu trees, app selection & switching
• Organization — Org tree, positions, multi-role users with a primary org
• Notifications — In-app notices & announcements, targetable to everyone / roles / users
• Dictionary & config — Dict types + items + key-value config, cached with event-driven invalidation
• Logging — Auto-recorded operation logs with sensitive-input masking
• File management — Upload/download, size limits, extension whitelist, path-traversal protection
• Import/export — xlsx import wizard (preview, per-cell validation, dedupe, partial commit) and column-pickable export, from the optional SmartAdmin.Excel package — skip it and publish size doesn't grow by a byte
• Scheduled jobs — a scheduler in the kernel, with no new dependency and no extra process: cron (six fields, seconds first, L/W/# included), fixed interval or one-shot triggers; write an IAdminJob class for the payload, or write no code at all and configure an HTTP call. Replicas elect a leader through a database lease, so one dying doesn't stop the schedule — and every occurrence still fires exactly once cluster-wide
• Multi-database — SQLite (default) / MySQL / SQL Server / PostgreSQL; switching is a config change
• Multi-replica — Optional Redis cache, cross-replica rate-limit counters, per-replica snowflake worker IDs — scales out without surprises
• Restrained dependencies — Core packages depend only on SqlSugarCore + Microsoft.* at runtime; no third-party framework zoo dumped into your project

🖥️ Frontend: the official template

The backend contract ships with one self-contained frontend template:

It's self-contained, so a degit snapshot runs and evolves on its own. What it brings:

• Contract-generated API — OpenAPI → schema.d.ts, type-safe end to end; change an endpoint and the frontend fails to compile
• Dynamic routing — Backend menu tree drives route registration; multi-app portal with seamless switching
• Button-level permissions — v-auth directive, permission codes matching the backend routes
• Column-driven tables — One columns array drives the search form, dict rendering, and column settings
• Design tokens + light/dark themes — Four-layer CSS variable tokens, follows the system or toggles manually
• Three login-page skins — Switchable out of the box, style-isolated
• In-house component library — FormContainer (modal/drawer two-in-one), StatusSwitch (pessimistic-update toggle), dict suite, OrgTreeSelect, FileUpload (chunked / resumable / instant), PasswordStrength, ImportWizard, chart wrappers, and more

🧩 Repository layout

📋 Project status

The API may still change before 1.0 — breaking changes are called out in the changelog. Development happens on the dev branch; issues and PRs welcome.

📄 License

Apache License 2.0