Workflow Foundation

Windows Workflow Foundation

Trigger On

• working on WF activities, workflows, or designer-backed process logic
• reviewing long-lived workflow state and persistence behavior
• assessing whether to keep, isolate, or replace Workflow Foundation

Workflow

1. Treat WF as legacy infrastructure and start by understanding what workflow behavior is still business-critical before proposing replacement. 2. Separate workflow host concerns, activity logic, persistence, and integration points so risk is visible. 3. Avoid half-migrations that leave workflow state and business rules split across two orchestration systems without ownership. 4. If replacement is needed, define explicit equivalence for triggers, compensation, persistence, and audit expectations. 5. Stabilize current behavior with targeted tests or scenario captures before changing designer-driven artifacts. 6. Validate with representative long-running and failure scenarios, not just a single successful execution path.

Deliver

• practical maintenance or migration guidance for WF
• clear boundaries around host, workflow, and persistence responsibilities
• risk-aware change plans for legacy process logic

Validate

• business-critical workflow behavior is identified before change
• migration work preserves state and audit expectations
• designer artifacts are treated carefully

References

• Migration Guidance - decision framework for keeping, replacing, or isolating WF; migration targets and steps; common pitfalls
• Maintenance Patterns - host management, persistence, activity design, testing, and operational patterns for WF systems

Windows Workflow Foundation Migration Guidance

Migration Decision Framework

When to Keep WF

• Long-lived workflow instances with active persisted state
• Complex compensation and rollback logic that is well-tested
• Designer artifacts that encode irreplaceable business rules
• Compliance or audit requirements tied to existing WF persistence
• No clear business driver to modernize

When to Replace WF

• .NET Core or .NET 5+ migration is required
• Workflow logic is simple and can be expressed as state machines or sagas
• Active development is needed but WF expertise is unavailable
• Hosting infrastructure is being decommissioned
• Persisted state can be drained or migrated

When to Isolate WF

• Core application moves to modern .NET but workflow behavior must survive
• WF host can run as a standalone service behind an API boundary
• Migration is planned but not immediate
• Risk of touching designer artifacts is too high

Migration Targets

Durable Task Framework

• Best fit for long-running orchestrations in Azure
• Supports fan-out, fan-in, and human interaction patterns
• State persistence via Azure Storage or SQL
• Works with Azure Functions or standalone hosts

Elsa Workflows

• Open-source workflow engine for .NET
• Designer support via web-based workflow builder
• Supports persistence, versioning, and long-running workflows
• Good fit when visual design continuity matters

MassTransit Sagas

• Best fit for event-driven process orchestration
• State machine semantics with explicit states and transitions
• Persistence via Entity Framework or other stores
• Good fit when messaging is already part of the architecture

Custom State Machines

• Best fit for simple, well-understood process logic
• No external dependencies beyond your own code
• Suitable when WF was overkill for the original problem

Migration Steps

1. Inventory Current State

• List all workflow types and their purpose
• Identify persisted instances and their expected lifespan
• Document integration points: triggers, external calls, compensation
• Map designer artifacts to business rules they encode

2. Define Equivalence Criteria

• What triggers must produce the same downstream effects?
• What compensation or rollback behavior must be preserved?
• What audit or compliance records must survive migration?
• What monitoring or alerting depends on current workflow state?

3. Drain or Migrate Persisted State

Options:

• Wait for all instances to complete naturally
• Export state and replay into new system
• Run dual systems with routing based on instance creation date
• Accept state loss with stakeholder approval

4. Build Replacement Logic

• Start with the simplest possible implementation
• Add compensation and rollback only where equivalence requires it
• Test with representative scenarios from production
• Preserve audit trail expectations

5. Validate and Cut Over

• Run parallel comparison if feasible
• Validate edge cases: failures, timeouts, retries
• Monitor for unexpected behavior post-cutover
• Keep WF host available for rollback window

Common Pitfalls

Half-Migrations

Running two orchestration systems without clear ownership leads to:

• Duplicated business rules
• Inconsistent state
• Unclear error handling responsibility
• Increased operational burden

Designer Artifact Assumptions

Designer-generated code may contain:

• Implicit ordering assumptions
• Hidden state transitions
• Compensation logic that is not obvious from the visual representation
• Version-specific serialization behavior

Persistence Format Changes

WF persistence stores:

• Serialized workflow instance state
• Bookmark and continuation data
• Custom tracking records

Migration must account for:

• Deserialization compatibility
• Bookmark resolution in the new system
• Tracking data continuity

Underestimating Compensation

WF compensation scopes may encode:

• Multi-step rollback sequences
• External system reversals
• Audit record generation
• Notification triggers

Replacement systems must explicitly handle these cases.

References

• Windows Workflow Foundation Docs
• Durable Task Framework
• Elsa Workflows
• MassTransit Sagas

Windows Workflow Foundation Maintenance Patterns

Host Management Patterns

Isolated Workflow Host

Keep WF hosting separate from application logic:

┌─────────────────────────────────────────┐
│           Application Layer             │
├─────────────────────────────────────────┤
│        Workflow Service API             │
├─────────────────────────────────────────┤
│         WF Host Process                 │
│  ┌─────────┐ ┌─────────┐ ┌──────────┐  │
│  │ Runtime │ │ Persist │ │ Tracking │  │
│  └─────────┘ └─────────┘ └──────────┘  │
└─────────────────────────────────────────┘

Benefits:

• Clear deployment boundary
• Independent scaling and lifecycle
• Easier to replace or isolate later

Workflow Service Facade

Wrap WF operations behind a service interface:

