Mandatory Update and Package Rollout Support

Allows users to specify that an application or flight submission
is a mandatory update, or to enable gradual rollout on the packages
for those submissions.

This also introduces new top-level commands to allow users
to further control package rollout (Get / Update / Complete / Stop).

Additionally, the `Format-ApplicationSubmission` and
`Format-ApplicationFlightSubmission` commands were updated to also print
out mandatory update and package rollout information.  No new Format
command was introduced for `Get-ApplicationSubmissionPackageRollout` or
`Get-ApplicationFlightSubmissionPackageRollout` since the returned content
was simple enough as-is.

Additionally:

  * Updated Get-PiiSafeString / Get-SHA512Hash to support receiving
    empty / null strings, as it's possible to call
    `Update-ApplicationSubmission` and `Update-ApplicationFlightSubmission`
    without providing a packagePath, and without this update that would cause
    a parameter binding failure in those scenarios

  * Updated all of the `Patch-*Submission` methods to first convert
    TargetDate to UTC before using it, as that is the expected behavior from
    the API.  The documentation and Comment-Based-Help has been updated to
    indicate to users that the time will be converted to UTC for them.

Resolves #2: Add support for Package Rollout and Mandatory Update

Documentation/USAGE.md

@@ -13,6 +13,7 @@
 *   [Creating A New Application Submission](#creating-a-new-application-submission)
     *    [The Easy Way](#the-easy-way)
     *    [Manual Submissions](#manual-submissions)
+    *    [Related Commands](#related-commands)
 *   [Monitoring A Submission](#monitoring-a-submission)
     *   [Status Progression](#status-progression)
 *   [Flighting](#flighting)
@@ -168,6 +169,18 @@ The basic syntax looks of the command looks like this:
 
     Update-ApplicationSubmission -AppId <appId> -SubmissionDataPath ".\submission.json" -PackagePath ".\package.zip" -AutoCommit -Force
 
+While most of those parameters are straight-forward, the last two deserve explanation:
+
+ * **`-Force`** - You can only have one "pending" (e.g. in-progress) submission at any given
+   time.  Using `-Force` tells the command to delete any pending submission before continuing.
+   If you want to continue working with an existing pending submission, you can instead provide
+   the existing pending submission with the **`-SubmissionId`** paramter, as noted below.
+
+ * **`-AutoCommit`** - The submission will not start the certification process until you "commit"
+   it.  This switch says that the submission should automatically be committed once it has finished
+   replacing the submission content and uploading the package.  If you don't specify this, you'll
+   have to manually call the `Complete-ApplicationSubmission` command later on.
+
 > An important thing to note though, is that if you run that exact command above, the resulting
 > submission will be **identical** to the currently published submission, because you didn't tell
 > `Update-ApplicationSubmission` what you specifically wanted to modify.
@@ -228,8 +241,9 @@ fully override the publication and visibility of your app submission.
        Specify with `TargetPublishDate`
 
  * **`TargetPublishDate`** - The specific date/time that the submission should be published. To use
- this, you must specify `TargetPublishMode` as `SpecificDate`.  Using this value will override
- any value that might have been set by `-UpdatePublishModeAndVisibility`.
+   this, you must specify `TargetPublishMode` as `SpecificDate`.  Using this value will override
+   any value that might have been set by `-UpdatePublishModeAndVisibility`.  Users should provide this in
+   local time and it will be converted automatically to UTC.
 
  * **`Visibility`** - Indicates the store visibility of the app once the submission has been
    published. Setting this to any value other than `Default` will override the usage of
@@ -241,6 +255,35 @@ fully override the publication and visibility of your app submission.
      * **`Hidden`** - Hide this app and prevent acquisition. Customers with a promotional code can
        still download it on Windows 10 devices.
 
+You can control mandatory updates with the following parameters
+
+ * **`-IsMandatoryUpdate`** - Indicates whether you want to treat the packages in the submission
+   as mandatory packages for self-installing app updates.  For more information, refer to the
+   [Store documentation](https://docs.microsoft.com/en-us/windows/uwp/packaging/self-install-package-updates).
+
+ * **`MandatoryUpdateEffectiveDate`** - The date/time when the packges in this submission become mandatory.
+   This value will be ignored if `-IsMandatoryUpdate` is not also provided. Users should provide this in
+   local time and it will be converted automatically to UTC.
+
+You can also leverage gradual rollouts to limit the percentage of users who will be given the packages within
+this submission.
+
+ * **`PackageRolloutPercentage`** - _[0 - 100]_.  If specified, the packages in this submission will only
+   be rolled out to this percentage of your users.  You can later update this percentage by calling
+   `Update-ApplicationSubmissionPackageRollout`, and can complete the gradual rollout by either
+   finalizing it with `Complete-ApplicationSubmissionPackageRollout` (which will make the packages available
+   to all of your users) or `Stop-ApplicationSubmissionPackageRollout` (which will halt any new users from
+   getting the packages in this submission).
+
+   > Changing the percentage to 100 is not the same as Finalizing the package rollout.  For more information
+   > on this topic, refer to the [Store documentation](https://docs.microsoft.com/en-us/windows/uwp/publish/gradual-package-rollout).
+
+* **`ExistingPackageRolloutAction`** _[NoAction, Halt, Finalize]_ You can't create a new submission if
+  the current pending submission is currently using package rollout.  In that scenario, prior to calling
+  this command, you can manually call `Complete-ApplicationSubmissionPackageRollout` or
+  `Stop-ApplicationSubmissionPackageRollout`, or you can just sepecify this paramter and the action it
+  should take, and it will do that for you automatically prior to cloning the submission.
+
 > Due to the nature of how the Store API works, you won't see any of your changes in the
 > dev portal until your submission has entered into certification.  It doesn't have to _complete_
 > certification for you to see your changes, but it does have to enter certification first.
@@ -310,6 +353,31 @@ for your submission to enter into the Store certification process.
 > All of the commands referenced above will work for app and flight submissions equally.
 > If using them for flight submissions, just be sure to also include the FlightId parameter.
 
+### Related Commands
+
+In addition to the commands above, there are some other commands that you may find useful along the way.
+
+#### Gradual Rollout Commands
+
+If you're not familiar with package rollout, it might be helpful to read more about it
+in the [Store documentation](https://docs.microsoft.com/en-us/windows/uwp/publish/gradual-package-rollout).
+
+To view the current package rollout status:
+
+    Get-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
+
+To update the current package rollout percentage:
+
+    Update-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId> -Percentage <percentage>
+
+To halt the current package rollout:
+
+    Stop-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
+
+To finalize the current package rollout:
+
+    Complete-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
+
 ## Monitoring A Submission
 
 Once you've committed a new submission, an unknown amount of time must pass for it to go through
@@ -408,6 +476,18 @@ The basic syntax looks of the command looks like this:
 
     Update-ApplicationFlightSubmission -AppId <appId> -FlightId <flightId> -SubmissionDataPath ".\submission.json" -PackagePath ".\package.zip" -AutoCommit -Force
 
+While most of those parameters are straight-forward, the last two deserve explanation:
+
+ * **`-Force`** - You can only have one "pending" (e.g. in-progress) submission at any given
+   time.  Using `-Force` tells the command to delete any pending submission before continuing.
+   If you want to continue working with an existing pending submission, you can instead provide
+   the existing pending submission with the **`-SubmissionId`** paramter, as noted below.
+
+ * **`-AutoCommit`** - The submission will not start the certification process until you "commit"
+   it.  This switch says that the submission should automatically be committed once it has finished
+   replacing the submission content and uploading the package.  If you don't specify this, you'll
+   have to manually call the `Complete-ApplicationFlightSubmission` command later on.
+
 > An important thing to note though, is that if you run that exact command above, the resulting
 > submission will be **identical** to the currently published submission, because you didn't tell
 > `Update-ApplicationFlightSubmission` what you specifically wanted to modify.
@@ -458,8 +538,38 @@ fully override the publication of your app's flight submission.
        `TargetPublishDate`
 
  * **`TargetPublishDate`** - The specific date/time that the submission should be published. To use
- this, you must specify `TargetPublishMode` as `SpecificDate`.  Using this value will override
- any value that might have been set by `-UpdatePublishMode`.
+   this, you must specify `TargetPublishMode` as `SpecificDate`.  Using this value will override
+   any value that might have been set by `-UpdatePublishMode`.  Users should provide this in
+   local time and it will be converted automatically to UTC.
+
+You can control mandatory updates with the following parameters
+
+ * **`-IsMandatoryUpdate`** - Indicates whether you want to treat the packages in the submission
+   as mandatory packages for self-installing app updates.  For more information, refer to the
+   [Store documentation](https://docs.microsoft.com/en-us/windows/uwp/packaging/self-install-package-updates).
+
+ * **`MandatoryUpdateEffectiveDate`** - The date/time when the packges in this submission become mandatory.
+   This value will be ignored if `-IsMandatoryUpdate` is not also provided. Users should provide this in
+   local time and it will be converted automatically to UTC.
+
+You can also leverage gradual rollouts to limit the percentage of users who will be given the packages within
+this submission.
+
+ * **`PackageRolloutPercentage`** - _[0 - 100]_.  If specified, the packages in this submission will only
+   be rolled out to this percentage of your users.  You can later update this percentage by calling
+   `Update-ApplicationFlightSubmissionPackageRollout`, and can complete the gradual rollout by either
+   finalizing it with `Complete-ApplicationFlightSubmissionPackageRollout` (which will make the packages available
+   to all of your users) or `Stop-ApplicationFlightSubmissionPackageRollout` (which will halt any new users from
+   getting the packages in this submission).
+
+   > Changing the percentage to 100 is not the same as Finalizing the package rollout.  For more information
+   > on this topic, refer to the [Store documentation](https://docs.microsoft.com/en-us/windows/uwp/publish/gradual-package-rollout).
+
+* **`ExistingPackageRolloutAction`** _[NoAction, Halt, Finalize]_ You can't create a new submission if
+  the current pending submission is currently using package rollout.  In that scenario, prior to calling
+  this command, you can manually call `Complete-ApplicationFlightSubmissionPackageRollout` or
+  `Stop-ApplicationFlightSubmissionPackageRollout`, or you can just sepecify this paramter and the action it
+  should take, and it will do that for you automatically prior to cloning the submission.
 
 > Due to the nature of how the Store API works, you won't see any of your changes in the
 > dev portal until your submission has entered into certification.  It doesn't have to _complete_
@@ -531,6 +641,27 @@ To monitor a flight submission:
 Follow the same steps for [monitoring an application submission](#monitoring-a-submission), but
 just be sure to _also include_ the **`-FlightId`** in the cmdlet parameters.
 
+##### Gradual Rollout
+
+If you're not familiar with package rollout, it might be helpful to read more about it
+in the [Store documentatin](https://docs.microsoft.com/en-us/windows/uwp/publish/gradual-package-rollout).
+
+To view the current package rollout status:
+
+    Get-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
+
+To update the current package rollout percentage:
+
+    Update-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId> -Percentage <percentage>
+
+To halt the current package rollout:
+
+    Stop-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
+
+To finalize the current package rollout:
+
+    Complete-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
+
 ## In App Products
 
 ### IAP Overview
@@ -637,7 +768,8 @@ fully override the publication and visibility of your IAP submission.
 
  * **`TargetPublishDate`** - The specific date/time that the submission should be published. To use
    this, you must specify `TargetPublishMode` as `SpecificDate`.  Using this value will
-   override any value that might have been set by `-UpdatePublishModeAndVisibility`.
+   override any value that might have been set by `-UpdatePublishModeAndVisibility`.  Users should
+   provide this in local time and it will be converted automatically to UTC.
 
  * **`Visibility`** - Indicates the store visibility of the app once the submission has been
    published.  Setting this to any value other than `Default` will override the usage of

README.md

@@ -6,7 +6,6 @@
     *   [Project Status](#project-status)
     *   [Goals](#goals)
     *   [Current Functionality](#current-functionality)
-        *   [Limitations](#limitations)
     *   [Prerequisites](#prerequisites)
 *   [Installation and Setup](#installation-and-setup)
 *   [Usage](#usage)
@@ -73,14 +72,6 @@ At a very high level, this is what you can do with StoreBroker:
  - General
     - Submission Monitor with email support
 
-#### Limitations
-
-At this time, we don't have support for these newest additions to the API, but they are on our
-[backlog to add](https://github.com/Microsoft/StoreBroker/issues/2):
-
-  - Package Rollout
-  - Mandatory Update
-
 ### Prerequisites
 
 This module requires PowerShell [version 4](https://en.wikipedia.org/wiki/PowerShell#PowerShell_4.0)

StoreBroker/Helpers.ps1

@@ -299,6 +299,8 @@ function Get-SHA512Hash
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
         [string] $PlainText
     )
 

StoreBroker/StoreBroker.psd1

@@ -6,7 +6,7 @@
     CompanyName = 'Microsoft Corporation'
     Copyright = 'Copyright (C) Microsoft Corporation.  All rights reserved.'
 
-    ModuleVersion = '1.2.2'
+    ModuleVersion = '1.3.0'
     Description = 'Provides command-line access to the Windows Store Submission REST API.'
 
     RootModule = 'StoreIngestionApi'
@@ -27,7 +27,9 @@
     FunctionsToExport = @(
         'Clear-StoreBrokerAuthentication',
         'Complete-ApplicationFlightSubmission',
+        'Complete-ApplicationFlightSubmissionPackageRollout',
         'Complete-ApplicationSubmission',
+        'Complete-ApplicationSubmissionPackageRollout',
         'Complete-InAppProductSubmission',
         'Format-Application',
         'Format-ApplicationFlight',
@@ -42,10 +44,12 @@
         'Get-Application',
         'Get-ApplicationFlight',
         'Get-ApplicationFlightSubmission',
+        'Get-ApplicationFlightSubmissionPackageRollout',
         'Get-ApplicationFlightSubmissionStatus',
         'Get-ApplicationFlights',
         'Get-ApplicationInAppProducts',
         'Get-ApplicationSubmission',
+        'Get-ApplicationSubmissionPackageRollout',
         'Get-ApplicationSubmissionStatus',
         'Get-Applications',
         'Get-FlightGroups',
@@ -80,8 +84,12 @@
         'Start-ApplicationFlightSubmissionMonitor',
         'Start-InAppProductSubmissionMonitor',
         'Start-SubmissionMonitor',
+        'Stop-ApplicationFlightSubmissionPackageRollout',
+        'Stop-ApplicationSubmissionPackageRollout',
         'Update-ApplicationFlightSubmission',
+        'Update-ApplicationFlightSubmissionPackageRollout',
         'Update-ApplicationSubmission',
+        'Update-ApplicationSubmissionPackageRollout',
         'Update-InAppProductSubmission')
 
     AliasesToExport = @(
@@ -90,6 +98,8 @@
         'Commit-IapSubmission',
         'Commit-InAppProductSubmission',
         'Complete-InAppProductSubmission',
+        'Finalize-ApplicationFlightSubmissionPackageRollout',
+        'Finalize-ApplicationSubmissionPackageRollout',
         'Format-ApplicationIaps',
         'Format-Iap',
         'Format-IapSubmission',
@@ -99,6 +109,8 @@
         'Get-IapSubmission',
         'Get-IapSubmissionStatus',
         'Get-Iaps',
+        'Halt-ApplicationFlightSubmissionPackageRollout',
+        'Halt-ApplicationSubmissionPackageRollout',
         'New-Iap',
         'New-IapSubmission',
         'New-IapSubmissionPackage',

StoreBroker/StoreIngestionApi.psm1

@@ -27,6 +27,7 @@ $script:accessTokenTimeoutSeconds = (59 * 60) - $script:accessTokenRefreshBuffer
 $script:keywordSpecificDate = 'SpecificDate'
 $script:keywordManual = 'Manual'
 $script:keywordDefault = 'Default'
+$script:keywordNoAction = 'NoAction'
 $script:keywordPendingDelete = 'PendingDelete'
 $script:keywordPendingCommit = 'PendingCommit'
 $script:keywordRelease = 'Release'
@@ -1757,7 +1758,7 @@ function Invoke-SBRestMethodMultipleResult
     .EXAMPLE
         Invoke-SBRestMethodMultipleResult "applications" "Get apps"
         Gets the first 100 applications associated with this developer account,
-        with the console window showing progress while awaiting for the response
+        with the console window showing progress while awaiting the response
         from the REST request.
 
     .EXAMPLE
@@ -1769,14 +1770,14 @@ function Invoke-SBRestMethodMultipleResult
     .EXAMPLE
         Invoke-SBRestMethodMultipleResult "applications" "Get apps" 500
         Gets the first 500 applications associated with this developer account,
-        with the console window showing progress while awaiting for the response
+        with the console window showing progress while awaiting the response
         from the REST request.
 
     .EXAMPLE
         Invoke-SBRestMethodMultipleResult "applications" "Get apps" 10 -StartAt 50
         Gets the next 10 apps in the developer account starting with the 51st app
         (since it's a 0-based index) with the console window showing progress while
-        awaiting for the response from the REST request.
+        awaiting the response from the REST request.
 #>
     [CmdletBinding(SupportsShouldProcess)]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]