开始使用

准备

开发环境

Visual Studio 2022/2026，SQLite/SQLServer/Oracle/PostgreSQL/MySql(8.0+)/Firebird/DM8(达梦)/KingbaseES(人大金仓)/openGauss(华为) 等等数据库。 若无数据库环境，可先用 SQLite 起步(该数据库无需任何安装和配置)。

安装项目模板

已在 NuGet 提供了若干项目模板，用来快速生成相应项目。在命令行输入以下命令进行安装(若已安装将更新至最新版)：

dotnet new install QuickAdmin.Net.Templates

TIP

模板比较大(包含了 FineUICore 资源)，若安装时提示下载超时，可去手动下载安装：在 NuGet 页面将 .nupkg 包文件下载下来(或点击此处直接下载)，然后到下载目录运行 dotnet new install 下载的.nupkg文件 安装。
若运行 dotnet new install QuickAdmin.Net.Templates 时提示 .nupkg 文件已存在，是因为前次运行时它把文件下载了个半截子，删掉再重试(文件位置通常为 %USERPROFILE%\.templateengine\packages)。

    用 Visual Studio 新建项目时，在搜索模板输入框内输入 "qadmin" 即可快速列出所提供的几个模板：

创建项目(用QAdmin模板)

用 "QuickAdmin.Net Web App" 模板去创建一个项目，首次运行，将自动导航到创建系统表的页面：

QuickAdmin.Net 内置了分别与 SQLite/SQLServer/Oracle/PostgreSQL/MySql 数据库对应的用来创建系统表的 SQL 脚本，对于这些数据库， 点击 "执行脚本创建系统表" 按钮，对于其它数据库点击 "用同步方法创建系统表" 按钮。

系统表创建好后，点击 "访问系统" 链接，即可进行登录(QuickAdmin.Net 还内置了手机号登录以及微信扫码登录，默认未启用)：

上图为 QuickAdmin.Net 内置的登录页，输入超级管理员账户 "admin" 及其默认密码 "admin"，再输入验证码，登入系统：

上图为 QuickAdmin.Net 内置的 Index 页，初次登录时会创建一些示例菜单项。点击 "系统菜单" 可去定制系统菜单项。点击 "内置页面总览" 去查看 QuickAdmin.Net 内置的功能页面有哪些。

内置的登录页、Index 页均可定制(无需编译，通过 json 配置文件进行)，如系统名称、系统 Logo 等等，也可改用你自己的登录页和 Index 页，具体在后边的章节中说明。

创建解决方案(用QAdmin模板)

用 "QuickAdmin.Net Solution" 模板去创建解决方案，该模板内含有示例数据库(SQLite，有组织机构、用户数据)以及简单的示例页面。
该模板包含了三个项目：实体(Entity)/服务(Service)/Web 项目，建议用此模板进行开发。
创建时有个 [添加 ASP.NET Core Cookie 身份认证] 选项，关于该选项参见开发指南里的身份认证与授权部分说明。

该模板 Web 项目下的 Program.cs 里附有详细的初始化注释说明，参考 AddQuickAdmin() 扩展方法和 QuickAdminInitializationOptions 选项类文档。
AddQuickAdmin()/UseQuickAdmin() 里默认会自动初始化 Session、FreeSql 以及 FineUICore，你可通过选项参数对他们的初始化过程进行定制，执行你需要的配置操作。你也可以完全自行初始化 Session/FreeSql/FineUICore 等。

TIP

如你所看到的，用 QAdmin 模板创建的 Web 项目里的 Pages 目录下并没有 Index 和 Login 页，应用将使用 QuickAdmin.Net 内置的对应页面。如果你要使用自己的页面，自行在 Pages 目录下创建 Index/Login 页即可。

创建项目(不用QAdmin模板)

不用 QAdmin 模板，按照以下步骤去建立基于 QuickAdmin.Net 的 Web 项目。

1. 用 Visual Studio 内置的 "ASP.NET Core Web 应用" 模板创建一个项目：
   项目框架选取 .NET 8.0+ (前提：你已安装对应版本的 .NET SDK)，并建议选中 "不使用顶级语句"。
2. 给项目添加以下 NuGet 包：
   QuickAdmin.Net: QuickAdmin.Net 框架 NuGet 包。
   FreeSql.Provider.Sqlite: 先用 SQLite 数据库进行演练。
3. 给项目添加 FineUICore 程序集引用：
   引用 FineUICore.dll 以及 FineUICoreRes.dll。这两个文件包含在 QAdmin 模板里，请用模板创建一个项目并从其中取得。
   要获取最新版 FineUICore.dll，请到其官方社区免费下载。
4. 删除自动创建的 Index 页面：
   鼠标右击 Pages 目录下的 Index.cshtml，将其删掉。删掉后将使用 QuickAdmin.Net 内置的 Index 页面。
   如果你要使用自己的 Index 页，则不要删除。
5. 修改Program.cs，加入以下代码里的高亮部分：

using FineUICoreRes;
using QuickAdmin.RCL;

namespace WebApplication1
{
  public class Program
  {
    public static void Main(string[] args)
    {
      var builder = WebApplication.CreateBuilder(args);

      // 添加 FineUICore 静态资源
      builder.Services.AddFineUICoreRes();

      // 添加 QuickAdmin.Net
      builder.Services.AddQuickAdmin(builder.Environment, builder.Configuration);

      // Add services to the container.
      builder.Services.AddRazorPages();

      // 添加 控制器服务
      builder.Services.AddControllers();

      var app = builder.Build();

      // Configure the HTTP request pipeline.
      if (!app.Environment.IsDevelopment())
      {
        app.UseExceptionHandler("/Error");
        // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
        app.UseHsts();
      }

      app.UseHttpsRedirection();
      app.UseStaticFiles();

      app.UseRouting();

      app.UseAuthorization();

      // QuickAdmin.Net 中间件配置
      app.UseQuickAdmin();

      app.MapRazorPages();

      // 添加 控制器路由映射
      app.MapControllers();

      app.Run();
    }
  }
}

6. 编译运行。首次运行将自动导航到创建系统表页面。

修改一下 _ViewStart.cshtml 和 _ViewImports.cshtml 文件来使用 QuickAdmin.Net 的内置布局：
_ViewStart.cshtml：

@{
  Layout = "/Areas/QAdmin/Pages/Shared/_QAdminLayout.cshtml";
}

_ViewImports.cshtml：

@using WebApplication1
@namespace WebApplication1.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

@using QuickAdmin.RCL
@using QuickAdmin.RCL.Extensions
@using QuickAdmin.RCL.Extensions.FineUI

@using FineUICore
@addTagHelper *, FineUICore

在 Linux/Docker 中运行

部署到 Linux 或在 Docker 容器里运行时，如果出现图片验证码生成失败的情况，如下图：

通常是缺少依赖库，请根据你的 Linux 发行版本运行以下命令安装：

# Ubuntu/Debian
apt-get install -y libfontconfig1 libfreetype6

或：

# Red Hat Linux/CentOS
yum install -y fontconfig freetype freetype-devel fontconfig-devel libstdc++

原因：内置的图片验证码服务使用了跨平台的开源图形库 SkiaSharp，有些 Linux 发行版本可能缺少相应依赖库。
当你基于微软官方 ASP.NET Core 运行时镜像构建 Docker 镜像时，把 apt-get install -y libfontconfig1 libfreetype6 加入构建命令即可。

Demo 源码下载

点击此处下载 Demo 源码。 打开解决方案，按说明文档操作。其中还包含了用于在 Linux 下部署的服务文件、命令简述以及 Docker 镜像构建说明及文件。

此文件已停止更新，QuickAdmin.Net 提供的解决方案模板里已包含了示例内容。你仍可下载去查阅 Linux部署/Docker构建 相关说明。