public interface IWorkflowService
{
    Task<Guid> StartWorkflowAsync(string workflowType, object input);
    Task<WorkflowStatus> GetStatusAsync(Guid instanceId);
    Task ResumeBookmarkAsync(Guid instanceId, string bookmarkName, object value);
    Task CancelAsync(Guid instanceId);
}

Benefits:

• Decouples callers from WF internals
• Enables future replacement without client changes
• Simplifies testing and mocking

Persistence Patterns

Controlled Persistence Points

Avoid implicit persistence; make persistence decisions explicit:

• Use NoPersistScope for transient operations
• Document persistence assumptions in activity code
• Test recovery from each explicit persistence point

Persistence Health Monitoring

Track persistence store health:

public class PersistenceHealthCheck
{
    public async Task<bool> CanPersistAsync()
    {
        // Attempt lightweight write/read cycle
        // Monitor persistence latency
        // Alert on degradation
    }
}

Instance Lifecycle Management

Define clear policies for:

• Maximum instance age before forced completion or termination
• Orphaned instance detection and cleanup
• Persisted state backup and retention

Activity Patterns

Idempotent Activities

Design activities to be safely re-executed:

public sealed class IdempotentActivity : CodeActivity
{
    protected override void Execute(CodeActivityContext context)
    {
        var operationId = context.WorkflowInstanceId.ToString() + "_" + context.ActivityInstanceId;

        if (AlreadyExecuted(operationId))
        {
            // Return cached result
            return;
        }

        // Execute and record result
    }
}

Compensation-Aware Activities

Structure activities to support rollback:

public sealed class BookableResourceActivity : NativeActivity
{
    protected override void Execute(NativeActivityContext context)
    {
        // Book resource
        var booking = BookResource();

        // Store booking for potential compensation
        context.Properties.Add("Booking", booking);
    }

    protected override void Cancel(NativeActivityContext context)
    {
        // Release resource on cancellation
        var booking = context.Properties.Find("Booking") as Booking;
        ReleaseResource(booking);
    }
}

Timeout and Retry Handling

Wrap external calls with explicit timeout and retry logic:

public sealed class ResilientServiceCall : NativeActivity
{
    public InArgument<TimeSpan> Timeout { get; set; }
    public InArgument<int> MaxRetries { get; set; }

    protected override void Execute(NativeActivityContext context)
    {
        var timeout = Timeout.Get(context);
        var maxRetries = MaxRetries.Get(context);

        // Implement retry with exponential backoff
        // Respect timeout boundaries
        // Log each attempt for debugging
    }
}

Designer Artifact Patterns

Minimal Designer Changes

When modifying designer-backed workflows:

1. Make the smallest possible change 2. Test the exact scenario being fixed 3. Verify no unintended side effects on other paths 4. Document the change with before/after screenshots if visual

Version Isolation

Keep workflow versions isolated:

workflows/
├── OrderProcessing_v1.xaml  # Legacy, read-only
├── OrderProcessing_v2.xaml  # Current production
└── OrderProcessing_v3.xaml  # Development

Route new instances to the current version; let old instances complete on their original version.

Designer to Code Migration

When designer complexity becomes unmanageable:

1. Extract the core logic into testable code activities 2. Simplify the designer workflow to orchestration only 3. Document the mapping between designer elements and code

Testing Patterns

Workflow Unit Testing

Test activities in isolation:

[Test]
public void Activity_WithValidInput_ProducesExpectedOutput()
{
    var activity = new MyActivity();
    var inputs = new Dictionary<string, object>
    {
        { "Input", testValue }
    };

    var outputs = WorkflowInvoker.Invoke(activity, inputs);

    Assert.That(outputs["Result"], Is.EqualTo(expectedValue));
}

Scenario Capture

Capture production scenarios for regression testing:

1. Log workflow inputs and decision points 2. Record external service responses 3. Replay scenarios in test environment 4. Compare outcomes to production baseline

Long-Running Workflow Testing

Test persistence and recovery:

[Test]
public async Task Workflow_AfterHostRestart_ResumesCorrectly()
{
    // Start workflow
    var instanceId = await StartWorkflowAsync();

    // Wait for persistence point
    await WaitForPersistenceAsync(instanceId);

    // Simulate host restart
    await RestartHostAsync();

    // Resume and verify completion
    await ResumeAndVerifyAsync(instanceId);
}

Monitoring Patterns

Instance Health Dashboard

Track key metrics:

• Active instance count by workflow type
• Instance age distribution
• Persistence queue depth
• Bookmark wait times
• Failure and cancellation rates

Stuck Instance Detection

Identify workflows that are not progressing:

public IEnumerable<StuckInstance> FindStuckInstances(TimeSpan threshold)
{
    // Query persistence store for instances
    // where last activity timestamp exceeds threshold
    // and instance is not in a known waiting state
}

Audit Trail Continuity

Ensure tracking records support compliance:

• Capture all state transitions
• Record decision inputs and outputs
• Preserve timestamps with consistent timezone handling
• Support query by instance, time range, or outcome

Operational Patterns

Graceful Shutdown

Drain workflows before host shutdown:

1. Stop accepting new workflow starts 2. Wait for in-flight activities to complete 3. Persist current state for all active instances 4. Verify persistence success before shutdown

Instance Recovery Procedures

Document recovery steps for common failures:

• Persistence store unavailable
• External service timeout
• Activity exception
• Host crash during execution

Capacity Planning

Monitor and plan for:

• Persistence store growth rate
• Peak concurrent instance count
• Activity execution latency trends
• Tracking record volume