Start-SubmissionMonitor should return the final submission retrieved

We now return the final submission object that was retrieved as part
of the loop if the `-PassThru` switch is provided.

Resolves Issue #43: Start-SubmissionMonitor should allow the shell to know the result

Documentation/USAGE.md

@@ -439,6 +439,11 @@ Multiple email addresses are separated by a comma
 
     Start-SubmissionMonitor -AppId <appId> -SubmissionId <submissionId> -EmailNotifyTo <emailAddress1>,<emailAddress2>
 
+> By default, `Start-SubmissionMonitor` does not return any result.
+> You can provide the `-PassThru` switch if you'd like it to return back the final submission object
+> that caused it to end its monitoring loop.  You can then capture that result and do additional
+> processing on it if so desired.
+
 ### Status Progression
 
  The following explains the common progression of a submission by status:

StoreBroker/StoreBroker.psd1

@@ -6,7 +6,7 @@
     CompanyName = 'Microsoft Corporation'
     Copyright = 'Copyright (C) Microsoft Corporation.  All rights reserved.'
 
-    ModuleVersion = '1.8.0'
+    ModuleVersion = '1.8.1'
     Description = 'Provides command-line access to the Windows Store Submission REST API.'
 
     RootModule = 'StoreIngestionApi'

StoreBroker/StoreIngestionApi.psm1

@@ -1128,6 +1128,16 @@ function Start-SubmissionMonitor
         with no commandline status update.  When not specified, those commands run in
         the background, enabling the command prompt to provide status information.
 
+    .PARAMETER PassThru
+        Returns the final submission object that was retrieved when checking submission
+        status.  By default, this function does not generate any output.
+
+    .OUTPUTS
+       None or PSCustomObject
+       By default, this does not generate any output. If you use the PassThru parameter,
+       it generates a PSCustomObject object that represents the last retrieved submission
+       which can be inspected for submission status.
+
     .EXAMPLE
         Start-SubmissionMonitor 0ABCDEF12345 1234567890123456789
         Checks that submission every 60 seconds until the submission enters a Failed state
@@ -1178,7 +1188,9 @@ function Start-SubmissionMonitor
             Position=0)]
         [string] $IapId,
 
-        [switch] $NoStatus
+        [switch] $NoStatus,
+
+        [switch] $PassThru
     )
 
     Write-Log "Executing: $($MyInvocation.Line)" -Level Verbose 
@@ -1224,6 +1236,8 @@ function Start-SubmissionMonitor
         }
     }
 
+    $submission = $null
+
     # We can safely assume this is being used on a recently committed submission.
     # If it isn't we'll report that to the user and update this value during the first
     # run through our loop.
@@ -1371,6 +1385,11 @@ function Start-SubmissionMonitor
             Start-Sleep -Seconds $secondsBetweenChecks
         }
     }
+
+    if ($PassThru)
+    {
+        return $submission
+    }
 }
 
 function Open-DevPortal

StoreBroker/StoreIngestionFlightingApi.ps1

@@ -1926,6 +1926,16 @@ function Start-ApplicationFlightSubmissionMonitor
         with no commandline status update.  When not specified, those commands run in
         the background, enabling the command prompt to provide status information.
 
+    .PARAMETER PassThru
+        Returns the final submission object that was retrieved when checking submission
+        status.  By default, this function does not generate any output.
+
+    .OUTPUTS
+       None or PSCustomObject
+       By default, this does not generate any output. If you use the PassThru parameter,
+       it generates a PSCustomObject object that represents the last retrieved submission
+       which can be inspected for submission status.
+
     .EXAMPLE
         Start-ApplicationFlightSubmissionMonitor 0ABCDEF12345 01234567-89ab-cdef-0123-456789abcdef 1234567890123456789
 
@@ -1959,7 +1969,9 @@ function Start-ApplicationFlightSubmissionMonitor
 
         [string[]] $EmailNotifyTo = @(),
 
-        [switch] $NoStatus
+        [switch] $NoStatus,
+
+        [switch] $PassThru
     )
 
     Start-SubmissionMonitor @PSBoundParameters

StoreBroker/StoreIngestionIapApi.ps1

@@ -1922,6 +1922,16 @@ function Start-InAppProductSubmissionMonitor
         with no commandline status update.  When not specified, those commands run in
         the background, enabling the command prompt to provide status information.
 
+    .PARAMETER PassThru
+        Returns the final submission object that was retrieved when checking submission
+        status.  By default, this function does not generate any output.
+
+    .OUTPUTS
+       None or PSCustomObject
+       By default, this does not generate any output. If you use the PassThru parameter,
+       it generates a PSCustomObject object that represents the last retrieved submission
+       which can be inspected for submission status.
+
     .EXAMPLE
         Start-InAppProductSubmissionMonitor 0ABCDEF12345 1234567890123456789
 
@@ -1953,8 +1963,10 @@ function Start-InAppProductSubmissionMonitor
 
         [string[]] $EmailNotifyTo = @(),
 
-        [switch] $NoStatus
+        [switch] $NoStatus,
+
+        [switch] $PassThru
     )
 
     Start-SubmissionMonitor @PSBoundParameters
-}
+}