Quick Start: Building Workflows with WF Azure Activity Pack

Troubleshooting WF Azure Activity Pack: Common Issues and Fixes

This guide covers common problems when using the WF (Windows Workflow Foundation) Azure Activity Pack and provides clear, actionable fixes and troubleshooting steps.

1. Deployment fails with missing assemblies or types

Symptoms:

• Workflow host throws TypeLoadException or FileNotFoundException.
• Errors reference activities from the Azure Activity Pack (e.g., Microsoft.Activities.*).

Fix:

1. Verify package references — Ensure your project references the correct NuGet packages for WF and the Azure Activity Pack. Use matching versions for all WF-related packages.
2. Include assemblies in deployment — Set Copy Local = true for required assemblies, or include them in the deployment package (bin folder or service package).
3. Check binding redirects — If running under .NET Framework, add/update binding redirects in web.config/app.config for conflicting assembly versions.
4. Rebuild and redeploy — Clean solution, restore NuGet packages, rebuild, then redeploy.

2. Activities fail to execute in Azure environment (works locally)

Symptoms:

• Activities run locally but throw exceptions or hang when deployed to Azure App Service / Cloud Service.
• Timeouts, network errors, or authentication failures appear only in cloud.

Fix:

1. Confirm platform and runtime parity — Ensure Azure environment uses the same .NET runtime and platform (x86/x64) as local dev.
2. Check outbound network rules — Some activities require outbound connectivity (e.g., to storage, Service Bus). Ensure NSGs, firewall settings, or App Service restrictions allow required endpoints.
3. Validate connection strings and credentials — Use Azure Key Vault or App Settings to store connection strings; confirm they are present in the deployed environment.
4. Adjust timeouts and retry policies — Increase operation timeouts and implement transient-fault handling (exponential backoff) for cloud variability.
5. Enable remote diagnostics/logging — Turn on Application Insights or Azure Diagnostics to capture exceptions and traces.

3. Serialization errors when persisting workflow state

Symptoms:

• SerializationException referencing types not marked serializable, or DataContractSerializer errors.
• Workflow persistence fails when using SQL persistence or Durable services.

Fix:

1. Use serializable data types — Ensure custom arguments and variables used in persisted workflows are serializable (DataContract/DataMember or [Serializable]).
2. Avoid non-serializable closures — Do not capture non-serializable objects (like open DB connections) in activity state.
3. Versioning of types — If workflow types changed after persistence data existed, provide version-tolerant serialization (optional DataMember, KnownType attributes) or migrate persisted data.
4. Test persistence locally — Run persistence scenarios against a local SQL instance to reproduce and fix issues before deploying.

4. Activities time out or hang under load

Symptoms:

• Long-running activities exceed expected duration or block other workflows.
• Thread starvation or high CPU/IO on host.

Fix:

1. Profile and identify bottlenecks — Use performance counters, Application Insights, or a profiler to find slow operations.
2. Offload blocking calls — Convert blocking I/O to asynchronous patterns or schedule long-running tasks outside the workflow using durable patterns or queues.
3. Tune workflow host settings — Increase concurrency limits, thread pool settings, and workflow persistence behavior to handle expected load.
4. Implement throttling and retries — Throttle incoming requests and add retry policies for transient failures.
5. Scale out — Add more worker instances or scale App Service Plan to distribute load.

5. Authentication and authorization failures with Azure services

Symptoms:

• Access denied or authentication errors when activities access Blob Storage, Service Bus, Key Vault, etc.

Fix:

1. Use managed identities where possible — Prefer system-assigned or user-assigned managed identity for service-to-service auth; grant least-privilege RBAC roles.
2. Check credentials in config — Verify connection strings, SAS tokens, and keys are correct and not expired.
3. Clock skew — Ensure host clock is accurate; large clock drift can cause token validation failures.
4. Test permissions separately — Use Azure CLI or Storage Explorer to verify the account or identity can access the resource.

6. Activity Pack version incompatibilities

Symptoms:

• Runtime exceptions or missing members after upgrading Activity Pack or WF packages.

Fix:

1. Pin package versions — Use consistent versioning across environments; avoid mixing preview and stable releases.
2. Read release notes and breaking changes — Check package changelogs for migration steps.
3. Test upgrades in staging — Validate upgrades in a staging slot before production rollout.
4. Update dependent code — Refactor code to match updated API signatures.

7. Logging and insufficient diagnostic information

Symptoms:

• Errors occur but logs lack context; hard to reproduce root cause.

Fix:

1. Enable verbose workflow tracing — Configure workflow tracing to include activity execution paths and arguments (obfuscate sensitive data).
2. Centralize logs — Use Application Insights, Log Analytics, or another centralized logging solution.
3. Add structured logs in activities — Instrument custom activities to log start/end, input/output, and exceptions.
4. Capture activity payloads safely — Record minimal, non-sensitive context needed to reproduce issues.

Troubleshooting checklist (quick)

Example diagnostic workflow (3 steps)

1. Reproduce the issue in a staging environment with diagnostics enabled (App Insights + detailed workflow tracing).
2. Capture exception stack trace, input arguments, and environment details (runtime, package versions).
3. Apply targeted fix (binding redirect, serialization attribute, config change), redeploy to staging, then to production.

If you want, I can produce a troubleshooting script or ARM/ARM Template snippets to automate common fixes (binding redirects, app settings, or diagnostic configuration).