Easy.WorkFlow.FluentBuilder 2.3.17

Easy.WorkFlow.FluentBuilder

Easy.WorkFlow.FluentBuilder 是一个基于 .NET 的工作流 Fluent API 构建包，为 Easy.WorkFlow.Core 提供以编程方式构建和持久化工作流定义的能力。本库支持 .NET 6、.NET 7、.NET 8 和 .NET 9。

功能特性

• 流畅的 API 设计：采用链式调用的 Fluent API 风格构建工作流
• 代码优先：使用强类型 C# 代码定义工作流结构和行为
• 步骤嵌套：支持复杂的工作流步骤和条件分支
• 内联步骤：支持直接在工作流定义中编写步骤处理逻辑
• 条件分支：基于表达式支持复杂的条件分支逻辑
• 自动注册：支持自动发现和注册工作流定义
• 持久化：自动将工作流定义持久化到数据存储
• 自动流转：支持步骤自动流转执行下一步

更新日志

• 2.3.17
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.14 版本
• 2.3.16
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.13 版本
• 2.3.15
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.12 版本
• 2.3.14
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.11 版本
• 2.3.13
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.10 版本
• 2.3.12
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.9 版本
  • 调整：内联步骤处理器在asp.net core环境中可通过context.ServiceProvider解析服务。
• 2.3.11
  • 升级：依赖 Easy.WorkFlow.Core 到 2.3.8 版本
  • 新增：内联步骤处理器在asp.net core环境中可通过context.ServiceResolver解析服务。
• 2.3.10
  • 新增：新增注册选项RegisterOptions,当开启EnableBackgroundRegisterService，会注入后台注册服务完成所有工作流的注册。
• 2.3.9
  • 依赖 Easy.WorkFlow.Core 到 2.3.7 版本
• 2.3.8
  • 修复：修复withid未生效的问题；
  • 升级：升级Easy.WorkFlow.Core到2.3.6版本,具体见 [Easy.WorkFlow.Core 更新日志]
• 2.3.7
  • 新增：IStepBuilder增加WithBtns方法，配置自定义步骤按钮；IWorkFlowBuilder增加Begin重载方法；IWorkFlow增加创建用户信息属性
• 2.3.6
  • 非内联处理器（实现IStepHandler处理器）支持依赖注入服务
• 2.3.5
  • 依赖 Easy.WorkFlow.Core 到 2.3.5 版本
• 2.3.4
  • 依赖 Easy.WorkFlow.Core 到 2.3.4 版本
• 2.3.3
  • 依赖 Easy.WorkFlow.Core 到 2.3.3 版本
• 2.3.1
  • 依赖 Easy.WorkFlow.Core 到 2.3.1 版本
• 2.3.0
  • 依赖 Easy.WorkFlow.Core 到 2.3.0 版本

安装

使用 NuGet 包管理器安装: dotnet add package Easy.WorkFlow.FluentBuilder

快速开始

1. 注册服务

在 Program.cs 或 Startup.cs 中注册 FluentBuilder 服务：

// 注册工作流核心服务
services.AddWorkFlow();

// 注册工作流存储服务 (以 SqlSugar 为例)
services.AddWorkFlowSqlSugar(options => {
    options.ConnectionString = "您的数据库连接字符串";
    options.DbType = DbType.SqlServer; // 或其他数据库类型
});

// 注册 Fluent Builder 服务
services.AddFluentBuilder();

2. 定义工作流数据模型

首先定义工作流中使用的数据模型：

public class LeaveRequest
{
    public string? EmployeeName { get; set; }
    public int Days { get; set; }
    public string? Reason { get; set; }
    public bool IsUrgent { get; set; }
    public string? Type { get; set; }
    
    // 审批人相关信息
    public User? Manager { get; set; }
    public User? DepartmentHead { get; set; }
}

public class User
{
    public long UserId { get; set; }
    public string? UserName { get; set; }
}

3. 定义工作流

创建一个实现 IWorkFlow<TData> 接口的类来定义工作流：

public class LeaveRequestWorkflow : IWorkFlow<LeaveRequest>
{
    public long Id => 1001;
    public string Name => "请假申请工作流";
    public string? Description => "员工请假申请和审批流程";
    public int Version => 1;
    public string? FormName => "请假表单";

    public void Build(IWorkFlowBuilder<LeaveRequest> builder)
    {
        builder
            .Begin<SubmitRequestStep>()
                .WithId(101)
                .WithName("提交请假申请")
                .WithDescription("员工提交请假申请")
            .Then<ManagerApprovalStep>(step => step
                .WithId(102)
                .WithName("经理审批")
                .WithDescription("部门经理审批请假申请")
                .WithActorsExpression("[Manager]"))
            .When(request => request.Days < 3, async (context)=>
                {
                     // 内联处理器，执行业务逻辑...
                })
                .WithId(103)
                .WithName("HR审批")
                .WithDescription("人力资源部审批短时间请假")
                .WithActorsExpression("[DepartmentHead]")
            .When(request => request.Days > 3, async (context)=>
                {
                     // 内联处理器，执行业务逻辑...
                })
                .WithId(103)
                .WithName("总经理审批")
                .WithDescription("总经理审批长时间请假")
                .WithActorsId(10003).WithActorsName("张总");
    }
}

