扩展集成

EasyAdminBlazor 把核心功能和扩展功能解耦,用哪个扩展就装哪个 NuGet 包。下面汇总各扩展包的安装、注册和基本用法。

如何自建扩展

官方扩展(审批、打印、计划任务、多租户、微信……)都是同一个套路:一个独立类库 + 一个 AddEasyAdminBlazorXxx() 注册方法,宿主加一行就装上,不引用就完全不存在。想把自己的功能也封成同样的扩展包,完整步骤见如何自建扩展。

扩展总览

扩展包 注册方法 功能
EasyAdminBlazor.Mail AddEasyAdminBlazorMail() SMTP / SendCloud / 腾讯云 邮件发送
EasyAdminBlazor.AliyunSms AddEasyAdminBlazorAliyunSms() 阿里云短信
EasyAdminBlazor.Redis AddEasyAdminBlazorRedis(连接串) Redis 缓存、在线状态、发布订阅、分布式锁
EasyAdminBlazor.FusionCache AddEasyAdminBlazorFusionCache() 混合缓存加速
EasyAdminBlazor.Captcha AddEasyAdminBlazorCaptcha(options) 表单/登录验证码
EasyAdminBlazor.HtmlEditor AddEasyAdminBlazorTinyMCEEditor() TinyMCE 富文本编辑器
EasyAdminBlazor.Chat AddEasyAdminBlazorChat() + app.UseChat() 实时聊天(依赖 Redis)
EasyAdminBlazor.MultiTenant AddEasyAdminBlazorMultiTenant() 多租户,详见多租户
EasyAdminBlazor.Scheduler AddEasyAdminBlazorScheduler() 计划任务,详见计划任务
EasyAdminBlazor.WeChat AddEasyAdminBlazorWeChat() 微信小程序、微信支付 V3
EasyAdminBlazor.Approval AddEasyAdminBlazorApproval() 轻量多级审批(状态机 + 审批记录表),详见审批
EasyAdminBlazor.Print AddEasyAdminBlazorPrint() 打印模板、报表设计器,详见打印模板
EasyAdminBlazor.CodeGenerator AddEasyAdminBlazorCodeGenerator() 可视化 CRUD 代码生成,详见代码生成
EasyAdminBlazor.Upgrade AddEasyAdminBlazorUpgrade() 应用在线升级(逐版本增量、发布即出包),详见应用升级
EasyAdminBlazor.Cms AddEasyAdminBlazorCms() 内容管理:内容、分类、页面元素、SEO,详见用 EasyAdminBlazor.Cms 开发一个新模块

在 Program.cs 里统一注册:

builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions { ... })
    .AddEasyAdminBlazorMail()
    .AddEasyAdminBlazorRedis(configuration["Redis:ConnectionString"]!)
    .AddEasyAdminBlazorChat()
    .AddEasyAdminBlazorScheduler()
    .AddEasyAdminBlazorCaptcha(options => { options.Chars = "0123456789"; })
    .AddEasyAdminBlazorCms();

Redis(EasyAdminBlazor.Redis)

.AddEasyAdminBlazorRedis(configuration["Redis:ConnectionString"]!)

配置:

{
  "Redis": {
    "ConnectionString": "127.0.0.1:6379,poolsize=10"
  }
}

注册后可以注入 IRedisService,支持:

  • 常用缓存:Get<T> / Set<T> / IncrBy / Expire 等 String、Hash、List、Set、Sorted Set 操作
  • 在线状态:JoinOnline / RemoveOnline / GetClientListByOnline / HasOnline
  • 发布订阅:Publish / Subscribe(频道见 SubscribeChannel 枚举)
  • 分布式锁:Lock(key, expireSeconds) / ReleaseLock(lockHandle)
@inject IRedisService Redis

// 缓存
Redis.Set("user:1", new UserDto { ... }, TimeSpan.FromMinutes(10));
var user = Redis.Get<UserDto>("user:1");

// 发布订阅
Redis.Subscribe<MyMessage>(SubscribeChannel.MessageNotification, msg =>
{
    // 处理消息
});
Redis.Publish(SubscribeChannel.MessageNotification, new MyMessage { ... });

