diff --git a/build.ps1 b/build.ps1 index 5476717a..ef11a59e 100644 --- a/build.ps1 +++ b/build.ps1 @@ -37,6 +37,10 @@ if ($Bootstrap.IsPresent) { Write-Log -Warning "Module 'Pester' is missing. Installing 'Pester' ..." Install-Module -Name Pester -Scope CurrentUser -Force } + if (-not (Get-Module -Name platyPS -ListAvailable)) { + Write-Log -Warning "Module 'platyPS' is missing. Installing 'platyPS' ..." + Install-Module -Name platyPS -Scope CurrentUser -Force + } } # Clean step @@ -95,4 +99,18 @@ if($Test.IsPresent) { if ($LASTEXITCODE -ne 0) { throw "xunit tests failed." } Invoke-Tests -Path "$PSScriptRoot/test/Unit/Modules" -OutputFile UnitTestsResults.xml + + if (-not (Get-Module -Name platyPS -ListAvailable)) { + throw "Cannot find the 'platyPS' module. Please specify '-Bootstrap' to install build dependencies." + } + elseif (-not (Get-Command -Name git -CommandType Application)) { + throw "Cannot find 'git'. Please make sure it's in the 'PATH'." + } + + # Cmdlet help docs should be up-to-date + Update-MarkdownHelp -Path ./docs/cmdlets + $diff = git diff ./docs/cmdlets + if ($diff) { + throw "Cmdlet help docs are not up-to-date, run Update-MarkdownHelp.`n$diff`n" + } } diff --git a/docs/cmdlets/Get-OutputBinding.md b/docs/cmdlets/Get-OutputBinding.md new file mode 100644 index 00000000..6433549c --- /dev/null +++ b/docs/cmdlets/Get-OutputBinding.md @@ -0,0 +1,88 @@ +--- +external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml +Module Name: Microsoft.Azure.Functions.PowerShellWorker +online version: +schema: 2.0.0 +--- + +# Get-OutputBinding + +## SYNOPSIS +Gets the hashtable of the output bindings set so far. + +## SYNTAX + +``` +Get-OutputBinding [[-Name] ] [-Purge] [] +``` + +## DESCRIPTION +Gets the hashtable of the output bindings set so far. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-OutputBinding +``` + +Gets the hashtable of all the output bindings set so far. + +### EXAMPLE 2 +``` +Get-OutputBinding -Name res +``` + +Gets the hashtable of specific output binding. + +### EXAMPLE 3 +``` +Get-OutputBinding -Name r* +``` + +Gets the hashtable of output bindings that match the wildcard. + +## PARAMETERS + +### -Name +The name of the output binding you want to get. +Supports wildcards. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: * +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Purge +Clear all stored output binding values. + +```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, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### The hashtable of binding names to their respective value. +## NOTES + +## RELATED LINKS diff --git a/docs/cmdlets/Push-OutputBinding.md b/docs/cmdlets/Push-OutputBinding.md new file mode 100644 index 00000000..297247c9 --- /dev/null +++ b/docs/cmdlets/Push-OutputBinding.md @@ -0,0 +1,149 @@ +--- +external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml +Module Name: Microsoft.Azure.Functions.PowerShellWorker +online version: +schema: 2.0.0 +--- + +# Push-OutputBinding + +## SYNOPSIS +Sets the value for the specified output binding. + +## SYNTAX + +``` +Push-OutputBinding [-Name] [-Value] [-Clobber] [] +``` + +## DESCRIPTION +When running in the Functions runtime, this cmdlet is aware of the output bindings +defined for the function that is invoking this cmdlet. +Hence, it's able to decide +whether an output binding accepts singleton value only or a collection of values. + +For example, the HTTP output binding only accepts one response object, while the +queue output binding can accept one or multiple queue messages. + +With this knowledge, the 'Push-OutputBinding' cmdlet acts differently based on the +value specified for '-Name': + +- If the specified name cannot be resolved to a valid output binding, then an error + will be thrown; + +- If the output binding corresponding to that name accepts a collection of values, + then it's allowed to call 'Push-OutputBinding' with the same name repeatedly in + the function script to push multiple values; + +- If the output binding corresponding to that name only accepts a singleton value, + then the second time calling 'Push-OutputBinding' with that name will result in + an error, with detailed message about why it failed. + +## EXAMPLES + +### EXAMPLE 1 +``` +Push-OutputBinding -Name response -Value "output #1" +``` + +The output binding of "response" will have the value of "output #1" + +### EXAMPLE 2 +``` +Push-OutputBinding -Name response -Value "output #2" +``` + +The output binding is 'http', which accepts a singleton value only. +So an error will be thrown from this second run. + +### EXAMPLE 3 +``` +Push-OutputBinding -Name response -Value "output #3" -Clobber +``` + +The output binding is 'http', which accepts a singleton value only. +But you can use '-Clobber' to override the old value. +The output binding of "response" will now have the value of "output #3" + +### EXAMPLE 4 +``` +Push-OutputBinding -Name outQueue -Value "output #1" +``` + +The output binding of "outQueue" will have the value of "output #1" + +### EXAMPLE 5 +``` +Push-OutputBinding -Name outQueue -Value "output #2" +``` + +The output binding is 'queue', which accepts multiple output values. +The output binding of "outQueue" will now have a list with 2 items: "output #1", "output #2" + +### EXAMPLE 6 +``` +Push-OutputBinding -Name outQueue -Value @("output #3", "output #4") +``` + +When the value is a collection, the collection will be unrolled and elements of the collection +will be added to the list. +The output binding of "outQueue" will now have a list with 4 items: +"output #1", "output #2", "output #3", "output #4". + +## PARAMETERS + +### -Name +The name of the output binding you want to set. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Value +The value of the output binding you want to set. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Clobber +(Optional) If specified, will force the value to be set for a specified output binding. + +```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, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/docs/cmdlets/Trace-PipelineObject.md b/docs/cmdlets/Trace-PipelineObject.md new file mode 100644 index 00000000..a07ee2c5 --- /dev/null +++ b/docs/cmdlets/Trace-PipelineObject.md @@ -0,0 +1,58 @@ +--- +external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml +Module Name: Microsoft.Azure.Functions.PowerShellWorker +online version: +schema: 2.0.0 +--- + +# Trace-PipelineObject + +## SYNOPSIS +Writes the formatted output of the pipeline object to the information stream before passing the object down to the pipeline. + +## SYNTAX + +``` +Trace-PipelineObject [-InputObject] [] +``` + +## DESCRIPTION +INTERNAL POWERSHELL WORKER USE ONLY. +Writes the formatted output of the pipeline object to the information stream before passing the object down to the pipeline. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> {{ Add example code here }} +``` + +{{ Add example description here }} + +## PARAMETERS + +### -InputObject +The object from pipeline. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +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, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/src/Modules/Microsoft.Azure.Functions.PowerShellWorker/Microsoft.Azure.Functions.PowerShellWorker.psm1 b/src/Modules/Microsoft.Azure.Functions.PowerShellWorker/Microsoft.Azure.Functions.PowerShellWorker.psm1 index 44d52e09..9f56538f 100644 --- a/src/Modules/Microsoft.Azure.Functions.PowerShellWorker/Microsoft.Azure.Functions.PowerShellWorker.psm1 +++ b/src/Modules/Microsoft.Azure.Functions.PowerShellWorker/Microsoft.Azure.Functions.PowerShellWorker.psm1 @@ -40,6 +40,8 @@ enum DataCollectingBehavior { Gets the hashtable of output bindings that match the wildcard. .PARAMETER Name The name of the output binding you want to get. Supports wildcards. +.PARAMETER Purge + Clear all stored output binding values. .OUTPUTS The hashtable of binding names to their respective value. #> @@ -202,17 +204,55 @@ function Merge-Collection .SYNOPSIS Sets the value for the specified output binding. .DESCRIPTION - Sets the value for the specified output binding. + When running in the Functions runtime, this cmdlet is aware of the output bindings + defined for the function that is invoking this cmdlet. Hence, it's able to decide + whether an output binding accepts singleton value only or a collection of values. + + For example, the HTTP output binding only accepts one response object, while the + queue output binding can accept one or multiple queue messages. + + With this knowledge, the 'Push-OutputBinding' cmdlet acts differently based on the + value specified for '-Name': + + - If the specified name cannot be resolved to a valid output binding, then an error + will be thrown; + + - If the output binding corresponding to that name accepts a collection of values, + then it's allowed to call 'Push-OutputBinding' with the same name repeatedly in + the function script to push multiple values; + + - If the output binding corresponding to that name only accepts a singleton value, + then the second time calling 'Push-OutputBinding' with that name will result in + an error, with detailed message about why it failed. .EXAMPLE - PS > Push-OutputBinding -Name res -Value "my output" - The output binding of "res" will have the value of "my output" + PS > Push-OutputBinding -Name response -Value "output #1" + The output binding of "response" will have the value of "output #1" +.EXAMPLE + PS > Push-OutputBinding -Name response -Value "output #2" + The output binding is 'http', which accepts a singleton value only. + So an error will be thrown from this second run. +.EXAMPLE + PS > Push-OutputBinding -Name response -Value "output #3" -Clobber + The output binding is 'http', which accepts a singleton value only. + But you can use '-Clobber' to override the old value. + The output binding of "response" will now have the value of "output #3" +.EXAMPLE + PS > Push-OutputBinding -Name outQueue -Value "output #1" + The output binding of "outQueue" will have the value of "output #1" +.EXAMPLE + PS > Push-OutputBinding -Name outQueue -Value "output #2" + The output binding is 'queue', which accepts multiple output values. + The output binding of "outQueue" will now have a list with 2 items: "output #1", "output #2" +.EXAMPLE + PS > Push-OutputBinding -Name outQueue -Value @("output #3", "output #4") + When the value is a collection, the collection will be unrolled and elements of the collection + will be added to the list. The output binding of "outQueue" will now have a list with 4 items: + "output #1", "output #2", "output #3", "output #4". .PARAMETER Name The name of the output binding you want to set. .PARAMETER Value The value of the output binding you want to set. -.PARAMETER InputObject - The hashtable that contains the output binding names to their respective value. -.PARAMETER Force +.PARAMETER Clobber (Optional) If specified, will force the value to be set for a specified output binding. #> function Push-OutputBinding