Guide to the standalone Durable Functions PowerShell SDK

The standalone Durable Functions PowerShell SDK (AzureFunctions.PowerShell.Durable.SDK) is the recommended approach for authoring Durable Functions apps with PowerShell. It replaces the built-in SDK with faster replay logic (the same engine as the C# isolated SDK), independent versioning, and improved exception handling, null-value handling, and serialization. The built-in SDK remains available for PowerShell 7.4 and earlier but will be removed in a future major release of the PowerShell worker.

Migration checklist

Use the following checklist to track your progress through each migration step:

Install the standalone SDK

Follow these steps to install and enable the standalone SDK in your existing app.

Verify prerequisites

The standalone PowerShell SDK requires the following minimum versions:

• Azure Functions Runtime v4.16+
• Azure Functions Core Tools v4.0.5095+ (if running locally)
• Azure Functions PowerShell app for PowerShell 7.4 or greater

Enable the standalone SDK

The following application setting is required to run the standalone PowerShell SDK:

• Name: ExternalDurablePowerShellSDK
• Value: "true"

This application setting disables 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, 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:

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings ExternalDurablePowerShellSDK="true"

Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"ExternalDurablePowerShellSDK" = "'true'"}

Install the SDK package

You have two options for installing the SDK package. Use managed dependencies (recommended for most apps) or bundle the module with your app content if you need to pin a specific version or your deployment doesn't support managed dependencies. Only one option is needed.

Option 1: Use managed dependencies (recommended)

To install the SDK as a managed dependency, follow the managed dependencies guidance. First, ensure your host.json contains a managedDependency section with enabled set to true:

{
  "version": "2.0",
  "managedDependency": {
    "enabled": true
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  }
}

Then specify an entry for the SDK in your requirements.psd1 file:

# 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.*'
}

Option 2: Include the SDK module in your app content

To bundle the SDK with your app, place the SDK package inside a ".\Modules" directory at the root of your app. For more information, see Including modules in app content.

From your application root, create the directory and download the SDK:

Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"

Import the SDK

Add the following line to your profile.ps1 file to import the SDK on every cold start:

Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

Run your app

Start your app with func host start. The standalone SDK is now active.

Migrate from the built-in SDK

If you're migrating an existing app from the built-in SDK, review the following interface and behavioral changes.

New cmdlets

Modified cmdlets

Behavioral changes

Exception handling in Wait-DurableTask

Exceptions thrown by activities scheduled with Wait-DurableTask (fan-out/fan-in pattern) are no longer silently ignored. The cmdlet now propagates the exception to the orchestrator so you can handle it in your code.

Built-in SDK — exceptions were silently swallowed:

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

Standalone SDK — exceptions propagate to the orchestrator:

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Null values preserved in Wait-DurableTask results

Null values are no longer dropped from the result list of a Wait-DurableTask (WhenAll) invocation. A successful call without the -Any flag now returns an array of the same size as the number of tasks scheduled, including $null entries for activities that returned null.

Built-in SDK — null results were dropped:

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

Standalone SDK — null results are preserved:

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

SDK reference

For the complete cmdlet reference, see AzureFunctions.PowerShell.Durable.SDK Module. After importing the module, you can also run Get-Help *-Durable* to list all available cmdlets, or Get-Help <cmdlet-name> -Full for detailed usage.

Get support

Report bugs and feature requests in the SDK's GitHub repo.

Next steps

• Create a Durable Functions app with PowerShell
• Durable Functions patterns and concepts
• PowerShell developer reference for Azure Functions