// 分布式锁
var lockHandle = Redis.Lock("order:100", 30);
try
{
    // 临界区
}
finally
{
    Redis.ReleaseLock(lockHandle);
}

该扩展同时提供了 IDistributedCache 实现,兼容标准分布式缓存接口。

邮件(EasyAdminBlazor.Mail)

.AddEasyAdminBlazorMail()

配置支持两种写法。推荐按服务商分组放在 Mail 下(三选一,只配置 SMTP 无法使用模板发送):

{
  "Mail": {
    "Provider": "TencentCloud",
    "Smtp": {
      "Server": "smtp.example.com",
      "Port": 587,
      "Username": "your_email@example.com",
      "Password": "your_email_password",
      "FromEmail": "your_email@example.com",
      "EnableSsl": true
    },
    "SendCloud": {
      "ApiUser": "your_sendcloud_api_user",
      "ApiKey": "your_sendcloud_api_key",
      "SenderEmail": "noreply@example.com",
      "SenderName": "Your App"
    },
    "TencentCloud": {
      "SecretId": "your_secret_id",
      "SecretKey": "your_secret_key",
      "Region": "ap-guangzhou",
      "FromEmail": "noreply@example.com",
      "FromName": "Your App",
      "ReplyToAddresses": ""
    }
  }
}

也兼容旧版顶层写法(SmtpSettings / SendCloud / TencentCloud):

{
  "SmtpSettings": {
    "Server": "smtp.example.com",
    "Port": 587,
    "Username": "your_email@example.com",
    "Password": "your_email_password",
    "FromEmail": "your_email@example.com",
    "EnableSsl": true
  }
}

两套写法可以混用:旧版键的非空值优先,其余再读 Mail 下的同名配置。 后台“系统配置”页保存的就是旧版键,所以页面上的修改始终生效;如果某个键在后台已经保存过,appsettings 里的新布局不会覆盖它(把后台对应值清空即可回退到 appsettings)。

Provider 可选值:Smtp / SendCloud / TencentCloud,不配置时默认 Auto 自动选择(SendCloud 优先,其次腾讯云,最后 SMTP)。 显式指定 Provider 后,后台系统配置页只展示对应服务商的配置项;不指定(Auto)时三种配置项都会展示。 每种服务商分组都支持发送测试邮件;调用时也可临时指定本次发送使用的服务商:

var ok = await EmailService.SendEmailAsync("a@example.com", "标题", "内容", provider: "TencentCloud");

服务商名称由 EasyAdminBlazor.Mail 扩展解析(Smtp / SendCloud / TencentCloud,大小写不敏感),Core 不依赖具体服务商,后续新增服务商只需更新 Mail 扩展。 后台配置页的"邮件测试"按配置贡献者声明自动展示:新增服务商时在 Mail 扩展里新增一个继承 ConfigSettingsContributorBase 的贡献者类(ConfigType 与服务商名一致,并声明 IsEmailProvider = true 和测试必填项 EmailRequiredKeys),配置页和测试邮件即自动生效,无需改动 /Admin/Config。

注入 IEmailService 发送:

@inject IEmailService EmailService

// 普通邮件,多个收件人用英文分号分隔;isHtml 控制正文是否为 HTML
var ok = await EmailService.SendEmailAsync("a@example.com;b@example.com", "标题", "<h1>内容</h1>", isHtml: true);

// 模板邮件(SendCloud 模板传模板调用名称;腾讯云模板传模板ID)
var (success, message) = await EmailService.SendTemplateEmailAsync(
    "a@example.com",
    "通知",
    "your_template_name_or_id",
    new Dictionary<string, object> { ["code"] = "1234" });

短信(EasyAdminBlazor.AliyunSms)

.AddEasyAdminBlazorAliyunSms()

配置:

{
  "AliyunSms": {
    "AccessKeyId": "your_access_key_id",
    "AccessKeySecret": "your_access_key_secret",
    "SignName": "your_sign_name"
  }
}

注入 ISmsService:

@inject ISmsService SmsService

var ok = await SmsService.SendSmsAsync("13800000000", "SMS_123456", "{\"code\":\"1234\"}");

验证码(EasyAdminBlazor.Captcha)

.AddEasyAdminBlazorCaptcha(options =>
{
    options.Chars = "0123456789";
})

