Merge pull request #1182 from marcduiker/workflow-tutorials

Workflow tutorials C#

Author: alicejgibbons

.github/workflows/validate_tutorials.yaml

@@ -184,6 +184,64 @@ jobs:
       #     pushd tutorials/observability
       #     make validate
       #     popd
-      - name: Linkcheck README.md
-        run: |
-          make validate
+      # Validation for workflows is intentionally commented out.
+      # Mechanical markdown is not able to invoke the workflow services.
+      # Once this feature has been added to Mechanical Markdown the 
+      # workflow validations can be enabled.
+      #- name: Validate workflow/csharp/child-workflows
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/child-workflows
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/combined-patterns
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/combined-patterns
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/external-system-interaction
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/external-system-interaction
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/fan-out-fan-in
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/fan-out-fan-in
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/fundamentals
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/fundamentals
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/monitor-pattern
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/monitor-pattern
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/resiliency-and-compensation
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/resiliency-and-compensation
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/task-chaining
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/task-chaining
+      #    make validate
+      #    popd
+      #- name: Validate workflow/csharp/workflow-management
+      #  if: matrix.os == 'ubuntu-latest'
+      #  run: |
+      #    pushd tutorials/workflow/csharp/workflow-management
+      #    make validate
+      #    popd
+      #- name: Linkcheck README.md
+      #  run: |
+      #    make validate

tutorials/workflow/csharp/README.md

@@ -0,0 +1,25 @@
+# Using the Dapr Workflow API with C#
+
+This folder contains tutorials of using the Dapr Workflow API with C#. All examples can be run locally on your machine.
+
+Before you start, it's recommended to read though the Dapr docs to get familiar with the many [Workflow features, concepts, and patterns](https://docs.dapr.io/developing-applications/building-blocks/workflow/).
+
+## Prerequisites
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) & [Initialization](https://docs.dapr.io/getting-started/install-dapr-selfhost/)
+- [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0)
+- Optional: An IDE such as [VSCode](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client).
+
+## Tutorials
+
+- [Workflow Basics](./fundamentals/README.md)
+- [Task Chaining](./task-chaining/README.md)
+- [Fan-out/Fan-in](./fan-out-fan-in/README.md)
+- [Monitor](./monitor-pattern/README.md)
+- [External Events](./external-system-interaction/README.md)
+- [Child Workflows](./child-workflows/README.md)
+- [Resiliency & Compensation](./resiliency-and-compensation/README.md)
+- [Combined Patterns](./combined-patterns/README.md)
+- [WorkflowManagement](./workflow-management/README.md)
+- [Challenges & Tips](./challenges-tips/README.md)

tutorials/workflow/csharp/challenges-tips/DeterministicWorkflow.cs

@@ -0,0 +1,47 @@
+using System;
+using Dapr.Workflow;
+
+namespace WorkflowApp;
+
+internal sealed class NonDeterministicWorkflow : Workflow<string, string>
+{
+    public override async Task<string> RunAsync(WorkflowContext context, string orderItem)
+    {
+        // Do not use non-deterministic operations in a workflow!
+        // These operations will create a new value every time the
+        // workflow is replayed.
+        var orderId = Guid.NewGuid().ToString();
+        var orderDate = DateTime.UtcNow;
+
+        var idResult = await context.CallActivityAsync<string>(
+            "SubmitId",
+            orderId);
+
+        await context.CallActivityAsync<string>(
+            "SubmitDate",
+            orderDate);
+
+        return idResult;
+    }
+}
+
+internal sealed class DeterministicWorkflow : Workflow<string, string>
+{
+    public override async Task<string> RunAsync(WorkflowContext context, string orderItem)
+    {
+        // Do use these deterministic methods and properties on the WorkflowContext instead.
+        // These operations create the same value when the workflow is replayed.
+        var orderId = context.NewGuid().ToString();
+        var orderDate = context.CurrentUtcDateTime;
+
+        var idResult = await context.CallActivityAsync<string>(
+            "SubmitId",
+            orderId);
+
+        await context.CallActivityAsync<string>(
+            "SubmitDate",
+            orderDate);
+
+        return idResult;
+    }
+}

tutorials/workflow/csharp/challenges-tips/IdempotentActivity.cs

@@ -0,0 +1,19 @@
+using Dapr.Client;
+using Dapr.Workflow;
+
+namespace WorkflowApp;
+
+internal sealed class IdempotentActivity : WorkflowActivity<string, string>
+{
+    public override async Task<InventoryResult> RunAsync(WorkflowActivityContext context, OrderItem orderItem)
+    {
+        // Beware of non-idempotent operations in an activity.
+        // Dapr Workflow guarantees at-least-once execution of activities, so activities might be executed more than once
+        // in case an activity is not ran to completion successfully.
+        // For instance, can you insert a record to a database twice without side effects?
+        //      var insertSql = $"INSERT INTO Orders (Id, Description, UnitPrice, Quantity) VALUES ('{orderItem.Id}', '{orderItem.Description}', {orderItem.UnitPrice}, {orderItem.Quantity})";
+        // It's best to perform a check if an record already exists before inserting it.
+    }
+}
+
+internal sealed record OrderItem(string Id, string Description, double UnitPrice, int Quantity);

tutorials/workflow/csharp/challenges-tips/PayloadSizeWorkflow.cs

@@ -0,0 +1,43 @@
+using Dapr.Workflow;
+
+namespace WorkflowApp;
+
+internal sealed class LargePayloadSizeWorkflow : Workflow<string, LargeDocument>
+{
+    public override async Task<LargeDocument> RunAsync(WorkflowContext context, string id)
+    {
+        // Do not pass large payloads between activities.
+        // They are stored in the Dapr state store twice, one as output argument 
+        // for GetDocument, and once as input argument for UpdateDocument.
+        var document = await context.CallActivityAsync<LargeDocument>(
+            "GetDocument",
+            id);
+
+        var updatedDocument = await context.CallActivityAsync<LargeDocument>(
+            "UpdateDocument",
+            document);
+
+        // More activities to process the updated document...
+
+        return updatedDocument;
+    }
+}
+
+
+public class SmallPayloadSizeWorkflow : Workflow<string, string>
+{
+    public override async Task<string> RunAsync(WorkflowContext context, string id)
+    {
+        // Do pass small payloads between activities, preferably IDs only, or objects that are quick to (de)serialize in large volumes.
+        // Combine multiple actions, such as document retrieval and update, into a single activity.
+        var documentId = await context.CallActivityAsync<string>(
+            "GetAndUpdateDocument",
+            id);
+
+        // More activities to process the updated document...
+
+        return documentId;
+    }
+}
+
+internal sealed record LargeDocument(string Id, object Data);

tutorials/workflow/csharp/challenges-tips/README.md

@@ -0,0 +1,10 @@
+# Workflow Challenges & Tips
+
+Workflow systems are very powerful tools but also have their challenges & limitations as described in the [Dapr docs](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-features-concepts/#limitations).
+
+This section provides some tips with code snippets to understand the limitations and get the most out of the Dapr Workflow API. Read through the following examples to learn best practices to develop Dapr workflows.
+
+- [Deterministic workflows](DeterministicWorkflow.cs)
+- [Idempotent activities](IdempotentActivity.cs)
+- [Versioning workflows](VersioningWorkflow.cs)
+- [Workflow & activity payload size](PayloadSizeWorkflow.cs)

tutorials/workflow/csharp/challenges-tips/VersioningWorkflow.cs

@@ -0,0 +1,50 @@
+using Dapr.Workflow;
+
+namespace WorkflowApp;
+
+/// <summary>
+/// This is the initial version of the workflow.
+/// Note that the input argument for both activities is the orderItem (string).
+/// </summary>
+internal sealed class VersioningWorkflow1 : Workflow<string, int>
+{
+    public override async Task<int> RunAsync(WorkflowContext context, string orderItem)
+    {
+        var resultA = await context.CallActivityAsync<int>(
+            "ActivityA",
+            orderItem);
+
+        var resultB = await context.CallActivityAsync<int>(
+            "ActivityB",
+            orderItem);
+
+        return resultA + resultB;
+    }
+}
+
+/// <summary>
+/// This is the updated version of the workflow.
+/// The input for ActivityB has changed from orderItem (string) to resultA (int).
+/// If there are in-flight workflow instances that were started with the previous version
+/// of this workflow, these will fail when the new version of the workflow is deployed 
+/// and the workflow name remains the same, since the runtime parameters do not match with the persisted state.
+/// It is recommended to version workflows by creating a new workflow class with a new name:
+/// {workflowname}1 -> {workflowname}2
+/// Try to avoid making breaking changes in perpetual workflows (that use the `ContinueAsNew` method) 
+/// since these are difficult to replace with a new version.
+/// </summary>
+internal sealed class VersioningWorkflow2 : Workflow<string, int>
+{
+    public override async Task<int> RunAsync(WorkflowContext context, string orderItem)
+    {
+        var resultA = await context.CallActivityAsync<int>(
+            "ActivityA",
+            orderItem);
+
+        var resultB = await context.CallActivityAsync<int>(
+            "ActivityB",
+            resultA);
+
+        return resultA + resultB;
+    }
+}

tutorials/workflow/csharp/child-workflows/ChildWorkflows/Activities/Activity1.cs

@@ -0,0 +1,12 @@
+using Dapr.Workflow;
+
+namespace ChildWorkflows.Activities;
+
+internal sealed class Activity1 : WorkflowActivity<string, string>
+{
+    public override Task<string> RunAsync(WorkflowActivityContext context, string input)
+    {
+        Console.WriteLine($"{nameof(Activity1)}: Received input: {input}.");
+        return Task.FromResult($"{input} is processed" );
+    }
+}

tutorials/workflow/csharp/child-workflows/ChildWorkflows/Activities/Activity2.cs

@@ -0,0 +1,12 @@
+using Dapr.Workflow;
+
+namespace ChildWorkflows.Activities;
+
+internal sealed class Activity2 : WorkflowActivity<string, string>
+{
+    public override Task<string> RunAsync(WorkflowActivityContext context, string input)
+    {
+        Console.WriteLine($"{nameof(Activity2)}: Received input: {input}.");
+        return Task.FromResult($"{input} as a child workflow." );
+    }
+}

tutorials/workflow/csharp/child-workflows/ChildWorkflows/ChildWorkflow.cs

@@ -0,0 +1,22 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using ChildWorkflows.Activities;
+using Dapr.Workflow;
+
+namespace ChildWorkflows;
+internal sealed class ChildWorkflow : Workflow<string, string>
+{
+    public override async Task<string> RunAsync(WorkflowContext context, string input)
+    {
+        var result1 = await context.CallActivityAsync<string>(
+            nameof(Activity1),
+            input);
+        var childWorkflowResult = await context.CallActivityAsync<string>(
+            nameof(Activity2),
+            result1);
+
+        return childWorkflowResult;
+    }
+}