Merge pull request #290390 from cgillum/durable-http-updates

Update Durable HTTP features documentation

Author: v-regandowner

articles/azure-functions/durable/durable-functions-http-features.md

@@ -3,7 +3,7 @@ title: HTTP features in Durable Functions - Azure Functions
 description: Learn about the integrated HTTP features in the Durable Functions extension for Azure Functions.
 author: cgillum
 ms.topic: conceptual
-ms.date: 05/10/2022
+ms.date: 11/11/2024
 ms.author: azfuncdf
 ms.devlang: csharp
 # ms.devlang: csharp, java, javascript, powershell, python
@@ -38,10 +38,39 @@ See the [HTTP APIs article](durable-functions-http-api.md) for a full descriptio
 
 The [orchestration client binding](durable-functions-bindings.md#orchestration-client) exposes APIs that can generate convenient HTTP response payloads. For example, it can create a response containing links to management APIs for a specific orchestration instance. The following examples show an HTTP-trigger function that demonstrates how to use this API for a new orchestration instance:
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 [!code-csharp[Main](~/samples-durable-functions/samples/precompiled/HttpStart.cs)]
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+/// <summary>
+/// HTTP-triggered function that starts the <see cref="HelloCitiesUntyped"/> orchestration.
+/// </summary>
+/// <param name="req">The HTTP request that was used to trigger this function.</param>
+/// <param name="client">The DurableTask client that is used to start and manage orchestration instances.</param>
+/// <param name="executionContext">The Azure Functions execution context, which is available to all function types.</param>
+/// <returns>Returns an HTTP response with more information about the started orchestration instance.</returns>
+[Function(nameof(StartHelloCitiesUntyped))]
+public static async Task<HttpResponseData> StartHelloCitiesUntyped(
+    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
+    [DurableClient] DurableTaskClient client,
+    FunctionContext executionContext)
+{
+    ILogger logger = executionContext.GetLogger(nameof(StartHelloCitiesUntyped));
+
+    string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(nameof(HelloCitiesUntyped));
+    logger.LogInformation("Created new orchestration with instance ID = {instanceId}", instanceId);
+
+    // Returns an HTTP response with a payload that includes links to built-in HTTP management payloads
+    return client.CreateCheckStatusResponse(req, instanceId);
+}
+```
+
+> [!NOTE]
+> The `CreateCheckStatusResponse` and related APIs currently only support `HttpRequestData` and `HttpResponseData` types when working with HTTP-triggered functions. ASP.NET-defined types are not currently supported.
+
 # [JavaScript](#tab/javascript)
 
 **index.js**
@@ -222,10 +251,10 @@ Starting with Durable Functions 2.0, orchestrations can natively consume HTTP AP
 
 The following example code shows an orchestrator function making an outbound HTTP request:
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
-[FunctionName("CheckSiteAvailable")]
+[FunctionName(nameof(CheckSiteAvailable))]
 public static async Task CheckSiteAvailable(
     [OrchestrationTrigger] IDurableOrchestrationContext context)
 {
@@ -242,6 +271,36 @@ public static async Task CheckSiteAvailable(
 }
 ```
 
+> [!NOTE]
+> You might wonder why this feature uses the **DurableHttpRequest** and **DurableHttpResponse** types instead of the built-in .NET **HttpRequestMessage** and **HttpResponseMessage** types.
+>
+> This design choice is intentional. The primary reason is that custom types help ensure users don't make incorrect assumptions about the supported behaviors of the internal HTTP client. Types specific to Durable Functions also make it possible to simplify API design. They also can more easily make available special features like [managed identity integration](#managed-identities) and the [polling consumer pattern](#http-202-handling).
+
+# [C# (Isolated)](#tab/csharp-isolated)
+
+```csharp
+[Function(nameof(CheckSiteAvailable))]
+public static async Task CheckSiteAvailable(
+    [OrchestrationTrigger] TaskOrchestrationContext context)
+{
+    Uri url = context.GetInput<Uri>();
+
+    // Makes an HTTP GET request to the specified endpoint
+    DurableHttpResponse response =
+        await context.CallHttpAsync(HttpMethod.Get, url);
+
+    if (response.StatusCode >= HttpStatusCode.BadRequest)
+    {
+        // handling of error codes goes here
+    }
+}
+```
+
+> [!NOTE]
+> You might wonder why this feature uses the **DurableHttpRequest** and **DurableHttpResponse** types instead of the built-in .NET **HttpRequestMessage** and **HttpResponseMessage** types.
+>
+> This design choice is intentional. The primary reason is that custom types help ensure users don't make incorrect assumptions about the supported behaviors of the internal HTTP client. Types specific to Durable Functions also make it possible to simplify API design. They also can more easily make available special features that aren't part of the built-in framework types.
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -291,21 +350,21 @@ By using the "call HTTP" action, you can do the following actions in your orches
 
 The ability to consume HTTP APIs directly from orchestrator functions is intended as a convenience for a certain set of common scenarios. You can implement all of these features yourself using activity functions. In many cases, activity functions might give you more flexibility.
 
-### HTTP 202 handling
+### <a name="http-202-handling"></a>HTTP 202 handling (.NET in-process only)
 
 The "call HTTP" API can automatically implement the client side of the polling consumer pattern. If a called API returns an HTTP 202 response with a Location header, the orchestrator function automatically polls the Location resource until receiving a response other than 202. This response will be the response returned to the orchestrator function code.
 
 > [!NOTE]
 > 1. Orchestrator functions also natively support the server-side polling consumer pattern, as described in [Async operation tracking](#async-operation-tracking). This support means that orchestrations in one function app can easily coordinate the orchestrator functions in other function apps. This is similar to the [sub-orchestration](durable-functions-sub-orchestrations.md) concept, but with support for cross-app communication. This support is particularly useful for microservice-style app development.
-> 2. Due to a temporary limitation, the built-in HTTP polling pattern is not currently available in JavaScript/TypeScript and Python.
+> 2. The built-in HTTP polling pattern is currently available only in the .NET in-process host.
 
 ### Managed identities
 
 Durable Functions natively supports calls to APIs that accept Microsoft Entra tokens for authorization. This support uses [Azure managed identities](../../active-directory/managed-identities-azure-resources/overview.md) to acquire these tokens.
 
 The following code is an example of an orchestrator function. The function makes authenticated calls to restart a virtual machine by using the Azure Resource Manager [virtual machines REST API](/rest/api/compute/virtualmachines).
 
-# [C#](#tab/csharp)
+# [C# (InProc)](#tab/csharp-inproc)
 
 ```csharp
 [FunctionName("RestartVm")]
@@ -331,6 +390,10 @@ public static async Task RunOrchestrator(
 }
 ```
 
+# [C# (Isolated)](#tab/csharp-isolated)
+
+This feature isn't yet available in the .NET Isolated worker.
+
 # [JavaScript](#tab/javascript)
 
 ```javascript
@@ -414,14 +477,9 @@ HTTP requests sent by orchestrator functions and their responses are [serialized
 
 If any of these limitations might affect your use case, consider instead using activity functions and language-specific HTTP client libraries to make outbound HTTP calls.
 
-> [!NOTE]
-> If you are a .NET developer, you might wonder why this feature uses the **DurableHttpRequest** and **DurableHttpResponse** types instead of the built-in .NET **HttpRequestMessage** and **HttpResponseMessage** types.
->
-> This design choice is intentional. The primary reason is that custom types help ensure users don't make incorrect assumptions about the supported behaviors of the internal HTTP client. Types specific to Durable Functions also make it possible to simplify API design. They also can more easily make available special features like [managed identity integration](#managed-identities) and the [polling consumer pattern](#http-202-handling). 
-
-### Extensibility (.NET only)
+### <a name="extensibility"></a>Extensibility (.NET in-process only)
 
-Customizing the behavior of the orchestration's internal HTTP client is possible using [Azure Functions .NET dependency injection](../functions-dotnet-dependency-injection.md). This ability can be useful for making small behavioral changes. It can also be useful for unit testing the HTTP client by injecting mock objects.
+Customizing the behavior of the orchestration's internal HTTP client is possible using [Azure Functions .NET dependency injection](../functions-dotnet-dependency-injection.md) for the in-process worker. This ability can be useful for making small behavioral changes. It can also be useful for unit testing the HTTP client by injecting mock objects.
 
 The following example demonstrates using dependency injection to disable TLS/SSL certificate validation for orchestrator functions that call external HTTP endpoints.