登录页验证码由 EasyAdminBlazorOptions.EnableLoginCaptcha 控制。字符集、长度等通过 CaptchaOptions 配置。

富文本编辑器(EasyAdminBlazor.HtmlEditor)

.AddEasyAdminBlazorTinyMCEEditor()

配置脚本地址(可自建 CDN 或本地部署):

{
  "TinyMCE": {
    "ScriptSrc": "https://cdn.wang-zhan.cn/tinymce_8.3.2/tinymce.min.js"
  }
}

页面里使用 AdminEditor 组件(见组件文档)。

实时聊天(EasyAdminBlazor.Chat)

.AddEasyAdminBlazorChat()
// ...
app.UseChat();

依赖 Redis:AddEasyAdminBlazorChat() 调用前需先注册 Redis 扩展,未配置 Redis 时聊天不会启用。界面用法见在线聊天。

多租户(EasyAdminBlazor.MultiTenant)

.AddEasyAdminBlazorMultiTenant()

独立数据库、按域名识别租户、菜单与文件隔离。完整说明见多租户。

计划任务(EasyAdminBlazor.Scheduler)

.AddEasyAdminBlazorScheduler()

支持 [Scheduler] 特性标注和 ISchedulerService 动态管理,可视化页面 /Admin/TaskScheduler。完整说明见计划任务。

打印模板(EasyAdminBlazor.Print)

`xml

`

csharp builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions { ... }) // …你现有的扩展链… .AddEasyAdminBlazorPrint(); // 启用打印模板与报表设计器

不引用这个扩展时框架不包含打印页面与打印实现;引用后系统菜单会出现「打印模板」(/Admin/PrintTemplate), 任意 AdminTable 工具栏也会出现打印按钮。设计好的模板可以在列表页/详情页一键打印,也可以在任意组件里注入 PrintService 调用。 完整说明见打印模板。

内容管理(EasyAdminBlazor.Cms)

EasyAdminBlazor.Cms 是面向开发人员的前台快速开发扩展:开发者用 Razor 写页面并用 [CmsPage] / [CmsDataType] 声明内容结构,即可获得自动生成的后台内容管理;内容编辑人员无需改代码,也能管理数据、分类、页面元素、SEO 和评论审核。

<!-- NuGet -->
<PackageReference Include="EasyAdminBlazor.Cms" Version="2.5.0" />
// Program.cs:在 AddEasyAdminBlazor 的扩展链中调用
builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions { ... })
    // …你现有的扩展链…
    .AddEasyAdminBlazorCms();

在宿主项目根组件(通常是 Components/App.razor)的 <body> 末尾、blazor.web.js 之后引入 Live Edit 脚本:

<script src="@Assets["_content/EasyAdminBlazor.Cms/cms-inline-edit.js"]"></script>

CMS 扩展提供按内容类型管理内容、分类、页面元素和页面 SEO 的能力,并自动生成后台管理入口:

  • 数据:/Admin/CmsManage/{ContentType},支持增删改、分页、分类筛选和自定义字段
  • 分类:/Admin/CmsManage/{ContentType} 的“分类”页签
  • 元素:/Admin/CmsManage/{ContentType} 的“元素”页签,引入上述脚本后支持页面内直接编辑
  • SEO:/Admin/CmsManage/{ContentType} 的“SEO”页签

在宿主的 Razor PageModel 上使用 [CmsPage] 声明页面、内容类型和自定义字段;CMS 启动时会自动同步 cms_data、cms_category、cms_field、cms_element、cms_page_seo 表结构,并生成后台菜单与按钮。前台取数使用 ICmsContentService,页面可编辑区域使用 <vc:textblock> 标记。

评论是可选功能,默认关闭:.AddEasyAdminBlazorCms(o => o.EnableComments = true) 开启后才会同步 cms_comment 表、生成后台「评论审核」菜单,前台 ICmsCommentService.AddAsync 才接收提交。关闭时「评论审核」菜单自动隐藏(菜单行和已有评论数据都不删除,重新开启即恢复)。

没有独立前台页面的数据管理入口,用 [CmsDataType] 声明,后台路径为 /Admin/CmsData/{ContentType}。

