StellaOps.Workflow.Analyzer

Roslyn analyzer and source generator for workflow definitions: reports workflow C# that cannot be expressed as a canonical definition (most cases fail the build; delegate forms such as Run whose body breaks no rule warn with WF021) and generates the registry of bundled definitions.

PackageStellaOps.Workflow.Analyzer
ComponentWorkflow
LicenceBUSL-1.1 (Workflow licence)
Package kindAnalyzer
Target frameworknetstandard2.0

To add the package to a project, see Installing Stella Ops packages.

The package adds a Roslyn analyzer to the projects that reference it. The compiler reports the diagnostics below; a project can change their severity in .editorconfig.

Diagnostics

IDSeverityTitleMessage
WF001ErrorImperative control flow is not canonicalizable‘{0}’ is not canonicalizable to workflow JSON; use builder.WhenExpression / Fork / Repeat instead
WF002ErrorAsync/await is not canonicalizable‘{0}’ is not canonicalizable to workflow JSON; workflow code must be synchronous and pure
WF003ErrorCall target is not canonicalizableCall to ‘{0}’ in assembly ‘{1}’ is not canonicalizable; only calls to StellaOps.Workflow.* or project-referenced helpers are allowed in workflow code
WF004ErrorObject creation is not canonicalizableInstantiation of ‘{0}’ from assembly ‘{1}’ is not canonicalizable; only StellaOps.Workflow.* types or project-referenced declarations are allowed
WF005ErrorC# conditional operator is not canonicalizable‘{0}’ resolves at workflow-build time, not at workflow-execution time; use WorkflowExpr.Func(“if”, …) or WorkflowExpr.Func(“coalesce”, …) instead
WF006ErrorField or property access is not canonicalizableReading ‘{0}’ from assembly ‘{1}’ bakes build-time state into the canonical definition; use WorkflowExpr.Path(…) to reference runtime state, WorkflowExpr.String/Number/Bool for literals, or a compile-time const
WF010ErrorHelper reachable from workflow contains non-canonical constructHelper ‘{0}’ (reachable from workflow code) contains a non-canonical construct: {1}
WF020ErrorDeclarative workflow class cannot be read as a workflowThe canonical artifact generator cannot read this class as a workflow: {0}
WF021WarningWorkflow not bundled by the canonical artifact generatorThe canonical artifact generator cannot evaluate this at compile time, so the workflow is not bundled and the publisher compiles it when it starts: {0}

WF001

Workflow definitions must be declarative. Statement-level C# branching or iteration (if, for, foreach, while, switch-statement, try, throw, lock, using, goto) cannot be serialized into the canonical workflow JSON and is therefore rejected. Express branching with builder.WhenExpression / Fork / Repeat and express conditions with WorkflowExpr.* operators.

WF002

The workflow Spec is constructed once, synchronously. await / async / Task.Run / Thread are runtime concurrency primitives that cannot be represented in the canonical workflow definition.

WF003

Workflow code may only call into the StellaOps.Workflow.* builder API, or into helpers whose source is available in the current compilation or a project reference (so the analyzer can verify they are canonicalizable). Calls into compiled NuGet/framework assemblies cannot be walked and are therefore rejected.

WF004

Workflow code may only instantiate StellaOps.Workflow.* types (e.g., EndpointAddress, WorkflowBusinessReferenceDeclaration, WorkflowNamedExpressionDefinition) or project-referenced declarative helper types. Instantiating anything else cannot be serialized into the canonical workflow JSON.

WF005

Using C# ternary (?:), null-coalescing (??), or null-conditional (?.) operators in workflow code ties the canonical JSON to whatever value those operators resolve to when the workflow Spec is constructed. Express runtime conditions with WorkflowExpr.Func(“if”, condition, trueExpr, falseExpr) / WorkflowExpr.Func(“coalesce”, a, b).

WF006

Reading a non-const field or property on a type from a compiled assembly (not a trusted workflow assembly, and not project-reference source) evaluates at workflow-build time. The resulting canonical JSON depends on whatever value that field/property held when the workflow Spec was constructed — machine name, current time, environment variables, etc. Use WorkflowExpr.Path(“start.*” | “state.*” | “payload.*” | “result.*”) for runtime-bound values or a compile-time const for build-time constants.

WF010

A method reachable from workflow code contains a non-canonical C# construct (if, for, throw, LINQ, etc.). NOTE: Helper methods whose return type comes from a trusted workflow assembly are EXEMPT — they are compile-time construction factories whose body is metaprogramming, not runtime workflow logic. An assembly is trusted when it is one of this product’s own workflow assemblies, when it carries [WorkflowTrustedAssembly], or when its name matches a prefix listed in the stellaops_workflow_trusted_assembly_prefixes analyzer option. If you see this diagnostic, the helper either returns a non-workflow type or returns a type from an assembly that has not opted in.

WF020

The class implements IDeclarativeWorkflow<T> but has no Spec property, so neither the canonical artifact generator nor the runtime compiler can build its definition. Give the class a Spec property built with WorkflowSpec.For<T>().

WF021

The generator bundles a workflow’s canonical definition only when it can evaluate every builder call at compile time. For any other construct the workflow still compiles and runs; it is left out of the bundle and listed for runtime compilation, and the publisher compiles it with the runtime compiler (WorkflowCanonicalDefinitionCompiler) when it starts. A construct whose value comes from a C# delegate (Run, or a payload, signal name, timer delay or condition given as a delegate) has no canonical definition at all: the runtime compiler rejects it (WFCD codes), so the publisher reports the workflow as not publishable. Use the WorkflowExpr form of the construct instead.