4. 定义步骤处理器

为工作流中的每个步骤创建处理器类，实现 IStepHandler 接口：

public class SubmitRequestStep : IStepHandler
{
    public async Task ExecuteAsync(WorkFlowExcutionContext context)
    {

        // 执行业务逻辑...

        // 自动执行下一步骤（如果不需要中断，不需要通过审批，那么可以手动执行下一步）
        if (context.HasNext && context.Next != null)
        {
            await context.Next(context);
        }
    }
}

5. 使用内联步骤处理器

您也可以使用内联步骤处理器直接在工作流定义中定义处理逻辑：

builder
    .Begin<SubmitRequestStep>()
    .Then(async context => {
        // 内联处理逻辑

        // 自动执行下一步骤（如果有）
        if (context.HasNext && context.Next != null)
        {
            await context.Next(context);
        }
    })
    .When(request => request.IsUrgent, context => {
        // 紧急请假处理逻辑
     
    });

6. 注册和启动工作流

在应用启动时自动注册所有工作流：

// 在 Program.cs 中注册所有IWorkflow
var app = builder.Build();
await FluentBuilderRegister.RegisterWorkflow(app.Services);

//或手动注册特定工作流：
public class WorkflowService
{
    private readonly IWorkflowRegister _register;
    
    public WorkflowService(IWorkflowRegister register)
    {
        _register = register;
    }
    
    public async Task RegisterLeaveWorkflow()
    {
        // 注册特定的工作流
        await _register.Register<LeaveRequestWorkflow, LeaveRequest>();
    }
}

高级用法

条件分支

使用 When 方法创建条件分支：

builder
    .Begin<InitialStep>()
    .Then<ProcessStep>()
    .When(data => data.Amount > 10000, step => step
        .WithName("高额审批")
        .WithActorsExpression("[seniorManager]"))
    .When(data => data.Amount <= 10000, step => step
        .WithName("常规审批")
        .WithActorsExpression("[manager]"));

指定步骤处理人

有多种方式指定步骤的处理人：

// 使用用户ID
step.WithActorsId(1001, 1002, 1003);

// 使用用户名称
step.WithActorsName("张三", "李四", "王五");

// 使用用户ID
step.WithActors(new List<(long, string)>
{
    (1001, "张三"),
    (1002, "李四"),
    (1003, "王五")
});

// 使用表达式（会在运行时解析）
step.WithActorsExpression("[department.managers]");

自定义步骤属性

builder
    .Begin<StartStep>(step => step
        .WithId(101)               // 设置步骤ID
        .WithName("开始步骤")       // 设置步骤名称
        .WithDescription("这是工作流的开始步骤") // 设置步骤描述
        .WithNumber(1)             // 设置步骤序号
    );

步骤自动流转

当一个步骤处理完成后，可以自动执行下一个步骤，无需用户手动触发： 适用于无需审批中断的工作流，审批流程一般不适用。

public class AutoFlowStep : IStepHandler
{
    public async Task ExecuteAsync(WorkFlowExcutionContext context)
    {
        // 处理当前步骤逻辑
        Console.WriteLine("当前步骤处理完成");
        
        // 检查是否有下一步骤
        if (context.HasNext && context.Next != null)
        {
            // 自动执行下一步骤
            await context.Next(context);
        }
    }
}

注意

• Easy.WorkFlow.FluentBuilder定义工作流时需要手动定义唯一的id。
• Easy.WorkFlow.FluentBuilder不会注册自己的IWorkFlowBuilder到IOC容器中，即不会替换你注册的IWorkFlowBuilder。他使用IWorkflowRegister注册工作流。

与其他包集成

Easy.WorkFlow.FluentBuilder 可以与 Easy.WorkFlow 生态系统中的其他包一起使用：

• Easy.WorkFlow.Core：工作流核心库
• Easy.WorkFlow.SqlSugar：提供基于 SqlSugar 的工作流存储实现
• Easy.WorkFlow.AspNetCore：提供 ASP.NET Core 集成
• Easy.WorkFlow.JsonBuilder：提供基于 JSON 的工作流定义能力

工作流执行模型

Easy.WorkFlow.FluentBuilder 定义的工作流会被持久化到数据库，并可以通过 Easy.WorkFlow.Core 的工作流引擎执行：

1. 启动工作流：使用工作流服务启动特定 ID 的工作流，会激活一个工作流实例。
2. 执行步骤：使用工作流服务运行步骤，每个步骤会按照定义的顺序和条件执行，可以携带审批意见等信息
3. 条件分支：工作流服务根据条件表达式自动解析下一步的执行路径
4. 完成工作流：当所有步骤执行完毕时，工作流实例完成

依赖项

• Easy.WorkFlow.Core >= 2.3.0

许可证

Easy.WorkFlow.FluentBuilder 使用 MIT 许可证。