Skip to content

Commit 7ac8a34

Browse files
daxian-dbwdaxian-dbw
authored
Update the help content for 'Push-OutputBinding' (#179)
1 parent 1844e1e commit 7ac8a34

File tree

5 files changed

+359
-6
lines changed

5 files changed

+359
-6
lines changed

‎build.ps1‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ if ($Bootstrap.IsPresent) {
3737
Write-Log -Warning "Module 'Pester' is missing. Installing 'Pester' ..."
3838
Install-Module -Name Pester -Scope CurrentUser -Force
3939
}
40+
if (-not (Get-Module -Name platyPS -ListAvailable)) {
41+
Write-Log -Warning "Module 'platyPS' is missing. Installing 'platyPS' ..."
42+
Install-Module -Name platyPS -Scope CurrentUser -Force
43+
}
4044
}
4145

4246
# Clean step
@@ -95,4 +99,18 @@ if($Test.IsPresent) {
9599
if ($LASTEXITCODE -ne 0) { throw "xunit tests failed." }
96100

97101
Invoke-Tests -Path "$PSScriptRoot/test/Unit/Modules" -OutputFile UnitTestsResults.xml
102+
103+
if (-not (Get-Module -Name platyPS -ListAvailable)) {
104+
throw "Cannot find the 'platyPS' module. Please specify '-Bootstrap' to install build dependencies."
105+
}
106+
elseif (-not (Get-Command -Name git -CommandType Application)) {
107+
throw "Cannot find 'git'. Please make sure it's in the 'PATH'."
108+
}
109+
110+
# Cmdlet help docs should be up-to-date
111+
Update-MarkdownHelp -Path ./docs/cmdlets
112+
$diff = git diff ./docs/cmdlets
113+
if ($diff) {
114+
throw "Cmdlet help docs are not up-to-date, run Update-MarkdownHelp.`n$diff`n"
115+
}
98116
}

‎docs/cmdlets/Get-OutputBinding.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml
3+
Module Name: Microsoft.Azure.Functions.PowerShellWorker
4+
online version:
5+
schema: 2.0.0
6+
---
7+
8+
# Get-OutputBinding
9+
10+
## SYNOPSIS
11+
Gets the hashtable of the output bindings set so far.
12+
13+
## SYNTAX
14+
15+
```
16+
Get-OutputBinding [[-Name] <String[]>] [-Purge] [<CommonParameters>]
17+
```
18+
19+
## DESCRIPTION
20+
Gets the hashtable of the output bindings set so far.
21+
22+
## EXAMPLES
23+
24+
### EXAMPLE 1
25+
```
26+
Get-OutputBinding
27+
```
28+
29+
Gets the hashtable of all the output bindings set so far.
30+
31+
### EXAMPLE 2
32+
```
33+
Get-OutputBinding -Name res
34+
```
35+
36+
Gets the hashtable of specific output binding.
37+
38+
### EXAMPLE 3
39+
```
40+
Get-OutputBinding -Name r*
41+
```
42+
43+
Gets the hashtable of output bindings that match the wildcard.
44+
45+
## PARAMETERS
46+
47+
### -Name
48+
The name of the output binding you want to get.
49+
Supports wildcards.
50+
51+
```yaml
52+
Type: String[]
53+
Parameter Sets: (All)
54+
Aliases:
55+
56+
Required: False
57+
Position: 1
58+
Default value: *
59+
Accept pipeline input: True (ByPropertyName, ByValue)
60+
Accept wildcard characters: False
61+
```
62+
63+
### -Purge
64+
Clear all stored output binding values.
65+
66+
```yaml
67+
Type: SwitchParameter
68+
Parameter Sets: (All)
69+
Aliases:
70+
71+
Required: False
72+
Position: Named
73+
Default value: False
74+
Accept pipeline input: False
75+
Accept wildcard characters: False
76+
```
77+
78+
### CommonParameters
79+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
80+
81+
## INPUTS
82+
83+
## OUTPUTS
84+
85+
### The hashtable of binding names to their respective value.
86+
## NOTES
87+
88+
## RELATED LINKS

‎docs/cmdlets/Push-OutputBinding.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml
3+
Module Name: Microsoft.Azure.Functions.PowerShellWorker
4+
online version:
5+
schema: 2.0.0
6+
---
7+
8+
# Push-OutputBinding
9+
10+
## SYNOPSIS
11+
Sets the value for the specified output binding.
12+
13+
## SYNTAX
14+
15+
```
16+
Push-OutputBinding [-Name] <String> [-Value] <Object> [-Clobber] [<CommonParameters>]
17+
```
18+
19+
## DESCRIPTION
20+
When running in the Functions runtime, this cmdlet is aware of the output bindings
21+
defined for the function that is invoking this cmdlet.
22+
Hence, it's able to decide
23+
whether an output binding accepts singleton value only or a collection of values.
24+
25+
For example, the HTTP output binding only accepts one response object, while the
26+
queue output binding can accept one or multiple queue messages.
27+
28+
With this knowledge, the 'Push-OutputBinding' cmdlet acts differently based on the
29+
value specified for '-Name':
30+
31+
- If the specified name cannot be resolved to a valid output binding, then an error
32+
will be thrown;
33+
34+
- If the output binding corresponding to that name accepts a collection of values,
35+
then it's allowed to call 'Push-OutputBinding' with the same name repeatedly in
36+
the function script to push multiple values;
37+
38+
- If the output binding corresponding to that name only accepts a singleton value,
39+
then the second time calling 'Push-OutputBinding' with that name will result in
40+
an error, with detailed message about why it failed.
41+
42+
## EXAMPLES
43+
44+
### EXAMPLE 1
45+
```
46+
Push-OutputBinding -Name response -Value "output #1"
47+
```
48+
49+
The output binding of "response" will have the value of "output #1"
50+
51+
### EXAMPLE 2
52+
```
53+
Push-OutputBinding -Name response -Value "output #2"
54+
```
55+
56+
The output binding is 'http', which accepts a singleton value only.
57+
So an error will be thrown from this second run.
58+
59+
### EXAMPLE 3
60+
```
61+
Push-OutputBinding -Name response -Value "output #3" -Clobber
62+
```
63+
64+
The output binding is 'http', which accepts a singleton value only.
65+
But you can use '-Clobber' to override the old value.
66+
The output binding of "response" will now have the value of "output #3"
67+
68+
### EXAMPLE 4
69+
```
70+
Push-OutputBinding -Name outQueue -Value "output #1"
71+
```
72+
73+
The output binding of "outQueue" will have the value of "output #1"
74+
75+
### EXAMPLE 5
76+
```
77+
Push-OutputBinding -Name outQueue -Value "output #2"
78+
```
79+
80+
The output binding is 'queue', which accepts multiple output values.
81+
The output binding of "outQueue" will now have a list with 2 items: "output #1", "output #2"
82+
83+
### EXAMPLE 6
84+
```
85+
Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")
86+
```
87+
88+
When the value is a collection, the collection will be unrolled and elements of the collection
89+
will be added to the list.
90+
The output binding of "outQueue" will now have a list with 4 items:
91+
"output #1", "output #2", "output #3", "output #4".
92+
93+
## PARAMETERS
94+
95+
### -Name
96+
The name of the output binding you want to set.
97+
98+
```yaml
99+
Type: String
100+
Parameter Sets: (All)
101+
Aliases:
102+
103+
Required: True
104+
Position: 1
105+
Default value: None
106+
Accept pipeline input: False
107+
Accept wildcard characters: False
108+
```
109+
110+
### -Value
111+
The value of the output binding you want to set.
112+
113+
```yaml
114+
Type: Object
115+
Parameter Sets: (All)
116+
Aliases:
117+
118+
Required: True
119+
Position: 2
120+
Default value: None
121+
Accept pipeline input: True (ByValue)
122+
Accept wildcard characters: False
123+
```
124+
125+
### -Clobber
126+
(Optional) If specified, will force the value to be set for a specified output binding.
127+
128+
```yaml
129+
Type: SwitchParameter
130+
Parameter Sets: (All)
131+
Aliases:
132+
133+
Required: False
134+
Position: Named
135+
Default value: False
136+
Accept pipeline input: False
137+
Accept wildcard characters: False
138+
```
139+
140+
### CommonParameters
141+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
142+
143+
## INPUTS
144+
145+
## OUTPUTS
146+
147+
## NOTES
148+
149+
## RELATED LINKS

