Updates all state-changing commands to be silent by default (with -PassThru) (#276)

All state-changing commands (with the exception of `New-*`) are now silent by default.  Users can pass-in `-PassThru` to make them return the result that used to be returned by default.

Users can revert back to the previous behavior by leveraging the new configuration value: `DefaultPassThru`.

Resolves #217

Author: HowardWolosky

GitHubAssignees.ps1

@@ -257,6 +257,11 @@ function Add-GitHubAssignee
         NOTE: Only users with push access can add assignees to an issue.
         Assignees are silently ignored otherwise.
 
+    .PARAMETER PassThru
+        Returns the updated GitHub Issue.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -346,6 +351,8 @@ function Add-GitHubAssignee
         [Alias('UserName')]
         [string[]] $Assignee,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -397,7 +404,11 @@ function Add-GitHubAssignee
             return
         }
 
-        return (Invoke-GHRestMethod @params | Add-GitHubIssueAdditionalProperties)
+        $result = (Invoke-GHRestMethod @params | Add-GitHubIssueAdditionalProperties)
+        if (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
+        {
+            return $result
+        }
     }
 }
 

GitHubConfiguration.ps1

@@ -79,6 +79,13 @@ function Set-GitHubConfiguration
         The owner name that should be used with a command that takes OwnerName as a parameter
         when no value has been supplied.
 
+    .PARAMETER DefaultPassThru
+        Sets what the default PassThru behavior should be for commands that have a PassThru
+        switch.  By default, those commands will not return the result of the command unless
+        the user passes in -PassThru.  By setting this value to $true, those commands will
+        always behave as if -PassThru had been specified, unless you explicitly specify
+        -PassThru:$false on an individual command.
+
     .PARAMETER DefaultRepositoryName
         The owner name that should be used with a command that takes RepositoryName as a parameter
         when no value has been supplied.
@@ -196,6 +203,8 @@ function Set-GitHubConfiguration
 
         [string] $DefaultOwnerName,
 
+        [string] $DefaultPassThru,
+
         [string] $DefaultRepositoryName,
 
         [switch] $DisableLogging,
@@ -299,6 +308,7 @@ function Get-GitHubConfiguration
             'ApiHostName',
             'ApplicationInsightsKey',
             'DefaultOwnerName',
+            'DefaultPassThru',
             'DefaultRepositoryName',
             'DisableLogging',
             'DisablePiiProtection',
@@ -656,6 +666,7 @@ function Import-GitHubConfiguration
         'disableTelemetry' = $false
         'disableUpdateCheck' = $false
         'defaultOwnerName' = [String]::Empty
+        'defaultPassThru' = $false
         'defaultRepositoryName' = [String]::Empty
         'logPath' = $logPath
         'logProcessId' = $false
