Merge pull request #224925 from jviau/durable-dotnet-isolated

Update durable docs for dotnet isolated

Author: American-Dipper

articles/azure-functions/durable/TOC.yml

@@ -10,6 +10,8 @@
     href: ../functions-compare-logic-apps-ms-flow-webjobs.md?toc=/azure/azure-functions/durable/toc.json
   - name: Durable Functions versions
     href: durable-functions-versions.md
+  - name: Durable Functions for .NET isolated
+    href: durable-functions-dotnet-isolated-overview.md
 - name: Quickstarts
   expanded: true
   items:

articles/azure-functions/durable/durable-functions-bindings.md

@@ -57,7 +57,7 @@ The orchestration trigger binding supports both inputs and outputs. Here are som
 
 The following example code shows what the simplest "Hello World" orchestrator function might look like. Note that this example orchestrator doesn't actually schedule any tasks.
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("HelloWorld")]
@@ -71,6 +71,19 @@ public static string Run([OrchestrationTrigger] IDurableOrchestrationContext con
 > [!NOTE]
 > The previous code is for Durable Functions 2.x. For Durable Functions 1.x, you must use `DurableOrchestrationContext` instead of `IDurableOrchestrationContext`. For more information about the differences between versions, see the [Durable Functions Versions](durable-functions-versions.md) article.
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+[Function("HelloWorld")]
+public static string Run([OrchestrationTrigger] TaskOrchestrationContext context, string name)
+{
+    return $"Hello {name}!";
+}
+```
+
+> [!NOTE]
+> In both Durable functions in-proc and in .NET-isolated, the orchestration input can be extracted via `context.GetInput<T>()`. However, .NET-isolated also supports the input being supplied as a parameter, as shown above. The input binding will bind to the first parameter which has no binding attribute on it and is not a well-known type already covered by other input bindings (ie: `FunctionContext`).
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -119,7 +132,7 @@ public String helloWorldOrchestration(
 
 Most orchestrator functions call activity functions, so here is a "Hello World" example that demonstrates how to call an activity function:
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("HelloWorld")]
@@ -135,6 +148,18 @@ public static async Task<string> Run(
 > [!NOTE]
 > The previous code is for Durable Functions 2.x. For Durable Functions 1.x, you must use `DurableOrchestrationContext` instead of `IDurableOrchestrationContext`. For more information about the differences between versions, see the [Durable Functions versions](durable-functions-versions.md) article.
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+[Function("HelloWorld")]
+public static async Task<string> Run(
+    [OrchestrationTrigger] TaskOrchestrationContext context, string name)
+{
+    string result = await context.CallActivityAsync<string>("SayHello", name);
+    return result;
+}
+```
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -228,7 +253,7 @@ The activity trigger binding supports both inputs and outputs, just like the orc
 
 The following example code shows what a simple `SayHello` activity function might look like:
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("SayHello")]
@@ -249,6 +274,18 @@ public static string SayHello([ActivityTrigger] string name)
 }
 ```
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+In the .NET-isolated worker, only serializable types representing your input are supported for the `[ActivityTrigger]`.
+
+```csharp
+[FunctionName("SayHello")]
+public static string SayHello([ActivityTrigger] string name)
+{
+    return $"Hello {name}!";
+}
+```
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -355,7 +392,7 @@ In .NET functions, you typically bind to [IDurableClient](/dotnet/api/microsoft.
 
 Here's an example queue-triggered function that starts a "HelloWorld" orchestration.
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("QueueStart")]
@@ -371,6 +408,19 @@ public static Task Run(
 > [!NOTE]
 > The previous C# code is for Durable Functions 2.x. For Durable Functions 1.x, you must use `OrchestrationClient` attribute instead of the `DurableClient` attribute, and you must use the `DurableOrchestrationClient` parameter type instead of `IDurableOrchestrationClient`. For more information about the differences between versions, see the [Durable Functions Versions](durable-functions-versions.md) article.
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+[Function("QueueStart")]
+public static Task Run(
+    [QueueTrigger("durable-function-trigger")] string input,
+    [DurableClient] DurableTaskClient client)
+{
+    // Orchestration input comes from the queue message content.
+    return client.ScheduleNewOrchestrationInstanceAsync("HelloWorld", input);
+}
+```
+
 # [JavaScript](#tab/javascript)
 
 **function.json**