完整的页面定义、自定义字段、前台取数、元素标记与 Live Edit 用法,见用 EasyAdminBlazor.Cms 开发一个新模块。

应用在线升级(EasyAdminBlazor.Upgrade)

<!-- NuGet(推荐) -->
<PackageReference Include="EasyAdminBlazor.Upgrade" Version="2.4.0" />
builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions { ... })
    // …你现有的扩展链…
    .AddEasyAdminBlazorUpgrade();     // 后台页脚出现「检查更新」;/health 由扩展自动挂载
"Upgrade": {
  "Enabled": true,
  "Source": "Local",              // Local 本地发布目录 / Url 发布索引
  "ReleasesPath": "updates",
  "RestartMode": "WindowsService", // Windows 服务用 WindowsService;systemd 用 Systemd;宝塔/自托管用 Direct
  "ServiceName": "你的服务名",
  "HealthCheckUrl": "http://127.0.0.1:5000"
}

不引用这个扩展就完全没有升级能力(页脚没有入口、没有 /health、发布时也不会生成升级包),老项目行为不变。 发布一次(Release)就会自动生成 updates/v<版本>/update.zip 增量包;把新版本目录和 index.json 拷到服务器 updates/, 管理员在后台点「检查更新 → 立即升级」即可,失败自动回滚、用户不需要重新登录。 Windows 下必须在 Windows 服务(Kestrel + IIS 反代)形态下使用,IIS 进程内托管会自动禁用。 完整说明见应用升级。

轻量多级审批(EasyAdminBlazor.Approval)

.AddEasyAdminBlazorApproval(o =>
{
    o.Flows.Add(new ApprovalFlowConfig
    {
        BillType = typeof(Article).FullName!,
        Levels =
        [
            new ApprovalLevelConfig { Level = 1, Name = "部门主管审批", Kind = ApproverKind.OrgLeader, Offset = 1 },
            new ApprovalLevelConfig { Level = 2, Name = "财务复核", Kind = ApproverKind.Role, Value = "财务" }
        ]
    });
})

业务实体把基类换成 ApprovalEntity / ApprovalEntityFull(或直接实现 IApprovalBill)即接入审批:AdminTable 自动在保存后提交审批、审批中禁止修改删除,审批记录表同时充当待办索引。 需要「审批通过时顺手写业务数据」(例如审批通过即过账写库存),实现 IApprovalPostAction 注册进 DI 即可,钩子在同一事务内执行; 需要把业务异常的可读文案透出给用户(例如「库存不足:可用 64,本次出库 100」),实现 IApprovalFailureMessageProvider 即可。两者都是可选扩展点,不注册时行为不变。 完整说明见审批。

混合缓存(EasyAdminBlazor.FusionCache)

.AddEasyAdminBlazorFusionCache()

用 FusionCache 实现 ICacheService,在内存与 Redis 之间提供混合缓存加速。

微信(EasyAdminBlazor.WeChat)

.AddEasyAdminBlazorWeChat()

配置:

{
  "Wechat": {
    "App": {
      "AppKey": "your_app_key",
      "AppSecret": "your_app_secret"
    },
    "PayV3": {
      "AppId": "",
      "MchId": "",
      "ApiV3Key": "",
      "CertificatePath": "certs/apiclient_cert.pem",
      "KeyPath": "certs/apiclient_key.pem",
      "PubPath": "certs/pub_key.pem",
      "NotifyUrl": "",
      "BaseUrl": "https://api.mch.weixin.qq.com"
    }
  }
}

主要服务:

  • WeChatAppService:小程序登录(code → openid/session_key)、用户数据验签解密、小程序码生成
  • WeChatPayV3Service:Native / JSAPI 下单、回调验签与解密、查询/关闭订单
@inject WeChatPayV3Service WeChatPay

// 创建 PC 扫码支付订单
var result = await WeChatPay.CreateNativePaymentAsync("商品描述", 0.01m, outTradeNo);
if (result.Success)
{
    // result.CodeUrl 用来生成二维码
}

注意事项

  • 扩展包与核心包建议保持同一版本
  • 用不到的扩展不要安装,避免功能臃肿和潜在冲突
  • 微信支付证书文件(certs/)不要提交到代码仓库