@@ -835,6 +846,10 @@ function Resolve-ParameterWithDefaultConfigurationValue
     if ($BoundParameters.ContainsKey($Name))
     {
         $value = $BoundParameters[$Name]
+        if ($value -is [switch])
+        {
+            $value = $value.IsPresent
+        }
     }
     else
     {

GitHubContents.ps1

@@ -255,6 +255,11 @@ filter Set-GitHubContent
         The email of the author of the commit. Defaults to the email of the authenticated user if
         not specified. If specified, AuthorName must also be specified.
 
+    .PARAMETER PassThru
+        Returns the updated GitHub Content.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -335,6 +340,8 @@ filter Set-GitHubContent
 
         [string] $AuthorEmail,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -425,7 +432,11 @@ filter Set-GitHubContent
 
     try
     {
-        return (Invoke-GHRestMethod @params | Add-GitHubContentAdditionalProperties)
+        $result = (Invoke-GHRestMethod @params | Add-GitHubContentAdditionalProperties)
+        if (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
+        {
+            return $result
+        }
     }
     catch
     {
@@ -486,7 +497,11 @@ filter Set-GitHubContent
                 'of that file.  Retrieving the SHA now.'
             Write-Log -Level Verbose -Message $message
 
-            return (Invoke-GHRestMethod @params | Add-GitHubContentAdditionalProperties)
+            $result = (Invoke-GHRestMethod @params | Add-GitHubContentAdditionalProperties)
+            if (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
+            {
+                return $result
+            }
         }
     }
 }

GitHubGistComments.ps1

@@ -315,6 +315,11 @@ filter Set-GitHubGistComment
     .PARAMETER Body
         The new text of the comment that you wish to leave on the gist.
 
+    .PARAMETER PassThru
+        Returns the updated Comment.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -330,7 +335,7 @@ filter Set-GitHubGistComment
         GitHub.GistComment
 
     .EXAMPLE
-        New-GitHubGistComment -Gist 6cad326836d38bd3a7ae -Comment 1232456 -Body 'Hello World'
+        Set-GitHubGistComment -Gist 6cad326836d38bd3a7ae -Comment 1232456 -Body 'Hello World'
 
         Updates the body of the comment with ID 1232456 octocat's "hello_world.rb" gist to be
         "Hello World".
@@ -339,6 +344,7 @@ filter Set-GitHubGistComment
         SupportsShouldProcess,
         PositionalBinding = $false)]
     [OutputType({$script:GitHubGistCommentTypeName})]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="PassThru is accessed indirectly via Resolve-ParameterWithDefaultConfigurationValue")]
     param(
         [Parameter(
             Mandatory,
@@ -362,6 +368,8 @@ filter Set-GitHubGistComment
         [ValidateNotNullOrEmpty()]
         [string] $Body,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -387,7 +395,11 @@ filter Set-GitHubGistComment
         'TelemetryProperties' = $telemetryProperties
     }
 
-    return (Invoke-GHRestMethod @params | Add-GitHubGistCommentAdditionalProperties)
+    $result = (Invoke-GHRestMethod @params | Add-GitHubGistCommentAdditionalProperties)
+    if (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
+    {
+        return $result
+    }
 }
 
 filter Add-GitHubGistCommentAdditionalProperties

GitHubGists.ps1

@@ -519,6 +519,11 @@ filter Copy-GitHubGist
     .PARAMETER Gist
         The ID of the specific gist that you wish to fork.
 
+    .PARAMETER PassThru
+        Returns the newly created gist fork.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -539,16 +544,18 @@ filter Copy-GitHubGist
         Forks octocat's "hello_world.rb" gist.
 
     .EXAMPLE
-        Fork-GitHubGist -Gist 6cad326836d38bd3a7ae
+        $result = Fork-GitHubGist -Gist 6cad326836d38bd3a7ae -PassThru
 
         Forks octocat's "hello_world.rb" gist.  This is using the alias for the command.
         The result is the same whether you use Copy-GitHubGist or Fork-GitHubGist.
+        Specifying the -PassThru switch enables you to get a reference to the newly created fork.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
         PositionalBinding = $false)]
     [OutputType({$script:GitHubGistSummaryTypeName})]
     [Alias('Fork-GitHubGist')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="PassThru is accessed indirectly via Resolve-ParameterWithDefaultConfigurationValue")]
     param(
         [Parameter(
             Mandatory,
@@ -558,6 +565,8 @@ filter Copy-GitHubGist
         [ValidateNotNullOrEmpty()]
         [string] $Gist,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -578,8 +587,13 @@ filter Copy-GitHubGist
         'TelemetryProperties' = $telemetryProperties
     }
 
-    return (Invoke-GHRestMethod @params |
+    $result = (Invoke-GHRestMethod @params |
         Add-GitHubGistAdditionalProperties -TypeName $script:GitHubGistSummaryTypeName)
+
+    if (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
+    {
+        return $result
+    }
 }
 
 filter Set-GitHubGistStar
@@ -1075,6 +1089,11 @@ filter Set-GitHubGist
     .PARAMETER Force
         If this switch is specified, you will not be prompted for confirmation of command execution.
 
+    .PARAMETER PassThru
+        Returns the updated gist.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -1119,6 +1138,7 @@ filter Set-GitHubGist
         DefaultParameterSetName='Content',
         PositionalBinding = $false)]
     [OutputType({$script:GitHubGistTypeName})]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="PassThru is accessed indirectly via Resolve-ParameterWithDefaultConfigurationValue")]
     param(
         [Parameter(
             Mandatory,
@@ -1136,6 +1156,8 @@ filter Set-GitHubGist
 
         [switch] $Force,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -1231,8 +1253,13 @@ filter Set-GitHubGist
 
     try
     {
-        return (Invoke-GHRestMethod @params |
+        $result = (Invoke-GHRestMethod @params |
             Add-GitHubGistAdditionalProperties -TypeName $script:GitHubGistTypeName)
+
+        if (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
+        {
+            return $result
+        }
     }
     catch
     {
@@ -1275,6 +1302,11 @@ function Set-GitHubGistFile
     .PARAMETER Content
         The content of a single file that should be part of the gist.
 
+    .PARAMETER PassThru
+        Returns the updated gist.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -1314,6 +1346,7 @@ function Set-GitHubGistFile
     [OutputType({$script:GitHubGistTypeName})]
     [Alias('Add-GitHubGistFile')]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="This is a helper method for Set-GitHubGist which will handle ShouldProcess.")]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="PassThru is accessed indirectly via Resolve-ParameterWithDefaultConfigurationValue")]
     param(
         [Parameter(
             Mandatory,
@@ -1345,6 +1378,8 @@ function Set-GitHubGistFile
         [ValidateNotNullOrEmpty()]
         [string] $Content,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -1383,6 +1418,7 @@ function Set-GitHubGistFile
         $params = @{
             'Gist' = $Gist
             'Update' = $files
+            'PassThru' = (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
             'AccessToken' = $AccessToken
         }
 
@@ -1412,6 +1448,11 @@ function Remove-GitHubGistFile
     .PARAMETER Force
         If this switch is specified, you will not be prompted for confirmation of command execution.
 
+    .PARAMETER PassThru
+        Returns the updated gist.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -1447,6 +1488,7 @@ function Remove-GitHubGistFile
     [OutputType({$script:GitHubGistTypeName})]
     [Alias('Delete-GitHubGistFile')]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="This is a helper method for Set-GitHubGist which will handle ShouldProcess.")]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="PassThru is accessed indirectly via Resolve-ParameterWithDefaultConfigurationValue")]
     param(
         [Parameter(
             Mandatory,
@@ -1465,6 +1507,8 @@ function Remove-GitHubGistFile
 
         [switch] $Force,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -1491,6 +1535,7 @@ function Remove-GitHubGistFile
             'Delete' = $files
             'Force' = $Force
             'Confirm' = ($Confirm -eq $true)
+            'PassThru' = (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
             'AccessToken' = $AccessToken
         }
 
@@ -1520,6 +1565,11 @@ filter Rename-GitHubGistFile
     .PARAMETER NewName
         The new name of the file for the gist.
 
+    .PARAMETER PassThru
+        Returns the updated gist.  By default, this cmdlet does not generate any output.
+        You can use "Set-GitHubConfiguration -DefaultPassThru" to control the default behavior
+        of this switch.
+
     .PARAMETER AccessToken
         If provided, this will be used as the AccessToken for authentication with the
         REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
@@ -1544,6 +1594,7 @@ filter Rename-GitHubGistFile
         PositionalBinding = $false)]
     [OutputType({$script:GitHubGistTypeName})]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="This is a helper method for Set-GitHubGist which will handle ShouldProcess.")]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="PassThru is accessed indirectly via Resolve-ParameterWithDefaultConfigurationValue")]
     param(
         [Parameter(
             Mandatory,
@@ -1565,6 +1616,8 @@ filter Rename-GitHubGistFile
         [ValidateNotNullOrEmpty()]
         [string] $NewName,
 
+        [switch] $PassThru,
+
         [string] $AccessToken
     )
 
@@ -1574,6 +1627,7 @@ filter Rename-GitHubGistFile
     $params = @{
         'Gist' = $Gist
         'Update' = @{$FileName = @{ 'fileName' = $NewName }}
+        'PassThru' = (Resolve-ParameterWithDefaultConfigurationValue -Name PassThru -ConfigValueName DefaultPassThru)
         'AccessToken' = $AccessToken
     }