开始使用

准备

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

  • 下载 FineUICore 社区版
    QuickAdmin.Net 内置管理页面采用 FineUICoreopen in new window 社区版(一个丰富的 .NET 控件库,只有一个 DLL 文件,拷贝即用)构建,可在其官方社区免费下载。在编写自己的页面时,你可自行决定是否使用 FineUICore。
    从其官网进入(或 点击此处open in new window 直接进入) FineUI 免费社区并扫码加入,在置顶贴里找到 FineUICore 下载页面(版本:v12+), 下载其中的空项目或示例项目压缩包并解压,需要的文件为项目 bin 目录下的FineUICore.dllFineUICore.xml文件。
    为方便进行项目开发演示,建议在文件系统某个位置(例如D:盘根目录下)创建以下目录结构, 将以上两个文件放入FineUICore目录,创建 Visual Studio 项目时项目位置则选source目录:

├─QAdminDemos
  └─source
    └─FineUICore
  • 安装项目模板
    已在 NuGetopen in new window 提供了若干项目模板,用来快速生成相应项目。在命令行输入以下命令进行安装(若已安装将更新至最新版):
dotnet new install QuickAdmin.Net.Templates

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

创建项目(用QAdmin模板)

用 "QuickAdmin.Net Web App" 模板去创建一个项目,创建后手动更正一下项目对FineUICore.dll程序集的引用即可编译运行。
首次运行,将自动导航到创建系统表的页面:
CreateTables

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

系统表创建好后,点击 "访问系统" 链接,即可进行登录(QuickAdmin.Net 还内置了手机号登录以及微信扫码登录,默认未启用):
Login
上图为 QuickAdmin.Net 内置的登录页,输入超级管理员账户 "admin" 及其默认密码 "admin",再输入验证码,登入系统:
Index
上图为 QuickAdmin.Net 内置的 Index 页,初次登录时会创建一些示例菜单项。点击 "系统菜单" 可去定制系统菜单项。点击 "内置页面总览" 去查看 QuickAdmin.Net 内置的功能页面有哪些。

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

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

用 "QuickAdmin.Net Solution" 模板去创建解决方案,该模板内含有示例数据库(SQLite,有组织机构、用户数据)以及简单的示例页面。
该模板包含了三个项目:实体(Entity)/服务(Service)/Web 项目,建议用此模板进行开发。
创建时有个 [添加 ASP.NET Core Cookie 身份认证] 选项,关于该选项参见开发指南里的身份认证与授权部分说明。
Solution
该模板 Web 项目下的 Program.cs 里附有详细的初始化注释说明,参考 AddQuickAdmin()open in new window 扩展方法和 QuickAdminInitializationOptionsopen in new window 选项类文档。
AddQuickAdmin()/UseQuickAdmin() 里默认会自动初始化 Session、FreeSql 以及 FineUICore,你可通过选项参数对他们的初始化过程进行定制,执行你需要的配置操作。你也可以完全自行初始化 Session/FreeSql/FineUICore 等。

创建时若项目位置选取了前边建议的目录(如:D:\QAdminDemos\source),并选中了 "将解决方案和项目放在同一目录中",可不用调整程序集引用,直接编译运行。

TIP

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

创建项目(不用QAdmin模板)

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

  1. 用 Visual Studio 内置的 "ASP.NET Core Web 应用" 模板创建一个项目:
    项目位置可选取前边建议创建的目录,如:D:\QAdminDemos\source,项目框架选取 .NET 8.0+ (前提:你已安装对应版本的 .NET SDK),并建议选中 "不使用顶级语句"。
  2. 给项目添加以下 NuGet 包:
    QuickAdmin.Net: QuickAdmin.Net 框架 NuGet 包。
    FreeSql.Provider.Sqlite: 先用 SQLite 数据库进行演练。
  3. 给项目添加程序集引用:
    引用前边准备的 FineUICore.dll 以及 FineUICoreRes.dllFineUICoreRes.dll 包含在 QAdmin 模板里,请用模板创建一个项目并从其中取得该 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();
    }
  }
}
 
 









 
 

 
 




 
 


















 
 



 
 





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

修改一下 _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 容器里运行时,如果出现图片验证码生成失败的情况,如下图:
CaptchaFailed
通常是缺少依赖库,请根据你的 Linux 发行版本运行以下命令安装:

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

或:

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

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

Demo 源码下载

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

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