‎docs/cmdlets/Trace-PipelineObject.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml
3+
Module Name: Microsoft.Azure.Functions.PowerShellWorker
4+
online version:
5+
schema: 2.0.0
6+
---
7+
8+
# Trace-PipelineObject
9+
10+
## SYNOPSIS
11+
Writes the formatted output of the pipeline object to the information stream before passing the object down to the pipeline.
12+
13+
## SYNTAX
14+
15+
```
16+
Trace-PipelineObject [-InputObject] <Object> [<CommonParameters>]
17+
```
18+
19+
## DESCRIPTION
20+
INTERNAL POWERSHELL WORKER USE ONLY.
21+
Writes the formatted output of the pipeline object to the information stream before passing the object down to the pipeline.
22+
23+
## EXAMPLES
24+
25+
### Example 1
26+
```powershell
27+
PS C:\> {{ Add example code here }}
28+
```
29+
30+
{{ Add example description here }}
31+
32+
## PARAMETERS
33+
34+
### -InputObject
35+
The object from pipeline.
36+
37+
```yaml
38+
Type: Object
39+
Parameter Sets: (All)
40+
Aliases:
41+
42+
Required: True
43+
Position: 1
44+
Default value: None
45+
Accept pipeline input: True (ByValue)
46+
Accept wildcard characters: False
47+
```
48+
49+
### CommonParameters
50+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
51+
52+
## INPUTS
53+
54+
## OUTPUTS
55+
56+
## NOTES
57+
58+
## RELATED LINKS

‎src/Modules/Microsoft.Azure.Functions.PowerShellWorker/Microsoft.Azure.Functions.PowerShellWorker.psm1‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ enum DataCollectingBehavior {
4040
Gets the hashtable of output bindings that match the wildcard.
4141
.PARAMETER Name
4242
The name of the output binding you want to get. Supports wildcards.
43+
.PARAMETER Purge
44+
Clear all stored output binding values.
4345
.OUTPUTS
4446
The hashtable of binding names to their respective value.
4547
#>
@@ -202,17 +204,55 @@ function Merge-Collection
202204
.SYNOPSIS
203205
Sets the value for the specified output binding.
204206
.DESCRIPTION
205-
Sets the value for the specified output binding.
207+
When running in the Functions runtime, this cmdlet is aware of the output bindings
208+
defined for the function that is invoking this cmdlet. Hence, it's able to decide
209+
whether an output binding accepts singleton value only or a collection of values.
210+
211+
For example, the HTTP output binding only accepts one response object, while the
212+
queue output binding can accept one or multiple queue messages.
213+
214+
With this knowledge, the 'Push-OutputBinding' cmdlet acts differently based on the
215+
value specified for '-Name':
216+
217+
- If the specified name cannot be resolved to a valid output binding, then an error
218+
will be thrown;
219+
220+
- If the output binding corresponding to that name accepts a collection of values,
221+
then it's allowed to call 'Push-OutputBinding' with the same name repeatedly in
222+
the function script to push multiple values;
223+
224+
- If the output binding corresponding to that name only accepts a singleton value,
225+
then the second time calling 'Push-OutputBinding' with that name will result in
226+
an error, with detailed message about why it failed.
206227
.EXAMPLE
207-
PS > Push-OutputBinding -Name res -Value "my output"
208-
The output binding of "res" will have the value of "my output"
228+
PS > Push-OutputBinding -Name response -Value "output #1"
229+
The output binding of "response" will have the value of "output #1"
230+
.EXAMPLE
231+
PS > Push-OutputBinding -Name response -Value "output #2"
232+
The output binding is 'http', which accepts a singleton value only.
233+
So an error will be thrown from this second run.
234+
.EXAMPLE
235+
PS > Push-OutputBinding -Name response -Value "output #3" -Clobber
236+
The output binding is 'http', which accepts a singleton value only.
237+
But you can use '-Clobber' to override the old value.
238+
The output binding of "response" will now have the value of "output #3"
239+
.EXAMPLE
240+
PS > Push-OutputBinding -Name outQueue -Value "output #1"
241+
The output binding of "outQueue" will have the value of "output #1"
242+
.EXAMPLE
243+
PS > Push-OutputBinding -Name outQueue -Value "output #2"
244+
The output binding is 'queue', which accepts multiple output values.
245+
The output binding of "outQueue" will now have a list with 2 items: "output #1", "output #2"
246+
.EXAMPLE
247+
PS > Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")
248+
When the value is a collection, the collection will be unrolled and elements of the collection
249+
will be added to the list. The output binding of "outQueue" will now have a list with 4 items:
250+
"output #1", "output #2", "output #3", "output #4".
209251
.PARAMETER Name
210252
The name of the output binding you want to set.
211253
.PARAMETER Value
212254
The value of the output binding you want to set.
213-
.PARAMETER InputObject
214-
The hashtable that contains the output binding names to their respective value.
215-
.PARAMETER Force
255+
.PARAMETER Clobber
216256
(Optional) If specified, will force the value to be set for a specified output binding.
217257
#>
218258
function Push-OutputBinding

0 commit comments

Comments
 (0)