@@ -502,7 +552,7 @@ If you're using JavaScript, Python, or PowerShell, the entity trigger is defined
 ```
 
 > [!NOTE]
-> Entity triggers are not yet supported in Java.
+> Entity triggers are not yet supported in Java or in the .NET-isolated worker.
 
 By default, the name of an entity is the name of the function.
 

articles/azure-functions/durable/durable-functions-diagnostics.md

@@ -178,7 +178,7 @@ For more information about what log events are available, see the [Durable Task
 
 It's important to keep the orchestrator replay behavior in mind when writing logs directly from an orchestrator function. For example, consider the following orchestrator function:
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("FunctionChain")]
@@ -196,6 +196,25 @@ public static async Task Run(
 }
 ```
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+[Function("FunctionChain")]
+public static async Task Run(
+    [OrchestrationTrigger] TaskOrchestrationContext context,
+    FunctionContext executionContext)
+{
+    ILogger log = executionContext.GetLogger("FunctionChain");
+    log.LogInformation("Calling F1.");
+    await context.CallActivityAsync("F1");
+    log.LogInformation("Calling F2.");
+    await context.CallActivityAsync("F2");
+    log.LogInformation("Calling F3");
+    await context.CallActivityAsync("F3");
+    log.LogInformation("Done!");
+}
+```
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -271,7 +290,7 @@ Done!
 
 If you want to only write logs on non-replay executions, you can write a conditional expression to log only if the "is replaying" flag is `false`. Consider the example above, but this time with replay checks.
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("FunctionChain")]
@@ -311,6 +330,28 @@ public static async Task Run(
 > [!NOTE]
 > The previous C# examples are for Durable Functions 2.x. For Durable Functions 1.x, you must use `DurableOrchestrationContext` instead of `IDurableOrchestrationContext`. For more information about the differences between versions, see the [Durable Functions versions](durable-functions-versions.md) article.
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+In Durable Functions for .NET-isolated, you can create an `ILogger` that automatically filters out log statements during replay. The main difference with Durable Functions in-proc is that you do not provide an existing `ILogger`. This logger is created via the `TaskOrchestrationContext.CreateReplaySafeLogger` overloads.
+
+```csharp
+[Function("FunctionChain")]
+public static async Task Run([OrchestrationTrigger] TaskOrchestrationContext context)
+{
+    ILogger log = context.CreateReplaySafeLogger("FunctionChain");
+    log.LogInformation("Calling F1.");
+    await context.CallActivityAsync("F1");
+    log.LogInformation("Calling F2.");
+    await context.CallActivityAsync("F2");
+    log.LogInformation("Calling F3");
+    await context.CallActivityAsync("F3");
+    log.LogInformation("Done!");
+}
+```
+
+> [!NOTE]
+> The ability to wrap an existing `ILogger` into a replay-safe logger has been removed in Durable Functions for .NET isolated worker.
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -383,7 +424,7 @@ Done!
 
 Custom orchestration status lets you set a custom status value for your orchestrator function. This custom status is then visible to external clients via the [HTTP status query API](durable-functions-http-api.md#get-instance-status) or via language-specific API calls. The custom orchestration status enables richer monitoring for orchestrator functions. For example, the orchestrator function code can invoke the "set custom status" API to update the progress for a long-running operation. A client, such as a web page or other external system, could then periodically query the HTTP status query APIs for richer progress information. Sample code for setting a custom status value in an orchestrator function is provided below:
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("SetStatusTest")]
@@ -402,6 +443,22 @@ public static async Task SetStatusTest([OrchestrationTrigger] IDurableOrchestrat
 > [!NOTE]
 > The previous C# example is for Durable Functions 2.x. For Durable Functions 1.x, you must use `DurableOrchestrationContext` instead of `IDurableOrchestrationContext`. For more information about the differences between versions, see the [Durable Functions versions](durable-functions-versions.md) article.
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+[Function("SetStatusTest")]
+public static async Task SetStatusTest([OrchestrationTrigger] TaskOrchestrationContext context)
+{
+    // ...do work...
+
+    // update the status of the orchestration with some arbitrary data
+    var customStatus = new { completionPercentage = 90.0, status = "Updating database records" };
+    context.SetCustomStatus(customStatus);
+
+    // ...do more work...
+}
+```
+
 # [JavaScript](#tab/javascript)
 
 ```javascript

articles/azure-functions/durable/durable-functions-dotnet-entities.md

@@ -24,7 +24,10 @@ We currently offer two APIs for defining entities:
 This article focuses primarily on the class-based syntax, as we expect it to be better suited for most applications. However, the [function-based syntax](#function-based-syntax) may be appropriate for applications that wish to define or manage their own abstractions for entity state and operations. Also, it may be appropriate for implementing libraries that require genericity not currently supported by the class-based syntax. 
 
 > [!NOTE]
-> The class-based syntax is just a layer on top of the function-based syntax, so both variants can be used interchangeably in the same application. 
+> The class-based syntax is just a layer on top of the function-based syntax, so both variants can be used interchangeably in the same application.
+
+> [!NOTE]
+> Entities are not currently supported in Durable Functions for the dotnet-isolated worker.
  
 ## Defining entity classes
 

articles/azure-functions/durable/durable-functions-dotnet-isolated-overview.md

@@ -0,0 +1,145 @@
+---
+title: Overview of Durable Functions in the .NET isolated worker - Azure
+description: Learn about Durable Functions in the Azure Functions .NET isolated worker process, which supports non-LTS versions of .NET and .NET Framework apps.
+author: jviau
+ms.topic: overview
+ms.date: 01/24/2023
+ms.author: azfuncdf
+ms.devlang: csharp
+#Customer intent: As a developer, I want to learn about Durable Functions for the Azure Functions .NET isolated worker process.
+---
+
+# Overview of Durable Functions in the .NET isolated worker
+
+This article is an overview of Durable Functions in the [.NET isolated worker](../dotnet-isolated-process-guide.md). The isolated worker allows your Durable Functions app to run on a .NET version different than that of the Azure Functions host.
+
+## Why use Durable Functions in the .NET isolated worker?
+
+Using this model lets you get all the great benefits that come with the Azure Functions .NET isolated worker process. For more information, see [here](../dotnet-isolated-process-guide.md#why-net-functions-isolated-worker-process). Additionally, this new SDK includes some new [features](#feature-improvements-over-in-process-durable-functions).
+
+### Feature improvements over in-process Durable Functions
+
+- Orchestration input can be injected directly: `MyOrchestration([OrchestrationTrigger] TaskOrchestrationContext context, T input)`
+- Support for strongly typed calls and class-based activities and orchestrations (NOTE: in preview. For more information, see [here](#source-generator-and-class-based-activities-and-orchestrations).)
+- Plus all the benefits of the Azure Functions .NET isolated worker.
+
+### Feature parity with in-process Durable Functions
+
+Not all features from in-process Durable Functions have been migrated to the isolated worker yet. Some known missing features that will be addressed at a later date are:
+
+- Durable Entities
+- `CallHttpAsync`
+
+### Source generator and class-based activities and orchestrations
+
+**Requirement**: add `<PackageReference Include="Microsoft.DurableTask.Generators" Version="1.0.0-preview.1" />` to your project.
+
+By adding the source generator package, you get access to two new features:
+
+- **Class-based activities and orchestrations**, an alternative way to write Durable Functions. Instead of "function-based", you write strongly-typed classes, which inherit types from the Durable SDK.
+- **Strongly typed extension methods** for invoking sub orchestrations and activities. These extension methods can also be used from "function-based" activities and orchestrations.
+
+#### Function-based example
+
+```csharp
+public static class MyFunctions
+{
+    [Function(nameof(MyActivity))] 
+    public static async Task<string> MyActivity([ActivityTrigger] string input)
+    {
+        // implementation
+    }
+
+    [Function(nameof(MyOrchestration))] 
+    public static async Task<string> MyOrchestration([OrchestrationTrigger] TaskOrchestrationContext context, string input)
+    {
+        // implementation
+        return await context.CallActivityAsync(nameof(MyActivity), input);
+    }
+}
+```
+
+#### Class-based example
+
+```csharp
+[DurableTask(nameof(MyActivity))]
+public class MyActivity : TaskActivity<string, string>
+{
+    private readonly ILogger logger;
+
+    public MyActivity(ILogger<SayHelloTyped> logger) // activites have access to DI.
+    {
+        this.logger = logger;
+    }
+
+    public async override Task<string> RunAsync(TaskActivityContext context, string input)
+    {
+        // implementation
+    }
+}
+
+[DurableTask(nameof(MyOrchestration))]
+public class MyOrchestration : TaskOrchestrator<string, string>
+{
+    public async override Task<string> RunAsync(TaskOrchestrationContext context, string input)
+    {
+        ILogger logger = context.CreateReplaySafeLogger<MyOrchestration>(); // orchestrations do NOT have access to DI.
+
+        // An extension method was generated for directly invoking "MyActivity".
+        return await context.CallMyActivityAsync(input);
+    }
+}
+```
+
+## Migration guide
+
+This guide assumes you're starting with a .NET Durable Functions 2.x project.
+
+### Update your project
+
+The first step is to update your project to [Azure Functions .NET isolated](../migrate-version-3-version-4.md). Then, update your Durable Functions NuGet package references.
+
+Old:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="2.9.0" />
+</ItemGroup>
+```
+
+New:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.0.0" />
+</ItemGroup>
+```
+
+### Update your code
+
+Durable Functions for .NET isolated worker is an entirely new package with different types and namespaces. There are required changes to your code as a result, but many of the APIs line up with no changes needed.
+
+#### Host.json schema
+
+The schema for Durable Functions .NET isolated worker and Durable Functions 2.x has remained the same, no changes should be needed.
+
+#### Public interface changes
+
+This table isn't an exhaustive list of changes.
+
+| 2.x | Isolated |
+| ---- | ---- |
+| `IDurableOrchestrationClient` | `DurableTaskClient` |
+| `IDurableOrchestrationClient.StartNewAsync` | `DurableTaskClient.ScheduleNewOrchestrationInstanceAsync` |
+| `IDurableOrchestrationContext` | `TaskOrchestrationContext` |
+| `IDurableOrchestrationContext.GetInput<T>()` | `TaskOrchestrationContext.GetInput<T>()` or inject input as a parameter: `MyOrchestration([OrchestrationTrigger] TaskOrchestrationContext context, T input)` |
+| `DurableActivityContext` | No equivalent |
+| `DurableActivityContext.GetInput<T>()` | Inject input as a parameter `MyActivity([ActivityTrigger] T input)` |
+| `CallActivityWithRetryAsync` | `CallActivityAsync`, include `TaskOptions` parameter with retry details. |
+| `CallSubOrchestratorWithRetryAsync` | `CallSubOrchestratorAsync`, include `TaskOptions` parameter with retry details. |
+| `CallHttpAsync` | No equivalent. Instead, write an activity that invokes your desired HTTP API. |
+| `CreateReplaySafeLogger(ILogger)` | `CreateReplaySafeLogger<T>()` or `CreateReplaySafeLogger(string)` |
+
+#### Behavioral changes
+
+- Serialization default behavior has changed from `Newtonsoft.Json` to `System.Text.Json`. For more information, see [here](./durable-functions-serialization-and-persistence.md).