后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载本篇技术指南聚焦 Elsa Workflow Engine.NET的Output Converters输出转换器机制它允许扩展模块把一个 Activity 的原生输出为某一个绑定的变量或工作流输出做一次显式的、可选的转换。读完本文你将掌握如何实现并注册一个带稳定 ID 的转换器、如何在OutputT绑定上配置转换器、转换器在定义校验与运行时分别经历哪些检查、失败如何进入故障管线并保持隐私安全以及 Studio 与 API 如何基于服务器端注册表做发现式消费。相关设计决策记录于 ADR 0011、ADR 0012 与 ADR 0013。一、设计定位转换是显式、可选、发生在绑定边界的输出转换器要解决的问题非常具体一个活动产出的是其原生输出native output例如HttpResponseMessage、decimal或任意自定义类型而绑定到某个变量或工作流输出时下游往往需要另一种形态的值。转换器就是为这一个绑定定制的单向变换。理解这个机制先要记住四条边界见 ADR 0011转换发生在绑定边界且是同步的Activity 的输出寄存器activity output register、日志、API、诊断信息中保留的始终是原生值只有最终写入变量或工作流输出的绑定值会被转换。显式且可选绑定没有配置 converter 时走原有的直接赋值路径——不产生任何转换相关的查找、校验、处理或内存分配配置了才生效。不做隐式推断Core 永远不会根据源类型 目标类型的组合自动推导一个转换器见 ADR 0012。转换必须通过明确的 converter ID 选定。排除在外的场景异步转换、Activity 输入input转换、表达式强制类型转换、转换器链式串联以及没有目的地的转换器配置都不属于此边界。从源码看绑定模型Output上新增了一个可选属性ConverterOutput.cs类型为OutputConverterConfiguration。写入绑定时ActivityExecutionContext.Set 先判断output?.Converter null为空则直接ExpressionExecutionContext.Set并记录原生活动输出非空才进入转换路径——先把原生值写入活动输出寄存器再解析绑定目的地并调用IOutputConverterInvoker最后把转换结果写为绑定值。这条实现路径正是原生值保留、绑定值转换的落地保证。二、实现并注册一个转换器2.1 实现IOutputConverter转换器必须实现 IOutputConverterpublic interface IOutputConverter { /// summary把非空的原生输出值转换为绑定值。/summary object? Convert(OutputConversionContext context); /// summary校验每个绑定可选的设置项返回的消息不得包含敏感设置值。/summary IEnumerablestring ValidateSettings(JsonElement? settings) []; }核心契约约束如下同步、确定性、无副作用接口文档明确要求实现必须满足这三条。不要在此执行 I/O、不要修改工作流状态。Convert只处理非空值null 原生值会绕过转换器详见第五节。可选实现ValidateSettings默认返回空集合视为通过。注意校验消息中不得泄露具体设置值避免把敏感内容带进错误信息。上下文是窄且不可变的OutputConversionContext 只包含四样东西——非空的原生值Value、活动输出声明的SourceType、绑定目的地声明的DestinationType、以及克隆后的可选 JSONSettings。依赖如格式化器、本地化服务通过构造函数注入获取。官方示例——一个把decimal按显式不变文化invariant格式转成文本的转换器using System.Globalization; using System.Text.Json; using Elsa.Extensions; using Elsa.Workflows; using Elsa.Workflows.Models; public sealed class NumberToTextConverter : IOutputConverter { public object Convert(OutputConversionContext context) { var format context.Settings?.TryGetProperty(format, out var value) true ? value.GetString() : null; return ((decimal)context.Value).ToString(format, CultureInfo.InvariantCulture); } }实现要点设置项从context.Settings读取JSON 属性访问Value按声明的源类型强转返回值的类型必须与描述符声明的ResultType兼容。仓库测试中也有同款模式例如 ReferenceOutputConverter 从 settings 读取prefix前缀后拼接字符串并用实例InstanceId证明转换器实例按需从作用域解析、注册表不缓存实例这一行为。2.2 注册并生成描述符用AddOutputConverterT扩展方法注册OutputConverterServiceCollectionExtensions.csusing var schemaDocument JsonDocument.Parse( {type:object,properties:{format:{type:string}}}); services.AddOutputConverterNumberToTextConverter( new OutputConverterDescriptor( sample.number-to-text.v1, typeof(decimal), typeof(string), Number to text, Formats a decimal using an explicit invariant format., schemaDocument.RootElement));OutputConverterDescriptor 是只描述、不暴露实现的只读记录字段如下字段类型含义Idstring稳定、区分大小写的转换器 ID持久化公共契约SourceTypeType转换器接受的声明源类型ResultTypeType转换器产出的声明结果类型DisplayNamestring通过发现 API 暴露的显示名Descriptionstring?可选描述SettingsSchemaJsonElement?可选的、每绑定设置的 JSON Schema不可变构造时克隆注册时的内部机制值得注意OutputConverterRegistryID 不能为空且源/结果类型不能是开放泛型open generic否则抛InvalidOperationException。ID 唯一且大小写敏感重复注册、或两个注册仅大小写不同OrdinalIgnoreCase 比较命中都会抛异常。注册表内部用StringComparer.Ordinal建字典——查找是区分大小写的精确匹配。keyed serviceAddOutputConverter会把实现类注册为以 converter ID 为 key 的 keyed service默认ServiceLifetime.Scoped并把一个单例OutputConverterRegistration连同描述符注册到容器。注册表缓存的是描述符与注册信息不是转换器实例默认作用域生命周期下每次转换时 Elsa 从当前活动工作流执行作用域的ServiceProvider通过GetRequiredKeyedServiceIOutputConverter(id)解析实现见 OutputConverterInvoker。构造函数注入的依赖因此能正确绑定到当前工作流上下文。2.3 转换器 ID 的版本化契约转换器 ID 是持久化的公共契约写进工作流 JSON 的字段查找区分大小写绑定中写的 ID 必须与注册时完全一致不要复用同一个 ID 去改变行为、设置语义或结果类型——这会破坏已发布工作流的既有含义行为或设置发生破坏性变化时注册一个新的带版本号的 ID如sample.number-to-text.v1→sample.number-to-text.v2。三、在OutputT绑定上配置转换器转换器的配置属于绑定本身而非活动或变量activity.Result new Outputdecimal(targetVariable) { Converter new OutputConverterConfiguration( sample.number-to-text.v1, JsonDocument.Parse({format:0.00}).RootElement) };OutputConverterConfiguration 只有两个成员Id选择注册的转换器和可选的Settings克隆后不可变的 JSON 设置。序列化后工作流 JSON 中该绑定会额外多出一个可选对象converter序列化实现见 OutputJsonConverterT 与写入侧 #L85-L91{ typeName: Decimal, memoryReference: { id: formatted-total }, converter: { id: sample.number-to-text.v1, settings: { format: 0.00 } } }要点converter是可选对象绑定没有转换器时整个converter键省略序列化与反序列化都保留原赋值路径。JSON 中只持久化id与settings绝不持久化 CLR 类型、描述符、实现类实例或显示元数据见 ADR 0013。客户端模型同样只暴露Id与Settings见 ActivityOutput.cs与服务器端契约对齐。四、校验定义期与运行期的双重检查4.1 定义期校验接受/物化定义时Elsa 在定义校验阶段就会检查绑定的转换器配置。处理器 ValidateOutputConverters 监听WorkflowDefinitionValidating通知逐活动逐输出执行下列检查converter ID 非空AddError(a converter ID is required.)绑定存在可解析的变量或工作流输出目的地——没有目的地的转换器配置直接被拒绝a converter can only be configured when the output has a variable or workflow-output destination.converter ID 已注册converter ... is not registered.声明的输出类型与转换器源类型兼容用descriptor.SourceType.IsAssignableFrom(outputDescriptor.Type)判定转换器结果类型可赋给目的地类型CanAssign同时考虑普通可赋值性与可空目标Nullable.GetUnderlyingType两种情况设置校验通过解析出 keyed 服务实例后调用settingsValidator.Validate任何失败都会以converter ... settings are invalid: ...追加到校验错误集合。从实现看目的地可解析由IOutputBindingDestinationResolver负责转换器实例解析失败也会被捕获并报could not be resolved。4.2 运行期检查绑定写入时即使在定义期校验通过运行时 Elsa 仍会重复安全核查。写入绑定的完整链路在 ActivityExecutionContext.Set 与 OutputConverterInvoker.Invoke 中按阶段推进Resolution解析注册表按 ID 查找描述符找不到则失败。同样目的地解析失败destination null也在此阶段失败。SourceCompatibility源兼容运行时值必须是源类型的实例IsRuntimeValueCompatible同时处理可空底层类型且描述符源类型可被活动声明类型赋值两者不满足即失败。ResultValidation结果预校验描述符结果类型必须可赋给目的地类型含可空目标。实例解析从活动工作流执行作用域解析 keyed 转换器实例失败归入 Resolution 阶段。SettingsValidation设置校验IOutputConverterSettingsValidator校验描述符 Schema 转换器自定义ValidateSettings任何错误信息或异常都归入此阶段失败。Invocation调用调用converter.Convert(new OutputConversionContext(...))异常归入此阶段。ResultValidation结果后校验转换结果为 null 时仅当目的地允许 null 才交付否则失败非 null 结果必须同时与结果类型、目的地类型运行时兼容否则失败。阶段清单完整定义于 OutputConversionFailureStageResolution、SettingsValidation、SourceCompatibility、Invocation、ResultValidation。4.3 失败语义目的地不变、原生值保留关键保证ADR 0011转换与结果校验完成于写入目的地之前——任何失败都让目的地保持原值不变组件测试断言变量保持unchanged见 OutputConverterTests活动输出寄存器始终保留原生值供诊断使用失败时同样如此。五、失败进入活动故障管线隐私安全的OutputConversionException运行期失败通过 Elsa 常规的活动故障管线activity fault pipeline传播异常类型为 OutputConversionException它实现ISafeExceptionMetadataProvider保证持久化的异常状态只含安全的结构化身份与失败阶段包含ConverterId、Stage、ActivityId、ActivityType、OutputName、SourceTypeName以及可选的DestinationId、DestinationTypeName明确排除原生值、原始设置 JSON、以及转换器内部异常的细节。GetSafeMetadata()返回的字典就是持久化进 incident 的元数据。消息模板本身也是隐私安全的Output converter {id} failed during {stage} for output {name} of activity {id}.不包含具体值。组件测试 OutputConverterTests.cs 验证了完整行为配置一个未注册的 IDtests.component.missing→ 工作流以Faulted子状态结束 → incident 异常类型为OutputConversionException→ 元数据中ConverterId/StageResolution存在 →incident 消息不包含native value。关于 null 值的两条规则同时出现在 ADR 0011 与调用器实现中null 原生值绕过转换调用直接跳过 converter仅交付给允许 null 的目的地destination.AllowsNull否则在 ResultValidation 阶段失败转换器产出的 null 只对可空目的地有效非空目的地收到 null 结果即失败。六、发现 API 与 Studio 集成6.1 服务器端注册表与GET /descriptors/output-converters转换器目录catalog由Core 拥有IOutputConverterRegistryListAll()、按 IDFind、按 ID 查FindRegistration、以及按源/目标类型查FindCompatible。FindCompatible的实现OutputConverterRegistry.cs同时做源类型可赋值与结果类型可赋目的地两向过滤。API 端点 Endpoint.cs 暴露发现能力GET /descriptors/output-converters?sourceTypeDecimaldestinationTypeString鉴权要求read:*或read:output-converters实现为RequirePermission(WorkflowPermissions.DescriptorsOutputConverters, CoreVerbs.View)。查询参数sourceType与destinationType均为必填且必须是通过序列化类型注册表可解析的安全类型名或注册别名缺失或传不安全类型名返回 400错误消息明确见端点测试 OutputConverterEndpointTests.cs。响应内容兼容的转换器列表每个条目只含Id、SourceTypeName、ResultTypeName、DisplayName、Description与可选SettingsSchemaOutputConverterDescriptorModel。安全边界响应永不暴露转换器实例、实现类型CLR type、keyed service key 或服务生命周期——端点测试明确断言响应模型中不存在SourceType、ResultType、ServiceKey、ServiceLifetime这类 CLR 属性#L58。6.2 Studio 的 schema 驱动表单Studio 通过上述发现 API 获取兼容转换器及其可选 settings Schema对简单的 object SchemaStudio 渲染 schema 驱动的字段表单对其他复杂 Schema退化为原始 JSON 对象编辑器未知的持久化 converter ID 仍然可见旧数据里引用的、当前服务器未注册的 ID 不会被隐藏向后兼容不支持发现 API 的旧服务器不会导致 Studio 删除已存在的转换器配置——发现服务只是目录来源不是配置清洗器。七、操作指南与最佳实践官方文档给出的四条操作性约束每条都有明确的工程理由把环境相关选择显式设为设置locale、时区、舍入方式等会随宿主环境变化的行为必须作为显式 settings如format传入保证转换器确定性与可复现。禁止 I/O 与状态变更转换器内不得访问文件、网络、数据库不得修改工作流状态——这是同步、无副作用契约的直接推论否则会破坏执行语义与可诊断性。把转换器下架视为部署漂移删除一个转换器注册后已发布工作流中引用它的绑定会在赋值时故障Resolution 阶段需与工作流版本一起规划下线。异步或有副作用的需求交给 Activity需要异步、I/O、副作用或链式处理时应改用活动输入activity inputs或写一个显式的转换活动而不是扩展转换器。八、与测试、扩展生态的关系测试即规范组件测试 OutputConverterTests.cs 验证转换值写入变量/工作流输出 原生值保留在活动输出寄存器双断言OutputConverterEndpointTests.cs 验证路由、鉴权、过滤与安全元数据暴露单元测试目录test/unit/Elsa.Workflows.Core.UnitTests/OutputConverters/覆盖注册、调用器、注册表、绑定目的地解析、异常状态与序列化OutputJsonConverterTests.cs等全部侧面。生态定位Core 只交付基础设施与测试/示例中的参考转换器生产模块自行注册语义归自己所有的转换器Core 不提供宽泛的强制类型转换目录ADR 0013。这意味着你要为自己的模块或应用添加转换能力时遵循本文第二节的实现 注册流程即可转换器会立刻进入发现目录供 Studio 与 API 消费。九、关键事实速查主题结论证据位置转换边界同步、显式、仅作用于绑定值原生值始终保留ADR 0011、ActivityExecutionContext.Set契约接口IOutputConverterConvert 可选ValidateSettingsIOutputConverter.cs注册AddOutputConverterT默认 Scoped、ID 作 keyed service keyOutputConverterServiceCollectionExtensions.csID 规则区分大小写、唯一、语义不可变、变更需新版本 IDADR 0012、OutputConverterRegistry.cs失败阶段Resolution / SettingsValidation / SourceCompatibility / Invocation / ResultValidationOutputConversionFailureStage.cs异常安全结构化身份 阶段不含原生值、原始设置、内部异常细节OutputConversionException.cs发现 APIGET /descriptors/output-converters需read:*/read:output-convertersEndpoint.cs结论Output Converters 是 Elsa 3 在活动输出 → 绑定值边界上提供的一把精确工具——它用显式的版本化 ID、同步无副作用的转换器、定义期运行期双重校验、隐私安全的异常与服务器端发现目录把格式转换从活动实现中剥离出来变成可注册、可发现、可配置的独立能力。在你自己的模块中遵循实现 IOutputConverter AddOutputConverter 注册 绑定中配置 converter三步即可复用到这一完整机制。赞分享后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载相关推荐Elsa Workflows 输出转换同步绑定机制Activity Output 与 Bound Value 的边界设计深度解析Elsa Workflows 输出转换同步绑定机制Activity Output 与 Bound Value 的边界设计深度解析 导读 本文基于 Elsa W后端工作流自动化流程编排低代码Elsa Workflows 输出转换器Output Converter的显式稳定身份设计Converter ID、注册约束与运行时校验体系Elsa Workflows 输出转换器Output Converter的显式稳定身份设计Converter ID、注册约束与运行时校验体系 导读 本文以后端工作流自动化流程编排低代码niri 输出Output配置完全指南模式、缩放、旋转、定位与 VRRniri 输出Output配置完全指南模式、缩放、旋转、定位与 VRR 本指南系统讲解 niri 滚动平铺 Wayland 合成器中 output 配置段图形学上一篇Asciidoctor.js扩展开发完全指南自定义处理器与模板引擎下一篇红队工具生态Awesome Red Teaming中的性能优化与资源占用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考