Skip to content

Commit 1df2c78

Browse files
AnatoliBAnatoliB
authored
Add help for all Durable Functions cmdlets (#96)
Resolves #92 **Important note to reviewers**: The following content was auto-generated by platyPS based on the actual module content: - the cmdlet names; - the `SYNTAX` sections; - the parameter names; - the detailed technical information on parameters in the yaml blocks (e.g. type, default value, optional vs. mandatory, pipeline input, etc.); - the `CommonParameters` sections. There is no need to carefully review each and every piece of this data, as platyPS is doing a good job. Just a quick sanity check glance is enough.
1 parent ec6c22a commit 1df2c78

20 files changed

+2183
-34
lines changed

‎build.ps1

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,35 @@ Get-ChildItem -Path (Join-Path "$shimPath" "$publishPathSuffix") |
7676
Write-Log "Copying PowerShell module and manifest from the Durable SDK source code into $outputPath" "Gray"
7777
Copy-Item -Path $powerShellModulePath -Destination $outputPath
7878
Copy-Item -Path $manifestPath -Destination $outputPath
79+
80+
#region GENERATE EXTERNAL HELP ===================================================================
81+
Write-Log "Generating external help files (MAML) from markdown documentation..." "Gray"
82+
83+
# Install PlatyPS module if not already available
84+
if (-not (Get-Module -ListAvailable -Name PlatyPS)) {
85+
Write-Log "Installing PlatyPS module..." "Cyan"
86+
Install-Module -Name PlatyPS -Force -Scope CurrentUser
87+
}
88+
89+
# Import PlatyPS module
90+
Import-Module PlatyPS -Force
91+
92+
# Define paths for help generation
93+
$docsPath = "$PSScriptRoot/src/Help"
94+
$helpPath = "$outputPath/en-US"
95+
96+
# Create the help directory if it doesn't exist
97+
if (-not (Test-Path $helpPath)) {
98+
Write-Log "Creating help directory at $helpPath" "Cyan"
99+
New-Item -Path $helpPath -ItemType Directory -Force
100+
}
101+
102+
# Generate external help files from markdown
103+
Write-Log "Converting markdown files to MAML help files..." "Gray"
104+
New-ExternalHelp -Path $docsPath -OutputPath $helpPath -Force
105+
Write-Log "External help files generated successfully in $helpPath" "Green"
106+
#endregion
107+
79108
Write-Log "Build succeeded!"
80109
#endregion
81110

‎src/AzureFunctions.PowerShell.Durable.SDK.psm1

Lines changed: 0 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -69,21 +69,6 @@ function Get-DurableStatus {
6969
Invoke-RestMethod -Uri $requestUrl
7070
}
7171

72-
<#
73-
.SYNOPSIS
74-
Start an orchestration Azure Function.
75-
.DESCRIPTION
76-
Start an orchestration Azure Function with the given function name and input value.
77-
.EXAMPLE
78-
PS > Start-DurableOrchestration -DurableClient Starter -FunctionName OrchestratorFunction -InputObject "input value for the orchestration function"
79-
Return the instance id of the new orchestration.
80-
.PARAMETER FunctionName
81-
The name of the orchestration Azure Function you want to start.
82-
.PARAMETER InputObject
83-
The input value that will be passed to the orchestration Azure Function.
84-
.PARAMETER DurableClient
85-
The orchestration client object.
86-
#>
8772
function Start-DurableOrchestration {
8873
[CmdletBinding()]
8974
param(
@@ -284,25 +269,6 @@ function New-DurableOrchestrationCheckStatusResponse {
284269
}
285270
}
286271

287-
<#
288-
.SYNOPSIS
289-
Send an external event to an orchestration instance.
290-
.DESCRIPTION
291-
Send an external event with the given event name, and event data to an orchestration instance with the given instance ID.
292-
.EXAMPLE
293-
PS > Send-DurableExternalEvent -InstanceId "example-instance-id" -EventName "ExampleExternalEvent" -EventData "data for the external event"
294-
Return the instance id of the new orchestration.
295-
.PARAMETER InstanceId
296-
The ID of the orchestration instance that will handle the external event.
297-
.PARAMETER EventName
298-
The name of the external event.
299-
.PARAMETER EventData
300-
The JSON-serializable data associated with the external event.
301-
.PARAMETER TaskHubName
302-
The TaskHubName of the orchestration instance that will handle the external event.
303-
.PARAMETER ConnectionName
304-
The name of the connection string associated with TaskHubName
305-
#>
306272
function Send-DurableExternalEvent {
307273
[CmdletBinding()]
308274
param(

‎src/Help/AzureFunctions.PowerShell.Durable.SDK.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
Module Name: AzureFunctions.PowerShell.Durable.SDK
3+
Module Guid: 841fad61-94f5-4330-89be-613d54165289
4+
Download Help Link: https://github.com/Azure/azure-functions-durable-powershell
5+
Help Version: 1.0.0.0
6+
Locale: en-US
7+
---
8+
9+
# AzureFunctions.PowerShell.Durable.SDK Module
10+
11+
## Description
12+
13+
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.
14+
15+
## AzureFunctions.PowerShell.Durable.SDK Cmdlets
16+
17+
### [Get-DurableStatus](Get-DurableStatus.md)
18+
19+
Gets the status of a durable orchestration instance, including execution history, input data, and output data.
20+
21+
### [Get-DurableTaskResult](Get-DurableTaskResult.md)
22+
23+
Gets the result of a completed durable task, such as an activity function or sub-orchestrator.
24+
25+
### [Invoke-DurableActivity](Invoke-DurableActivity.md)
26+
27+
Invokes an activity function from within an orchestrator function.
28+
29+
### [Invoke-DurableSubOrchestrator](Invoke-DurableSubOrchestrator.md)
30+
31+
Invokes a sub-orchestrator function from within a parent orchestrator function.
32+
33+
### [New-DurableOrchestrationCheckStatusResponse](New-DurableOrchestrationCheckStatusResponse.md)
34+
35+
Creates an HTTP response for orchestration status check endpoints with status polling URLs.
36+
37+
### [New-DurableRetryPolicy](New-DurableRetryPolicy.md)
38+
39+
Creates a retry policy for durable activity functions and sub-orchestrators.
40+
41+
### [Resume-DurableOrchestration](Resume-DurableOrchestration.md)
42+
43+
Resumes a suspended durable orchestration instance.
44+
45+
### [Send-DurableExternalEvent](Send-DurableExternalEvent.md)
46+
47+
Sends an external event to a running durable orchestration instance.
48+
49+
### [Set-DurableCustomStatus](Set-DurableCustomStatus.md)
50+
51+
Sets custom status information for a durable orchestration instance.
52+
53+
### [Set-FunctionInvocationContext](Set-FunctionInvocationContext.md)
54+
55+
Sets the function invocation context for durable function operations.
56+
57+
### [Start-DurableExternalEventListener](Start-DurableExternalEventListener.md)
58+
59+
Starts listening for an external event within an orchestrator function.
60+
61+
### [Start-DurableOrchestration](Start-DurableOrchestration.md)
62+
63+
Starts a new durable orchestration instance with the specified function name and input.
64+
65+
### [Start-DurableTimer](Start-DurableTimer.md)
66+
67+
Starts a durable timer that fires after a specified delay or at a specific time.
68+
69+
### [Stop-DurableOrchestration](Stop-DurableOrchestration.md)
70+
71+
Terminates a running durable orchestration instance.
72+
73+
### [Stop-DurableTimerTask](Stop-DurableTimerTask.md)
74+
75+
Stops a running durable timer task.
76+
77+
### [Suspend-DurableOrchestration](Suspend-DurableOrchestration.md)
78+
79+
Suspends a running durable orchestration instance.
80+
81+
### [Wait-DurableTask](Wait-DurableTask.md)
82+
83+
Waits for the completion of one or more durable tasks within an orchestrator function.

‎src/Help/Get-DurableStatus.md

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
external help file: AzureFunctions.PowerShell.Durable.SDK-help.xml
3+
Module Name: AzureFunctions.PowerShell.Durable.SDK
4+
online version:
5+
schema: 2.0.0
6+
---
7+
8+
# Get-DurableStatus
9+
10+
## SYNOPSIS
11+
12+
Get the status of a durable orchestration instance.
13+
14+
## SYNTAX
15+
16+
```
17+
Get-DurableStatus [-InstanceId] <String> [-DurableClient <Object>] [-ShowHistory] [-ShowHistoryOutput] [-ShowInput] [<CommonParameters>]
18+
```
19+
20+
## DESCRIPTION
21+
22+
Get the status of a durable orchestration instance with the given instance ID.
23+
Optionally includes execution history, history output, and input data.
24+
25+
## EXAMPLES
26+
27+
### Example 1
28+
29+
```powershell
30+
Get-DurableStatus -InstanceId "example-instance-id"
31+
```
32+
33+
Returns the basic status of the orchestration instance.
34+
35+
### Example 2
36+
37+
```powershell
38+
Get-DurableStatus -InstanceId "example-instance-id" -ShowHistory -ShowHistoryOutput
39+
```
40+
41+
Returns the status with detailed execution history and output.
42+
43+
## PARAMETERS
44+
45+
### -InstanceId
46+
47+
The ID of the orchestration instance to get the status for.
48+
49+
```yaml
50+
Type: String
51+
Parameter Sets: (All)
52+
Aliases:
53+
54+
Required: True
55+
Position: 1
56+
Default value: None
57+
Accept pipeline input: True (ByPropertyName)
58+
Accept wildcard characters: False
59+
```
60+
61+
### -DurableClient
62+
63+
The durable client object.
64+
If not provided, it will be retrieved from module private data.
65+
66+
```yaml
67+
Type: Object
68+
Parameter Sets: (All)
69+
Aliases:
70+
71+
Required: False
72+
Position: Named
73+
Default value: None
74+
Accept pipeline input: True (ByPropertyName)
75+
Accept wildcard characters: False
76+
```
77+
78+
### -ShowHistory
79+
80+
When present, includes the execution history in the response.
81+
82+
```yaml
83+
Type: SwitchParameter
84+
Parameter Sets: (All)
85+
Aliases:
86+
87+
Required: False
88+
Position: Named
89+
Default value: False
90+
Accept pipeline input: False
91+
Accept wildcard characters: False
92+
```
93+
94+
### -ShowHistoryOutput
95+
96+
When present, includes the output of each step in the execution history.
97+
98+
```yaml
99+
Type: SwitchParameter
100+
Parameter Sets: (All)
101+
Aliases:
102+
103+
Required: False
104+
Position: Named
105+
Default value: False
106+
Accept pipeline input: False
107+
Accept wildcard characters: False
108+
```
109+
110+
### -ShowInput
111+
112+
When present, includes the input data that was provided to the orchestration instance.
113+
114+
```yaml
115+
Type: SwitchParameter
116+
Parameter Sets: (All)
117+
Aliases:
118+
119+
Required: False
120+
Position: Named
121+
Default value: False
122+
Accept pipeline input: False
123+
Accept wildcard characters: False
124+
```
125+
126+
### CommonParameters
127+
128+
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).
129+
130+
## INPUTS
131+
132+
### System.String
133+
134+
You can pipe instance ID strings to this cmdlet to get the status of multiple orchestration instances.
135+
136+
## OUTPUTS
137+
138+
### System.Object
139+
140+
Returns a status object containing information about the durable orchestration instance, including:
141+
142+
- InstanceId: The unique identifier of the orchestration instance
143+
- RuntimeStatus: The current runtime status (Running, Completed, Failed, etc.)
144+
- Input: The input data provided to the orchestration (if -ShowInput is specified)
145+
- Output: The output of the orchestration (if completed)
146+
- CreatedTime: When the orchestration was created
147+
- LastUpdatedTime: When the orchestration was last updated
148+
- History: Execution history (if -ShowHistory is specified)
149+
150+
## NOTES
151+
152+
- This cmdlet is typically used in HTTP trigger functions or other client functions to check orchestration progress.
153+
- The InstanceId must be from an existing orchestration; invalid IDs will result in a null response.
154+
- Use -ShowHistory to get detailed execution steps, which is useful for debugging orchestration behavior.
155+
- The -ShowHistoryOutput parameter can produce large responses; use carefully in production environments.
156+
- Status information includes runtime state, input/output data, creation time, and last update time.
157+
- Orchestration status is eventually consistent and may take a moment to reflect the latest state after operations.
158+
159+
## RELATED LINKS
160+
161+
[Durable Functions for PowerShell](https://github.com/Azure/azure-functions-durable-powershell)

0 commit comments

Comments
 (0)