Merge pull request #301888 from AnatoliB/anatolib/standalone-durable-powershell-sdk-ga

Document standalone Durable PowerShell SDK as GA

Author: prmerger-automator[bot]

articles/azure-functions/durable/durable-functions-instance-management.md

@@ -776,7 +776,7 @@ Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason
 ```
 
 > [!NOTE]
-> This change applies only to the standalone [Durable Functions PowerShell SDK](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK), which is currently [in preview](durable-functions-powershell-v2-sdk-migration-guide.md).
+> This feature is available in the standalone [Durable Functions PowerShell SDK](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK) only. See the difference between the standalone SDK and the legacy built-in SDK along with [migration guide](durable-functions-powershell-v2-sdk-migration-guide.md).
 
 # [Java](#tab/java)
 

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

@@ -20,7 +20,7 @@ ms.reviewer: azfuncdf
 
 **Storage providers packages**:
 
-By default, Durable Functions uses Azure Storage as it's backing store. However, alternative [storage providers](./durable-functions-storage-providers.md) are available as well. To use them, you need to reference their packages _in addition to_ the WebJobs extension in your `.csproj`. Those packages are:
+By default, Durable Functions uses Azure Storage as its backing store. However, alternative [storage providers](./durable-functions-storage-providers.md) are available as well. To use them, you need to reference their packages _in addition to_ the WebJobs extension in your `.csproj`. Those packages are:
 
 * The Netherite storage provider: [Microsoft.Azure.DurableTask.Netherite.AzureFunctions](https://www.nuget.org/packages/Microsoft.Azure.DurableTask.Netherite.AzureFunctions).
 * The MSSQL storage provider: [Microsoft.DurableTask.SqlServer.AzureFunctions](https://www.nuget.org/packages/Microsoft.DurableTask.SqlServer.AzureFunctions)
@@ -52,10 +52,10 @@ Users of [Extension Bundles](../extension-bundles.md) (the recommended Azure Fun
 * Node (JavaScript / TypeScript): The [durable-functions](https://www.npmjs.com/package/durable-functions) npm package.
 * Python: The [azure-functions-durable](https://pypi.org/project/azure-functions-durable/) PyPI package.
 * Java: The [durabletask-azure-functions](https://mvnrepository.com/artifact/com.microsoft/durabletask-azure-functions) Maven package.
-* PowerShell: The current GA SDK is built in to Azure Functions PowerShell language worker, so no installation is needed. See the following _note_ for details.
+* PowerShell: The [AzureFunctions.PowerShell.Durable.SDK](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK) module.
 
 > [!NOTE]
-> For PowerShell users: we have a [_preview_ SDK standalone package](./durable-functions-powershell-v2-sdk-migration-guide.md) under [AzureFunctions.PowerShell.Durable.SDK](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK) in the PowerShell gallery. The latter will be preferred in the future.
+> For PowerShell users: the standalone [AzureFunctions.PowerShell.Durable.SDK](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK) module is now generally available (GA) and is recommended over the legacy SDK that is built into the Azure Functions PowerShell language worker. Going forward, the legacy SDK may not receive new features or bug fixes, and may eventually be removed from the worker. See [migration guide](./durable-functions-powershell-v2-sdk-migration-guide.md) for details on migrating to the standalone SDK. 
 
 ## GitHub repositories
 

articles/azure-functions/durable/durable-functions-powershell-v2-sdk-migration-guide.md

@@ -9,11 +9,8 @@ ms.reviewer: azfuncdf
 
 # Guide to the standalone Durable Functions PowerShell SDK
 
-The Durable Functions (DF) PowerShell SDK is now available, _in preview_, as a standalone package in the PowerShell Gallery: [`AzureFunctions.PowerShell.Durable.SDK`](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK).
-Once this SDK package is GA, it will be the recommended means of authoring Durable Functions apps with PowerShell. In this article, we explain the benefits of this change, and what changes you can expect when adopting this new package.
-
-> [!NOTE]
-> This package is currently in **preview.**
+The Durable Functions (DF) PowerShell SDK is now available as a standalone module in the PowerShell Gallery: [`AzureFunctions.PowerShell.Durable.SDK`](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK).
+This SDK is now **generally available (GA)** and is the recommended approach for authoring Durable Functions apps with PowerShell. In this article, we explain the benefits of this change, and what changes you can expect when adopting this new package.
 
 ## Motivation behind the standalone SDK
 
@@ -30,7 +27,7 @@ By creating a standalone DF PowerShell SDK package, we're able to overcome these
 
 ## Deprecation plan for the built-in DF PowerShell SDK
 
-The built-in DF SDK in the PowerShell worker will remain available for PowerShell 7.4, 7.2, and prior releases.
+The built-in DF SDK in the PowerShell worker will remain available for PowerShell 7.4 and prior releases.
 
 We plan to eventually release a new **major** version of the PowerShell worker without the built-in SDK. At that point, users would need to install the SDK separately using this standalone package; the installation steps are described below.
 
@@ -44,7 +41,7 @@ The standalone PowerShell SDK requires the following minimum versions:
 
 - [Azure Functions Runtime](../functions-versions.md) v4.16+
 - [Azure Functions Core Tools](../functions-run-local.md) v4.0.5095+ (if running locally)
-- Azure Functions PowerShell app for PowerShell 7.2 or greater
+- Azure Functions PowerShell app for PowerShell 7.4 or greater
 
 
 ### Opt in to the standalone DF SDK
@@ -53,7 +50,7 @@ The following application setting is required to run the standalone PowerShell S
 - Name: `ExternalDurablePowerShellSDK`
 - Value: `"true"`
 
-This application setting will disable the built-in Durable SDK for PowerShell versions 7.2 and above, forcing the worker to use the external SDK. 
+This application setting will disable the built-in Durable SDK for PowerShell versions 7.4 and above, forcing the worker to use the external SDK. 
 
 If you're running locally using [Azure Functions Core Tools](../functions-run-local.md), you should add this setting to your `local.settings.json` file. If you're running in Azure, follow these steps with the tool of your choice:
 
@@ -113,13 +110,13 @@ Then you simply need to specify an entry for the DF SDK in your `requirements.ps
 #
 @{
     # For latest supported version, go to 'https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK/'.
-    'AzureFunctions.PowerShell.Durable.SDK' = '1.*'
+    'AzureFunctions.PowerShell.Durable.SDK' = '2.*'
 }
 ```
 
-#### Installation option 2: Use custom modules
+#### Installation option 2: Include the SDK module in your app content
 
-To install the standalone DF SDK as a custom module, you need to follow the [guidance regarding including modules in app content](./../functions-reference-powershell.md#including-modules-in-app-content). Make sure to review the aforementioned docs for details.
+To include the standalone DF SDK in your app content, you need to follow the [guidance regarding including modules in app content](./../functions-reference-powershell.md#including-modules-in-app-content). Make sure to review the aforementioned docs for details.
 In summary, you'll need to place the SDK package inside a `".\Modules"` directory located at the root of your app.
 
 For example, from within your application's root, and after creating a `".\Modules"` directory, you may download the standalone SDK into the modules directory as such:
@@ -163,23 +160,41 @@ Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop
 
 These are all the steps needed to utilize the next PowerShell SDK. Run your app as normal, via `func host start` in your terminal to start using the SDK.
 
+### SDK reference
+
+See [AzureFunctions.PowerShell.Durable.SDK Module](https://github.com/Azure/azure-functions-durable-powershell/blob/main/src/Help/AzureFunctions.PowerShell.Durable.SDK.md) for the complete reference of the SDK cmdlets and their parameters.
+
+You can also use the `Get-Help` cmdlet to get detailed descriptions of the SDK cmdlets. In order to do this, you need to import the module first, as shown in the previous section. After that, you can run the following command to get the entire list of cmdlets:
+
+```powershell
+Get-Help *-Durable*
+```
+
+In order to get detailed help on a specific cmdlet, including usage examples, run:
+
+```powershell
+Get-Help Invoke-DurableOrchestration -Full
+```
+
 ### Migration guide
 
 In this section, we describe the interface and behavioral changes you can expect when utilizing the new SDK.
 
-#### New CmdLets
+#### New cmdlets
 
-* `Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input>` is a new CmdLet that allows users to utilize suborchestrators in their workflows.
+* `Invoke-DurableSubOrchestrator` is a new cmdlet that allows users to utilize suborchestrators in their workflows.
+* `Suspend-DurableOrchestration` and `Resume-DurableOrchestration` are new cmdlets that allow users to suspend and resume orchestrations, respectively.
 
-#### Modified CmdLets
+#### Modified cmdlets
 
-* The CmdLet `Get-DurableTaskResult -Task <task>` now only accepts a single Task as it's argument, instead of accepting a list of Tasks.
+* The `Get-DurableTaskResult` cmdlet now only accepts a single Task as it's argument, instead of accepting a list of Tasks.
+* The `New-DurableRetryOptions` cmdlet is renamed to `New-DurableRetryPolicy` (an alias for the old name is provided for backward compatibility).
 
 #### Behavioral changes
 
-* Exceptions thrown by activities scheduled with `Wait-DurableTask` (as in the Fan-Out/Fan-In pattern) are no longer silently ignored. Instead, on an exception, the CmdLet propagates that exception to the orchestrator so that it may be handled by user-code.
+* Exceptions thrown by activities scheduled with `Wait-DurableTask` (as in the Fan-Out/Fan-In pattern) are no longer silently ignored. Instead, on an exception, the cmdlet propagates that exception to the orchestrator so that it may be handled by user-code.
 * Null values are no longer dropped from the result list of a `Wait-DurableTask` (i.e., WhenAll) invocation. This means that a successful invocation of `Wait-DurableTask` without the `-Any` flag should return an array of the same size as the number of tasks it scheduled.
 
-#### Where to get support, provide feedback, and suggest changes
+### Get support and provide feedbsck
 
-During the preview phase of this release, the standalone SDK may introduce a few more changes. These changes can be influenced by the community so report any feedback and suggestions to the SDK's [_new GitHub repo_](https://github.com/Azure/azure-functions-durable-powershell).
+Please report any feedback and suggestions to the SDK's [_GitHub repo_](https://github.com/Azure/azure-functions-durable-powershell).

articles/azure-functions/durable/durable-functions-sub-orchestrations.md

@@ -16,8 +16,8 @@ An orchestrator function can call another orchestrator function using the *"call
 Sub-orchestrator functions behave just like activity functions from the caller's perspective. They can return a value and throw an exception as the parent orchestrator function anticipates them.
 
 > [!NOTE]
-> Sub-orchestrations aren't yet supported in PowerShell.
-
+> In PowerShell, sub-orchestrations are supported in the standalone SDK only: [`AzureFunctions.PowerShell.Durable.SDK`](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK). See the difference between the standalone SDK and the legacy built-in SDK along with [migration guide](durable-functions-powershell-v2-sdk-migration-guide.md).
+ 
 [!INCLUDE [functions-nodejs-durable-model-description](../../../includes/functions-nodejs-durable-model-description.md)]
 
 ## Example
@@ -147,6 +147,29 @@ public void deviceProvisioningOrchestration(
 }
 ```
 
+# [PowerShell](#tab/powershell)
+
+```powershell
+param($Context)
+
+$deviceId = $Context.Input
+
+# Step 1: Create an installation package in blob storage and return a SAS URL.
+$sasUrl = Invoke-DurableActivity -FunctionName "CreateInstallationPackage" -Input $deviceId
+
+# Step 2: Notify the device that the installation package is ready.
+$deviceInfo = @{
+    id = $deviceId
+    url = $sasUrl
+}
+Invoke-DurableActivity -FunctionName "SendPackageUrlToDevice" -Input $deviceInfo
+
+# Step 3: Wait for the device to acknowledge that it has downloaded the new package.
+Start-DurableExternalEventListener -EventName "DownloadCompletedAck"
+
+# Step 4: ...
+```
+
 ---
 
 This orchestrator function can be used as-is for one-off device provisioning or it can be part of a larger orchestration. In the latter case, the parent orchestrator function can schedule instances of `DeviceProvisioningOrchestration` using the *"call-sub-orchestrator"* API.
@@ -296,6 +319,31 @@ public void provisionNewDevices(
 }
 ```
 
+# [PowerShell](#tab/powershell)
+
+```powershell
+param($Context)
+
+$deviceIds = Invoke-DurableActivity -FunctionName "GetNewDeviceIds"
+
+# Run multiple device provisioning flows in parallel
+$provisioningTasks = @()
+for ($i = 0; $i -lt $deviceIds.Count; $i++) {
+    $deviceId = $deviceIds[$i]
+    $childId = "$($Context.InstanceId):$i"
+    $provisionTask = Invoke-DurableSubOrchestrator `
+        -FunctionName "DeviceProvisioningOrchestration" `
+        -Input $deviceId `
+        -InstanceId $childId `
+        -NoWait
+    $provisioningTasks += $provisionTask
+}
+
+Wait-DurableTask -Task $provisioningTasks
+
+# ...
+```
+
 ---
 
 > [!NOTE]

articles/azure-functions/durable/quickstart-powershell-vscode.md

@@ -56,21 +56,42 @@ Visual Studio Code installs Azure Functions Core Tools if it's required to creat
 
 A *package.json* file is also created in the root folder.
 
-### Configure the function app to use PowerShell 7
+### Configure the function app to use PowerShell 7.4 and the standalone Durable Functions SDK
 
-Open the *local.settings.json* file and confirm that a setting named `FUNCTIONS_WORKER_RUNTIME_VERSION` is set to `~7`. If it's missing or if it's set to another value, update the contents of the file.
+Open the *local.settings.json* file and confirm that a setting named `FUNCTIONS_WORKER_RUNTIME_VERSION` is set to `7.4` and a setting named `ExternalDurablePowerShellSDK` is set to `true`. If they are missing or if they are set to other values, update the contents of the file.
 
 ```json
 {
   "IsEncrypted": false,
   "Values": {
     "AzureWebJobsStorage": "",
     "FUNCTIONS_WORKER_RUNTIME": "powershell",
-    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7"
+    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4",
+    "ExternalDurablePowerShellSDK": "true"
   }
 }
 ```
 
+Next, specify an entry for the DF SDK in your `requirements.psd1` file, as in the example below:
+
+```PowerShell
+# This file enables modules to be automatically managed by the Functions service.
+# See https://aka.ms/functionsmanageddependency for additional information.
+#
+@{
+    # For latest supported version, go to 'https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK/'.
+    'AzureFunctions.PowerShell.Durable.SDK' = '2.*'
+}
+```
+
+Make sure you use the latest version of the [AzureFunctions.PowerShell.Durable.SDK](https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK) module. The `2.*` version specifier ensures you get the latest stable 2.x version.
+
+Add the following line to your `profile.ps1` file (typically, at the end of the file):
+
+```PowerShell
+Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop
+```
+
 ## Create your functions
 
 The most basic Durable Functions app has three functions:
@@ -127,8 +148,8 @@ You added an HTTP-triggered function that starts an orchestration. Open *HttpSta
 
 You now have a Durable Functions app that you can run locally and deploy to Azure.
 
-> [!NOTE]
-> The next version of the Durable Functions PowerShell application is now in preview. You can download it from the PowerShell Gallery. Learn more about it and learn how to try it out in the [guide to the standalone PowerShell SDK](./durable-functions-powershell-v2-sdk-migration-guide.md). You can follow the guide's [installation section](./durable-functions-powershell-v2-sdk-migration-guide.md#install-and-enable-the-sdk) for instructions that are compatible with this quickstart to enable it.
+> [!TIP]
+> This quickstart uses the standalone Durable Functions PowerShell SDK, which is now generally available and provides the best performance and latest features. For more information about the SDK and migration from the legacy built-in version, see the [standalone PowerShell SDK guide](./durable-functions-powershell-v2-sdk-migration-guide.md).
 
 ## Test the function locally
 
@@ -194,6 +215,8 @@ After you verify that the function runs correctly on your local computer, it's t
 
 ## Test your function in Azure
 
+1. Make sure the app setting named `ExternalDurablePowerShellSDK` is set to `true`.
+
 1. Copy the URL of the HTTP trigger from the output panel. The URL that calls your HTTP-triggered function should be in this format:
 
    `https://<functionappname>.azurewebsites.net/api/orchestrators/HelloOrchestrator`