diff --git a/build.ps1 b/build.ps1 index 704fa05..dad15bc 100644 --- a/build.ps1 +++ b/build.ps1 @@ -76,6 +76,35 @@ Get-ChildItem -Path (Join-Path "$shimPath" "$publishPathSuffix") | Write-Log "Copying PowerShell module and manifest from the Durable SDK source code into $outputPath" "Gray" Copy-Item -Path $powerShellModulePath -Destination $outputPath Copy-Item -Path $manifestPath -Destination $outputPath + +#region GENERATE EXTERNAL HELP =================================================================== +Write-Log "Generating external help files (MAML) from markdown documentation..." "Gray" + +# Install PlatyPS module if not already available +if (-not (Get-Module -ListAvailable -Name PlatyPS)) { + Write-Log "Installing PlatyPS module..." "Cyan" + Install-Module -Name PlatyPS -Force -Scope CurrentUser +} + +# Import PlatyPS module +Import-Module PlatyPS -Force + +# Define paths for help generation +$docsPath = "$PSScriptRoot/src/Help" +$helpPath = "$outputPath/en-US" + +# Create the help directory if it doesn't exist +if (-not (Test-Path $helpPath)) { + Write-Log "Creating help directory at $helpPath" "Cyan" + New-Item -Path $helpPath -ItemType Directory -Force +} + +# Generate external help files from markdown +Write-Log "Converting markdown files to MAML help files..." "Gray" +New-ExternalHelp -Path $docsPath -OutputPath $helpPath -Force +Write-Log "External help files generated successfully in $helpPath" "Green" +#endregion + Write-Log "Build succeeded!" #endregion diff --git a/src/AzureFunctions.PowerShell.Durable.SDK.psm1 b/src/AzureFunctions.PowerShell.Durable.SDK.psm1 index 1cffa0c..4806a49 100644 --- a/src/AzureFunctions.PowerShell.Durable.SDK.psm1 +++ b/src/AzureFunctions.PowerShell.Durable.SDK.psm1 @@ -69,21 +69,6 @@ function Get-DurableStatus { Invoke-RestMethod -Uri $requestUrl } -<# -.SYNOPSIS - Start an orchestration Azure Function. -.DESCRIPTION - Start an orchestration Azure Function with the given function name and input value. -.EXAMPLE - PS > Start-DurableOrchestration -DurableClient Starter -FunctionName OrchestratorFunction -InputObject "input value for the orchestration function" - Return the instance id of the new orchestration. -.PARAMETER FunctionName - The name of the orchestration Azure Function you want to start. -.PARAMETER InputObject - The input value that will be passed to the orchestration Azure Function. -.PARAMETER DurableClient - The orchestration client object. -#> function Start-DurableOrchestration { [CmdletBinding()] param( @@ -284,25 +269,6 @@ function New-DurableOrchestrationCheckStatusResponse { } } -<# -.SYNOPSIS - Send an external event to an orchestration instance. -.DESCRIPTION - Send an external event with the given event name, and event data to an orchestration instance with the given instance ID. -.EXAMPLE - PS > Send-DurableExternalEvent -InstanceId "example-instance-id" -EventName "ExampleExternalEvent" -EventData "data for the external event" - Return the instance id of the new orchestration. -.PARAMETER InstanceId - The ID of the orchestration instance that will handle the external event. -.PARAMETER EventName - The name of the external event. -.PARAMETER EventData - The JSON-serializable data associated with the external event. -.PARAMETER TaskHubName - The TaskHubName of the orchestration instance that will handle the external event. -.PARAMETER ConnectionName - The name of the connection string associated with TaskHubName -#> function Send-DurableExternalEvent { [CmdletBinding()] param( diff --git a/src/Help/AzureFunctions.PowerShell.Durable.SDK.md b/src/Help/AzureFunctions.PowerShell.Durable.SDK.md new file mode 100644 index 0000000..786e23e --- /dev/null +++ b/src/Help/AzureFunctions.PowerShell.Durable.SDK.md @@ -0,0 +1,83 @@ +--- +Module Name: AzureFunctions.PowerShell.Durable.SDK +Module Guid: 841fad61-94f5-4330-89be-613d54165289 +Download Help Link: https://github.com/Azure/azure-functions-durable-powershell +Help Version: 1.0.0.0 +Locale: en-US +--- + +# AzureFunctions.PowerShell.Durable.SDK Module + +## Description + +The AzureFunctions.PowerShell.Durable.SDK module provides cmdlets for building durable, stateful functions in Azure Functions using PowerShell. This SDK enables you to create orchestrator functions, activity functions, and manage durable orchestration workflows with features like timers, external events, and sub-orchestrations. + +## AzureFunctions.PowerShell.Durable.SDK Cmdlets + +### [Get-DurableStatus](Get-DurableStatus.md) + +Gets the status of a durable orchestration instance, including execution history, input data, and output data. + +### [Get-DurableTaskResult](Get-DurableTaskResult.md) + +Gets the result of a completed durable task, such as an activity function or sub-orchestrator. + +### [Invoke-DurableActivity](Invoke-DurableActivity.md) + +Invokes an activity function from within an orchestrator function. + +### [Invoke-DurableSubOrchestrator](Invoke-DurableSubOrchestrator.md) + +Invokes a sub-orchestrator function from within a parent orchestrator function. + +### [New-DurableOrchestrationCheckStatusResponse](New-DurableOrchestrationCheckStatusResponse.md) + +Creates an HTTP response for orchestration status check endpoints with status polling URLs. + +### [New-DurableRetryPolicy](New-DurableRetryPolicy.md) + +Creates a retry policy for durable activity functions and sub-orchestrators. + +### [Resume-DurableOrchestration](Resume-DurableOrchestration.md) + +Resumes a suspended durable orchestration instance. + +### [Send-DurableExternalEvent](Send-DurableExternalEvent.md) + +Sends an external event to a running durable orchestration instance. + +### [Set-DurableCustomStatus](Set-DurableCustomStatus.md) + +Sets custom status information for a durable orchestration instance. + +### [Set-FunctionInvocationContext](Set-FunctionInvocationContext.md) + +Sets the function invocation context for durable function operations. + +### [Start-DurableExternalEventListener](Start-DurableExternalEventListener.md) + +Starts listening for an external event within an orchestrator function. + +### [Start-DurableOrchestration](Start-DurableOrchestration.md) + +Starts a new durable orchestration instance with the specified function name and input. + +### [Start-DurableTimer](Start-DurableTimer.md) + +Starts a durable timer that fires after a specified delay or at a specific time. + +### [Stop-DurableOrchestration](Stop-DurableOrchestration.md) + +Terminates a running durable orchestration instance. + +### [Stop-DurableTimerTask](Stop-DurableTimerTask.md) + +Stops a running durable timer task. + +### [Suspend-DurableOrchestration](Suspend-DurableOrchestration.md) + +Suspends a running durable orchestration instance. + +### [Wait-DurableTask](Wait-DurableTask.md) + +Waits for the completion of one or more durable tasks within an orchestrator function. diff --git a/src/Help/Get-DurableStatus.md b/src/Help/Get-DurableStatus.md new file mode 100644 index 0000000..5c4988d --- /dev/null +++ b/src/Help/Get-DurableStatus.md @@ -0,0 +1,161 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Get-DurableStatus + +## SYNOPSIS + +Get the status of a durable orchestration instance. + +## SYNTAX + +``` +Get-DurableStatus [-InstanceId] [-DurableClient ] [-ShowHistory] [-ShowHistoryOutput] [-ShowInput] [] +``` + +## DESCRIPTION + +Get the status of a durable orchestration instance with the given instance ID. +Optionally includes execution history, history output, and input data. + +## EXAMPLES + +### Example 1 + +```powershell +Get-DurableStatus -InstanceId "example-instance-id" +``` + +Returns the basic status of the orchestration instance. + +### Example 2 + +```powershell +Get-DurableStatus -InstanceId "example-instance-id" -ShowHistory -ShowHistoryOutput +``` + +Returns the status with detailed execution history and output. + +## PARAMETERS + +### -InstanceId + +The ID of the orchestration instance to get the status for. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -DurableClient + +The durable client object. +If not provided, it will be retrieved from module private data. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ShowHistory + +When present, includes the execution history in the response. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ShowHistoryOutput + +When present, includes the output of each step in the execution history. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ShowInput + +When present, includes the input data that was provided to the orchestration instance. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +You can pipe instance ID strings to this cmdlet to get the status of multiple orchestration instances. + +## OUTPUTS + +### System.Object + +Returns a status object containing information about the durable orchestration instance, including: + +- InstanceId: The unique identifier of the orchestration instance +- RuntimeStatus: The current runtime status (Running, Completed, Failed, etc.) +- Input: The input data provided to the orchestration (if -ShowInput is specified) +- Output: The output of the orchestration (if completed) +- CreatedTime: When the orchestration was created +- LastUpdatedTime: When the orchestration was last updated +- History: Execution history (if -ShowHistory is specified) + +## NOTES + +- This cmdlet is typically used in HTTP trigger functions or other client functions to check orchestration progress. +- The InstanceId must be from an existing orchestration; invalid IDs will result in a null response. +- Use -ShowHistory to get detailed execution steps, which is useful for debugging orchestration behavior. +- The -ShowHistoryOutput parameter can produce large responses; use carefully in production environments. +- Status information includes runtime state, input/output data, creation time, and last update time. +- Orchestration status is eventually consistent and may take a moment to reflect the latest state after operations. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Get-DurableTaskResult.md b/src/Help/Get-DurableTaskResult.md new file mode 100644 index 0000000..955e3c8 --- /dev/null +++ b/src/Help/Get-DurableTaskResult.md @@ -0,0 +1,84 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Get-DurableTaskResult + +## SYNOPSIS + +Gets the result value from a completed durable task. + +## SYNTAX + +``` +Get-DurableTaskResult -Task [] +``` + +## DESCRIPTION + +Retrieves the result value from a completed durable task. This cmdlet blocks execution +until the specified task completes and then returns the task's result value. The type +and content of the returned result depend on what the underlying activity function or +sub-orchestrator returned. This is typically used within orchestrator functions to +obtain the output of previously scheduled durable tasks. + +## EXAMPLES + +### Example 1 + +```powershell +$task = Invoke-DurableActivity -FunctionName "GetUserData" -Input @{ UserId = 123 } -NoWait +$result = Get-DurableTaskResult -Task $task +Write-Host "User data: $result" +``` + +This example demonstrates invoking a durable activity function asynchronously with -NoWait to get a task, then using Get-DurableTaskResult to retrieve the result from the task. + +## PARAMETERS + +### -Task + +The durable task object whose result you want to retrieve. This should be a task returned from cmdlets like Invoke-DurableActivity, Invoke-DurableSubOrchestrator, Start-DurableTimer, or Start-DurableExternalEventListener. + +```yaml +Type: DurableTask +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### System.Object + +Returns the result value from the completed durable task. The type and content depend on what the underlying activity function or sub-orchestrator returned. + +## NOTES + +- This cmdlet is typically used within orchestrator functions to retrieve results from tasks created with the -NoWait parameter. +- The cmdlet blocks execution until the specified task completes, which maintains the deterministic nature of orchestrations. +- If a task fails, this cmdlet will throw an exception with details about the failure. +- Tasks should be created within the same orchestration context where this cmdlet is called. +- Use Wait-DurableTask when you need to wait for multiple tasks with timeout or any/all semantics. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Invoke-DurableActivity.md b/src/Help/Invoke-DurableActivity.md new file mode 100644 index 0000000..013232a --- /dev/null +++ b/src/Help/Invoke-DurableActivity.md @@ -0,0 +1,141 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Invoke-DurableActivity + +## SYNOPSIS + +Invokes a durable activity function. + +## SYNTAX + +``` +Invoke-DurableActivity -FunctionName [-Input ] [-RetryOptions ] [-NoWait] [] +``` + +## DESCRIPTION + +Schedules a durable activity function for execution. By default, this cmdlet blocks +until the activity completes and returns the result directly. Use the -NoWait switch +to return a task object immediately without waiting for completion, allowing the +orchestrator to schedule multiple activities concurrently and retrieve their results +later using Get-DurableTaskResult or Wait-DurableTask. + +## EXAMPLES + +### Example 1 - Synchronous execution (default behavior) + +```powershell +$result = Invoke-DurableActivity -FunctionName "ProcessData" -Input @{ Data = "example"; ProcessType = "validation" } +Write-Host "Processing result: $result" +``` + +This example shows the default behavior where the cmdlet blocks until completion and returns the result directly. + +### Example 2 - Asynchronous execution with -NoWait + +```powershell +$task = Invoke-DurableActivity -FunctionName "ProcessData" -Input @{ Data = "example"; ProcessType = "validation" } -NoWait +$result = Get-DurableTaskResult -Task $task +Write-Host "Processing result: $result" +``` + +This example shows how to invoke a durable activity function asynchronously using -NoWait, which returns a task object that can be awaited later. + +## PARAMETERS + +### -FunctionName + +The name of the activity function to invoke. This should match the name of an activity function defined in your Azure Functions app. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Input + +The input data to pass to the activity function. This can be any object that will be serialized and passed as input to the activity function. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoWait + +When specified, the cmdlet returns a task object immediately without waiting for completion. By default, the cmdlet blocks and waits for the activity to complete before returning the result. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RetryOptions + +A retry policy object created with New-DurableRetryPolicy that defines how the activity should be retried if it fails. If not specified, the activity will not be retried on failure. + +```yaml +Type: RetryPolicy +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### System.Object + +Returns the result of the activity function execution by default. If -NoWait is specified, returns a DurableTask object that can be used with Get-DurableTaskResult or Wait-DurableTask to retrieve the result later. + +## NOTES + +- This cmdlet can only be used within orchestrator functions, not in activity functions or client functions. +- The activity function name must match a function defined in your Azure Functions app. +- Activity functions are automatically retried on transient failures when a RetryOptions policy is specified. +- Activity functions should be stateless and idempotent. +- Use the -NoWait parameter when you need to invoke multiple activities concurrently (fan-out pattern). + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Invoke-DurableSubOrchestrator.md b/src/Help/Invoke-DurableSubOrchestrator.md new file mode 100644 index 0000000..75986a8 --- /dev/null +++ b/src/Help/Invoke-DurableSubOrchestrator.md @@ -0,0 +1,159 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Invoke-DurableSubOrchestrator + +## SYNOPSIS + +Invokes a sub-orchestrator function. + +## SYNTAX + +``` +Invoke-DurableSubOrchestrator -FunctionName [-InstanceId ] [-Input ] [-RetryOptions ] [-NoWait] [] +``` + +## DESCRIPTION + +Invokes a sub-orchestrator function. By default, this cmdlet blocks until the +sub-orchestrator completes and returns the result directly. Use the -NoWait switch +to return a task object immediately without waiting for completion, allowing you to +orchestrate multiple sub-orchestrators concurrently. Sub-orchestrators enable +composition of orchestrations and help manage complexity in large workflow scenarios. + +## EXAMPLES + +### Example 1 - Synchronous execution (default behavior) + +```powershell +$batchResult = Invoke-DurableSubOrchestrator -FunctionName "ChildOrchestrator" -Input @{ BatchId = "batch123"; Items = @("item1", "item2", "item3") } +Write-Host "Sub-orchestrator completed with result: $batchResult" +``` + +This example shows the default behavior where the cmdlet blocks until completion and returns the result directly. + +### Example 2 - Asynchronous execution with -NoWait + +```powershell +$subOrchestratorTask = Invoke-DurableSubOrchestrator -FunctionName "ChildOrchestrator" -Input @{ BatchId = "batch123"; Items = @("item1", "item2", "item3") } -NoWait +$batchResult = Get-DurableTaskResult -Task $subOrchestratorTask +Write-Host "Sub-orchestrator completed with result: $batchResult" +``` + +This example shows how to invoke a sub-orchestrator function asynchronously using -NoWait, which returns a task object that can be awaited later. + +## PARAMETERS + +### -FunctionName + +The name of the orchestrator function to invoke as a sub-orchestrator. This should match the name of an orchestrator function defined in your Azure Functions app. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Input + +The input data to pass to the sub-orchestrator function. This can be any object that will be serialized and passed as input to the sub-orchestrator. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstanceId + +An optional instance ID for the sub-orchestrator. If not specified, a unique instance ID will be automatically generated for the sub-orchestrator. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoWait + +When specified, the cmdlet returns a task object immediately without waiting for completion. By default, the cmdlet blocks and waits for the sub-orchestrator to complete before returning the result. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RetryOptions + +A retry policy object created with New-DurableRetryPolicy that defines how the sub-orchestrator should be retried if it fails. If not specified, the sub-orchestrator will not be retried on failure. + +```yaml +Type: RetryPolicy +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### System.Object + +Returns the result of the sub-orchestrator execution by default. If -NoWait is specified, returns a DurableTask object that can be used with Get-DurableTaskResult or Wait-DurableTask to retrieve the result later. + +## NOTES + +- This cmdlet can only be used within orchestrator functions, not in activity functions or client functions. +- Sub-orchestrators enable composition and modularity in complex workflow scenarios. +- Each sub-orchestrator runs as an independent orchestration instance with its own instance ID. +- Use the -NoWait parameter when you need to invoke multiple sub-orchestrators concurrently. +- Sub-orchestrators inherit the fault-tolerance and replay characteristics of the parent orchestration. +- The sub-orchestrator function name must match a function defined in your Azure Functions app with an orchestration trigger. +- Consider using sub-orchestrators to break down complex workflows into manageable, reusable components. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/New-DurableOrchestrationCheckStatusResponse.md b/src/Help/New-DurableOrchestrationCheckStatusResponse.md new file mode 100644 index 0000000..dfb9e4b --- /dev/null +++ b/src/Help/New-DurableOrchestrationCheckStatusResponse.md @@ -0,0 +1,115 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# New-DurableOrchestrationCheckStatusResponse + +## SYNOPSIS + +Create a check status response for a durable orchestration. + +## SYNTAX + +``` +New-DurableOrchestrationCheckStatusResponse [-Request] [-InstanceId] [[-DurableClient] ] [] +``` + +## DESCRIPTION + +Creates an HTTP response with status check URLs for a durable orchestration instance. +This response includes URLs for checking status, terminating, suspending, resuming, and raising events. + +## EXAMPLES + +### Example 1 + +```powershell +New-DurableOrchestrationCheckStatusResponse -Request $Request -InstanceId "example-instance-id" +``` + +Creates a standard orchestration check status response with management URLs. + +## PARAMETERS + +### -Request + +The HTTP request object that triggered the orchestration. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -InstanceId + +The ID of the orchestration instance for which to create the check status response. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -DurableClient + +The durable client context object used to generate management URLs for the orchestration instance. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Object (Request) + +You can pipe HTTP request objects to create status check responses for multiple orchestrations. + +### System.String (InstanceId) + +You can pipe instance ID strings to generate status check responses for specific orchestration instances. + +## OUTPUTS + +### HttpResponseContext + +Returns an HTTP response context with status code 202 (Accepted) and management URLs for checking orchestration status, sending external events, and terminating the orchestration. + +## NOTES + +- This cmdlet is typically used in HTTP trigger functions after starting an orchestration to provide management URLs. +- The response includes a 202 (Accepted) status code following the standard async HTTP pattern. +- The generated URLs allow clients to check status, send events, and manage the orchestration without additional authentication. +- Store the instanceId securely if the orchestration contains sensitive data, as anyone with the URLs can manage the orchestration. +- The response follows the Durable Functions HTTP API conventions for orchestration management. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/New-DurableRetryPolicy.md b/src/Help/New-DurableRetryPolicy.md new file mode 100644 index 0000000..165a4ac --- /dev/null +++ b/src/Help/New-DurableRetryPolicy.md @@ -0,0 +1,146 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# New-DurableRetryPolicy + +## SYNOPSIS + +Creates a new retry policy for durable activity functions and sub-orchestrators. + +## SYNTAX + +``` +New-DurableRetryPolicy -FirstRetryInterval -MaxNumberOfAttempts [-BackoffCoefficient ] [-MaxRetryInterval ] [-RetryTimeout ] [] +``` + +## DESCRIPTION + +Creates a retry policy object that can be used with durable activity functions and +sub-orchestrators to handle transient failures. The retry policy defines how many +times an operation should be retried, the delay between retries, and optionally +a maximum retry interval and backoff coefficient. This helps make orchestrations +more resilient to temporary failures in downstream services or activities. + +## EXAMPLES + +### Example 1 + +```powershell +$retryPolicy = New-DurableRetryPolicy -MaxNumberOfAttempts 5 -FirstRetryInterval (New-TimeSpan -Seconds 30) -BackoffCoefficient 2.0 +$task = Invoke-DurableActivity -FunctionName "UnreliableOperation" -Input $data -RetryOptions $retryPolicy -NoWait +$result = Get-DurableTaskResult -Task $task +``` + +This example creates a retry policy with 5 maximum attempts, starting with a 30-second interval and doubling the delay with each retry, then uses it with a durable activity invoked asynchronously. + +## PARAMETERS + +### -BackoffCoefficient + +The coefficient used to calculate exponential backoff between retry attempts. Must be greater than 1.0. Default is 2.0, which doubles the delay between each retry attempt. + +```yaml +Type: Double +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FirstRetryInterval + +The initial retry interval in seconds. This is the delay before the first retry attempt. + +```yaml +Type: TimeSpan +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxNumberOfAttempts + +The maximum number of retry attempts. Must be a positive integer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxRetryInterval + +The maximum retry interval in seconds. Retry intervals will not exceed this value regardless of the backoff coefficient. + +```yaml +Type: TimeSpan +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RetryTimeout + +The total timeout for all retry attempts as a TimeSpan. If this timeout is exceeded, no further retries will be attempted. + +```yaml +Type: TimeSpan +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### RetryPolicy + +Returns a RetryPolicy object that can be used with Invoke-DurableActivity or Invoke-DurableSubOrchestrator to specify retry behavior for failed operations. + +## NOTES + +- Retry policies help make orchestrations more resilient to transient failures in downstream services. +- Retry policies work with both Invoke-DurableActivity and Invoke-DurableSubOrchestrator cmdlets. +- Failed attempts will be logged in the orchestration history for debugging purposes. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Resume-DurableOrchestration.md b/src/Help/Resume-DurableOrchestration.md new file mode 100644 index 0000000..543e0ae --- /dev/null +++ b/src/Help/Resume-DurableOrchestration.md @@ -0,0 +1,101 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Resume-DurableOrchestration + +## SYNOPSIS + +Resume a suspended durable orchestration instance. + +## SYNTAX + +``` +Resume-DurableOrchestration [-InstanceId] [-Reason] [] +``` + +## DESCRIPTION + +Resumes a previously suspended durable orchestration instance with the specified instance ID and reason. +This will continue execution from where the orchestration was suspended. + +## EXAMPLES + +### Example 1 + +```powershell +Resume-DurableOrchestration -InstanceId "example-instance-id" -Reason "Maintenance complete" +``` + +Resumes the orchestration instance with the provided reason. + +## PARAMETERS + +### -InstanceId + +The ID of the orchestration instance to resume. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Reason + +The reason for resuming the orchestration instance. +This will be recorded in the instance history. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String (InstanceId) + +You can pipe instance ID strings to resume multiple orchestration instances. + +### System.String (Reason) + +You can pipe reason strings to specify the resumption reason for orchestration instances. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It resumes the specified suspended orchestration instance. + +## NOTES + +- This cmdlet can only be used in client functions, not within orchestrator or activity functions. +- Only orchestrations in a "Suspended" state can be resumed. +- The resume operation is asynchronous; the orchestration will continue from where it was suspended. +- Use Get-DurableStatus to verify the orchestration is in a "Suspended" state before attempting to resume. +- The resumption reason is helpful for tracking why an orchestration was resumed. +- Resumed orchestrations will continue with their original input and context. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Send-DurableExternalEvent.md b/src/Help/Send-DurableExternalEvent.md new file mode 100644 index 0000000..bda3245 --- /dev/null +++ b/src/Help/Send-DurableExternalEvent.md @@ -0,0 +1,153 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Send-DurableExternalEvent + +## SYNOPSIS + +Send an external event to an orchestration instance. + +## SYNTAX + +``` +Send-DurableExternalEvent [-InstanceId] [-EventName] [[-EventData] ] [-TaskHubName ] [-ConnectionName ] [] +``` + +## DESCRIPTION + +Send an external event with the given event name and event data to an orchestration instance with the given instance ID. +The orchestration must be waiting for this event using Start-DurableExternalEventListener. + +## EXAMPLES + +### Example 1 + +```powershell +Send-DurableExternalEvent -InstanceId "example-instance-id" -EventName "ApprovalReceived" -EventData "approved" +``` + +Sends an external event to the orchestration instance. + +## PARAMETERS + +### -InstanceId + +The ID of the orchestration instance that will handle the external event. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -EventName + +The name of the external event. +This must match the event name the orchestration is waiting for. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -EventData + +The JSON-serializable data associated with the external event. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -TaskHubName + +The TaskHubName of the orchestration instance that will handle the external event. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ConnectionName + +The name of the connection string associated with TaskHubName. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String (InstanceId) + +You can pipe instance ID strings to specify which orchestration instance should receive the external event. + +### System.String (EventName) + +You can pipe event name strings to specify the name of the external event to send. + +### System.Object (EventData) + +You can pipe objects containing event data to be sent with the external event. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It sends the specified external event to the target orchestration instance. + +## NOTES + +- This cmdlet is typically used in HTTP trigger functions or other client functions to send events to running orchestrations. +- The target orchestration must be actively listening for the event using Start-DurableExternalEventListener. +- Event names are case-sensitive and must match exactly between sender and listener. +- Events sent to orchestrations that are not listening will be queued and delivered when a listener is started. +- Large event data should be stored in external storage and referenced by URL to avoid serialization limits. +- External events provide a way to implement human-in-the-loop patterns and real-time orchestration control. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Set-DurableCustomStatus.md b/src/Help/Set-DurableCustomStatus.md new file mode 100644 index 0000000..04918f6 --- /dev/null +++ b/src/Help/Set-DurableCustomStatus.md @@ -0,0 +1,85 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Set-DurableCustomStatus + +## SYNOPSIS + +Sets a custom status value for the current durable orchestration instance. + +## SYNTAX + +``` +Set-DurableCustomStatus [-CustomStatus] [] +``` + +## DESCRIPTION + +Sets a custom status value for the current durable orchestration instance. This +status can be retrieved by external clients using the orchestration management APIs +to monitor the progress or state of the orchestration. The custom status is useful +for providing meaningful progress updates or state information that can be queried +from outside the orchestration function. + +## EXAMPLES + +### Example 1 + +```powershell +Set-DurableCustomStatus -CustomStatus @{ Phase = "Processing"; Progress = 45; ItemsProcessed = 90; TotalItems = 200 } +# Continue with orchestration logic... +Set-DurableCustomStatus -CustomStatus @{ Phase = "Finalizing"; Progress = 95; ItemsProcessed = 190; TotalItems = 200 } +``` + +This example shows how to set custom status information during an orchestration to track processing progress and phase. + +## PARAMETERS + +### -CustomStatus + +A custom object containing status information that will be available when querying the orchestration instance status. This can include progress indicators, current phase, error messages, or any other relevant status data. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Object + +You can pipe objects directly to this cmdlet to set them as the custom status for the current orchestration instance. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It sets the custom status for the current orchestration instance. + +## NOTES + +- This cmdlet can only be used within orchestrator functions, not in activity functions or client functions. +- Custom status is visible when querying orchestration status with Get-DurableStatus. +- Status updates are useful for providing progress information to external monitoring systems. +- The status object will be JSON-serialized, so it should contain serializable data types. +- Custom status is preserved across orchestration replays and checkpoints. +- Keep status objects reasonably small to avoid performance impacts during serialization. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Set-FunctionInvocationContext.md b/src/Help/Set-FunctionInvocationContext.md new file mode 100644 index 0000000..69b36b8 --- /dev/null +++ b/src/Help/Set-FunctionInvocationContext.md @@ -0,0 +1,128 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Set-FunctionInvocationContext + +## SYNOPSIS + +**INTERNAL USE ONLY** - Sets the function invocation context for the current PowerShell function execution. + +## SYNTAX + +### OrchestrationContext + +``` +Set-FunctionInvocationContext -OrchestrationContext [] +``` + +### DurableClient + +``` +Set-FunctionInvocationContext -DurableClient [] +``` + +### Clear + +``` +Set-FunctionInvocationContext [-Clear] [] +``` + +## DESCRIPTION + +**WARNING: This cmdlet is for internal use by the Durable Functions runtime only.** +**Do not call this cmdlet directly in your orchestrator or activity functions.** + +This cmdlet is used internally by the Durable Functions runtime to establish the +execution context that enables durable orchestration capabilities. It provides the +necessary context for orchestrator functions to interact with the Durable Functions +framework, including task scheduling and state management. + +Calling this cmdlet directly in user code may interfere with the runtime's operation +and could lead to unpredictable behavior or runtime errors. + +## EXAMPLES + +### Example 1 + +```powershell +# Internal use only - example for SDK development +Set-FunctionInvocationContext -OrchestrationContext $durableOrchestrationContext +``` + +This cmdlet is for internal SDK use only and should not be called directly in user orchestration functions. + +## PARAMETERS + +### -Clear + +A switch parameter that, when specified, clears the current function invocation context. For internal SDK use only. + +```yaml +Type: SwitchParameter +Parameter Sets: Clear +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DurableClient + +The durable client context object used for client operations. For internal SDK use only. + +```yaml +Type: Object +Parameter Sets: DurableClient +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OrchestrationContext + +The orchestration context object containing the current orchestration state and capabilities. For internal SDK use only. + +```yaml +Type: String +Parameter Sets: OrchestrationContext +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It sets the function invocation context for use with durable function operations. + +## NOTES + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Start-DurableExternalEventListener.md b/src/Help/Start-DurableExternalEventListener.md new file mode 100644 index 0000000..e6de9fc --- /dev/null +++ b/src/Help/Start-DurableExternalEventListener.md @@ -0,0 +1,112 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Start-DurableExternalEventListener + +## SYNOPSIS + +Starts listening for an external event with a specified name and returns a task that will complete when the event is received. + +## SYNTAX + +``` +Start-DurableExternalEventListener -EventName [-NoWait] [] +``` + +## DESCRIPTION + +Creates a task that waits for an external event with the specified name to be raised +for the current orchestration instance. By default, this cmdlet blocks until the +external event is received and returns the event data directly. Use the -NoWait switch +to return a task object immediately that can be awaited later. External events enable +building interactive workflows and human-in-the-loop scenarios. + +## EXAMPLES + +### Example 1 - Synchronous execution (default behavior) + +```powershell +$approvalData = Start-DurableExternalEventListener -EventName "UserApproval" +if ($approvalData.Approved) { /* proceed */ } else { /* handle rejection */ } +``` + +This example shows the default behavior where the cmdlet blocks until the external event is received and returns the event data directly. + +### Example 2 - Asynchronous execution with -NoWait + +```powershell +$eventListener = Start-DurableExternalEventListener -EventName "UserApproval" -NoWait +# Continue with other orchestration logic... +$approvalData = Get-DurableTaskResult -Task $eventListener +if ($approvalData.Approved) { /* proceed */ } else { /* handle rejection */ } +``` + +This example starts listening for an external event asynchronously using -NoWait, allowing other orchestration logic to execute while waiting for the event. + +## PARAMETERS + +### -EventName + +The name of the external event to listen for. This must match the event name used when sending the external event to the orchestration instance. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoWait + +A switch parameter that, when specified, starts the external event listener without waiting for the event. Returns a task that can be awaited later. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### DurableTask + +Returns a DurableTask object that represents the external event listener. This task can be used with Wait-DurableTask to wait for the external event to be received. + +## NOTES + +- This cmdlet can only be used within orchestrator functions, not in activity functions or client functions. +- External events are sent to orchestrations using the Send-DurableExternalEvent cmdlet from client functions. +- Event listeners are fault-tolerant and will survive orchestration replays and Azure Functions host restarts. +- Multiple listeners can wait for the same event name within a single orchestration. +- Use the -NoWait parameter when implementing timeout patterns or waiting for multiple different events. +- Event data is preserved across orchestration replays, ensuring exactly-once delivery semantics. +- The event name is case-sensitive and must match exactly between the listener and sender. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Start-DurableOrchestration.md b/src/Help/Start-DurableOrchestration.md new file mode 100644 index 0000000..1fd19ac --- /dev/null +++ b/src/Help/Start-DurableOrchestration.md @@ -0,0 +1,137 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Start-DurableOrchestration + +## SYNOPSIS + +Start a durable orchestration. + +## SYNTAX + +``` +Start-DurableOrchestration [-FunctionName] [[-InputObject] ] [-DurableClient ] [-InstanceId ] [] +``` + +## DESCRIPTION + +Start a durable orchestration with the given function name and input value. +Returns the instance ID of the newly started orchestration. + +## EXAMPLES + +### Example 1 + +``` +Start-DurableOrchestration -FunctionName "OrchestratorFunction" -InputObject "input value for the orchestration function" +Returns the instance ID of the new orchestration. +``` + +## PARAMETERS + +### -FunctionName + +The name of the orchestration function you want to start. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -InputObject + +The input value that will be passed to the orchestration function. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -DurableClient + +The durable client object. +If not provided, it will be retrieved from module private data. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -InstanceId + +Optional custom instance ID for the orchestration. +If not provided, a new GUID will be generated. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String (FunctionName) + +You can pipe strings to the -FunctionName parameter to specify the orchestrator function to start. + +### System.Object (InputObject) + +You can pipe objects to the -InputObject parameter to provide input data for the orchestration function. + +### System.String (InstanceId) + +You can pipe strings to the -InstanceId parameter to specify a custom instance ID for the orchestration. + +## OUTPUTS + +### System.String + +Returns the instance ID of the started orchestration as a string. This ID can be used to check the status, send external events, or manage the orchestration instance. + +## NOTES + +- This cmdlet is typically used in HTTP trigger functions or other client functions to start new orchestrations. +- The returned instance ID can be used with other cmdlets like Get-DurableStatus, Send-DurableExternalEvent, or Stop-DurableOrchestration. +- If you don't specify an InstanceId, a new GUID will be automatically generated. +- Custom instance IDs should be unique to avoid conflicts with existing orchestrations. +- Large input data should be stored in external storage and referenced by URL to avoid serialization limits. +- The orchestration function name must match a function defined in your Azure Functions app with an orchestration trigger. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Start-DurableTimer.md b/src/Help/Start-DurableTimer.md new file mode 100644 index 0000000..e2e8b5c --- /dev/null +++ b/src/Help/Start-DurableTimer.md @@ -0,0 +1,113 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Start-DurableTimer + +## SYNOPSIS + +Starts a durable timer that will complete after the specified duration. + +## SYNTAX + +``` +Start-DurableTimer -Duration [-NoWait] [] +``` + +## DESCRIPTION + +Creates a durable timer that will complete after the specified duration. By default, +this cmdlet blocks until the timer fires and returns completion status. Use the +-NoWait switch to return a task object immediately that can be awaited later. Durable +timers are fault-tolerant and will survive orchestration replays and restarts, making +them the recommended way to implement delays in durable orchestrations. + +## EXAMPLES + +### Example 1 - Synchronous execution (default behavior) + +```powershell +$duration = New-TimeSpan -Minutes 30 +Start-DurableTimer -Duration $duration +Write-Host "Timer completed, continuing with scheduled operation" +``` + +This example shows the default behavior where the cmdlet blocks until the timer fires. + +### Example 2 - Asynchronous execution with -NoWait + +```powershell +$duration = New-TimeSpan -Minutes 30 +$timerTask = Start-DurableTimer -Duration $duration -NoWait +# Continue with other orchestration logic... +Wait-DurableTask -Task $timerTask +Write-Host "Timer completed, continuing with scheduled operation" +``` + +This example creates a timer that will fire 30 minutes from now using -NoWait, allowing other logic to execute while the timer runs. + +## PARAMETERS + +### -Duration + +The duration to wait before the timer fires, specified as a TimeSpan object. Alternative to using FireAt parameter. + +```yaml +Type: TimeSpan +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoWait + +A switch parameter that, when specified, starts the timer without waiting for it to complete. Returns a task that can be awaited or cancelled later. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### DurableTask + +Returns a DurableTask object representing the timer. This task can be used with Wait-DurableTask to wait for the timer to complete or with Stop-DurableTimerTask to cancel it. + +## NOTES + +- This cmdlet can only be used within orchestrator functions, not in activity functions or client functions. +- Durable timers are fault-tolerant and will survive orchestration replays and Azure Functions host restarts. +- Use durable timers instead of Start-Sleep or similar delay mechanisms in orchestrator functions to maintain deterministic replay behavior. +- Timer tasks can be cancelled using Stop-DurableTimerTask if created with the -NoWait parameter. +- The maximum timer duration is limited by the orchestration timeout configuration of your Azure Functions app. +- Timers created with -NoWait return immediately and can be used in timeout patterns with Wait-DurableTask -Any. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Stop-DurableOrchestration.md b/src/Help/Stop-DurableOrchestration.md new file mode 100644 index 0000000..7a31b8e --- /dev/null +++ b/src/Help/Stop-DurableOrchestration.md @@ -0,0 +1,101 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Stop-DurableOrchestration + +## SYNOPSIS + +Stop (terminate) a running durable orchestration instance. + +## SYNTAX + +``` +Stop-DurableOrchestration [-InstanceId] [-Reason] [] +``` + +## DESCRIPTION + +Terminates a running durable orchestration instance with the specified instance ID and reason. +This is a permanent action that cannot be undone. + +## EXAMPLES + +### Example 1 + +```powershell +Stop-DurableOrchestration -InstanceId "example-instance-id" -Reason "User requested termination" +``` + +Terminates the orchestration instance with the provided reason. + +## PARAMETERS + +### -InstanceId + +The ID of the orchestration instance to terminate. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Reason + +The reason for terminating the orchestration instance. +This will be recorded in the instance history. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String (InstanceId) + +You can pipe instance ID strings to terminate multiple orchestration instances. + +### System.String (Reason) + +You can pipe reason strings to specify the termination reason for orchestration instances. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It terminates the specified orchestration instance. + +## NOTES + +- This cmdlet can only be used in client functions, not within orchestrator or activity functions. +- Termination is permanent and cannot be undone; the orchestration cannot be resumed after termination. +- The termination is asynchronous; the orchestration may take some time to actually stop. +- Terminated orchestrations will have a final status of "Terminated" when checked with Get-DurableStatus. +- Use descriptive termination reasons to help with debugging and monitoring. +- Consider using Suspend-DurableOrchestration if you need to temporarily halt an orchestration that can be resumed later. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Stop-DurableTimerTask.md b/src/Help/Stop-DurableTimerTask.md new file mode 100644 index 0000000..b0ff6c3 --- /dev/null +++ b/src/Help/Stop-DurableTimerTask.md @@ -0,0 +1,88 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Stop-DurableTimerTask + +## SYNOPSIS + +Stops (cancels) a running durable timer task. + +## SYNTAX + +``` +Stop-DurableTimerTask -Task [] +``` + +## DESCRIPTION + +Cancels a running durable timer task before it completes. This is useful for +implementing timeout patterns or canceling scheduled delays when certain conditions +are met. Once a timer task is stopped, it will not fire and any orchestration +code waiting on the timer will need to handle the cancellation appropriately. +This cmdlet is typically used in conjunction with Wait-DurableTask to implement +race conditions between timers and other operations. + +## EXAMPLES + +### Example 1 + +```powershell +$timerTask = Start-DurableTimer -Duration (New-TimeSpan -Hours 1) -NoWait +# Later, if condition is met, cancel the timer +if ($conditionMet) { + Stop-DurableTimerTask -Task $timerTask + Write-Host "Timer cancelled due to early completion" +} +``` + +This example starts a timer for 1 hour using -NoWait to get a task object, then cancels it early if a certain condition is met, preventing unnecessary waiting. + +## PARAMETERS + +### -Task + +The timer task object returned from Start-DurableTimer that should be cancelled. The task must be in a running state to be successfully cancelled. + +```yaml +Type: DurableTimerTask +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It cancels the specified durable timer task. + +## NOTES + +- This cmdlet is used to implement timeout patterns and early cancellation scenarios in orchestrations. +- Once a timer task is stopped, any code waiting on it should handle the cancellation appropriately. +- Timer cancellation is commonly used in race conditions between timers and other operations. +- Only running timer tasks can be successfully cancelled; completed timers cannot be stopped. +- Use this cmdlet with Wait-DurableTask to implement sophisticated timeout and cancellation patterns. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Suspend-DurableOrchestration.md b/src/Help/Suspend-DurableOrchestration.md new file mode 100644 index 0000000..fdf837a --- /dev/null +++ b/src/Help/Suspend-DurableOrchestration.md @@ -0,0 +1,101 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Suspend-DurableOrchestration + +## SYNOPSIS + +Suspend a running durable orchestration instance. + +## SYNTAX + +``` +Suspend-DurableOrchestration [-InstanceId] [-Reason] [] +``` + +## DESCRIPTION + +Suspends a running durable orchestration instance with the specified instance ID and reason. +A suspended instance can be resumed later using Resume-DurableOrchestration. + +## EXAMPLES + +### Example 1 + +```powershell +Suspend-DurableOrchestration -InstanceId "example-instance-id" -Reason "Maintenance window" +``` + +Suspends the orchestration instance with the provided reason. + +## PARAMETERS + +### -InstanceId + +The ID of the orchestration instance to suspend. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Reason + +The reason for suspending the orchestration instance. +This will be recorded in the instance history. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String (InstanceId) + +You can pipe instance ID strings to suspend multiple orchestration instances. + +### System.String (Reason) + +You can pipe reason strings to specify the suspension reason for orchestration instances. + +## OUTPUTS + +### None + +This cmdlet does not return any output. It suspends the specified orchestration instance. + +## NOTES + +- This cmdlet can only be used in client functions, not within orchestrator or activity functions. +- Suspended orchestrations can be resumed later using Resume-DurableOrchestration with the same instance ID. +- The suspension is asynchronous; the orchestration may take some time to actually suspend. +- Suspended orchestrations will have a status of "Suspended" when checked with Get-DurableStatus. +- Use descriptive suspension reasons to help with monitoring and maintenance. +- Suspension is useful for implementing manual approval workflows or maintenance windows. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell) diff --git a/src/Help/Wait-DurableTask.md b/src/Help/Wait-DurableTask.md new file mode 100644 index 0000000..464545f --- /dev/null +++ b/src/Help/Wait-DurableTask.md @@ -0,0 +1,146 @@ +--- +external help file: AzureFunctions.PowerShell.Durable.SDK.dll-Help.xml +Module Name: AzureFunctions.PowerShell.Durable.SDK +online version: +schema: 2.0.0 +--- + +# Wait-DurableTask + +## SYNOPSIS + +Waits for one or more durable tasks to complete and returns their results. + +## SYNTAX + +``` +Wait-DurableTask [-Any] [-NoWait] -Task [] +``` + +## DESCRIPTION + +Waits for one or more durable tasks to complete before continuing orchestration execution. +By default, waits for all specified tasks to complete. When the -Any switch is used, +waits for any one of the tasks to complete. This cmdlet is used within orchestrator +functions to coordinate multiple asynchronous operations and retrieve their results. + +## EXAMPLES + +### Example 1 + +```powershell +$task1 = Invoke-DurableActivity -FunctionName "Step1" -Input "data1" -NoWait +$task2 = Invoke-DurableActivity -FunctionName "Step2" -Input "data2" -NoWait +$completedTasks = Wait-DurableTask -Task @($task1, $task2) + +# Get the actual results from the completed tasks +$results = @() +foreach ($task in $completedTasks) { + $results += Get-DurableTaskResult -Task $task +} +Write-Host "Both tasks completed with results: $results" +``` + +This example demonstrates waiting for multiple durable activity tasks to complete. Note that Wait-DurableTask returns the task objects themselves, not the results. To get the actual activity results, you need to use Get-DurableTaskResult on each completed task. + +### Example 2 + +```powershell +$task1 = Invoke-DurableActivity -FunctionName "FastOperation" -Input $data1 -NoWait +$task2 = Invoke-DurableActivity -FunctionName "SlowOperation" -Input $data2 -NoWait +$firstCompletedTask = Wait-DurableTask -Task @($task1, $task2) -Any + +# Determine which task completed first and get its result +if ($firstCompletedTask -eq $task1) { + $activityResult = Get-DurableTaskResult -Task $firstCompletedTask + Write-Host "FastOperation completed first with result: $activityResult" +} elseif ($firstCompletedTask -eq $task2) { + $activityResult = Get-DurableTaskResult -Task $firstCompletedTask + Write-Host "SlowOperation completed first with result: $activityResult" +} else { + # This block should never be hit + Write-Host "Unexpected task completion" +} +``` + +This example demonstrates waiting for any one of the tasks to complete using the -Any parameter. The cmdlet returns the first completed task object (not the result), which you can then compare to determine which task finished first and retrieve its actual result using Get-DurableTaskResult. + +## PARAMETERS + +### -Any + +When specified, the cmdlet waits for any one of the provided tasks to complete. By default, the cmdlet waits for all tasks to complete before returning. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoWait + +When specified, the cmdlet returns immediately without waiting for the tasks to complete. This is useful for scheduling the wait operation itself as a task. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Task + +An array of durable task objects to wait for. These should be tasks returned from cmdlets like Invoke-DurableActivity, Invoke-DurableSubOrchestrator, Start-DurableTimer, or Start-DurableExternalEventListener. + +```yaml +Type: DurableTask[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +This cmdlet does not accept pipeline input. All parameters must be specified directly. + +## OUTPUTS + +### System.Object + +Returns the completed task object(s), not the task results. If waiting for a single task, returns the task object directly. If waiting for multiple tasks, returns an array of task objects in the same order as the input tasks. To get the actual results from the tasks, use Get-DurableTaskResult on the returned task objects. + +## NOTES + +- This cmdlet can only be used within orchestrator functions, not in activity functions or client functions. +- When using the -Any parameter, only the first completed task object is returned. Other tasks continue running in the background. +- Tasks passed to this cmdlet must be created with the -NoWait parameter from other durable cmdlets. +- The cmdlet is fault-tolerant and will survive orchestration replays and restarts. +- When waiting for multiple tasks without -Any, task objects are returned in the same order as the input tasks, regardless of completion order. +- This cmdlet returns task objects, not task results. Use Get-DurableTaskResult to retrieve the actual results from completed tasks. +- Use this cmdlet to implement common patterns like fan-out/fan-in, timeouts, and race conditions in orchestrations. + +## RELATED LINKS + +[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell)