AdvancedListings support (gaming options and trailers) + additional s…

…creenshots

+ Adds gamingOptions support
  * Updated the config file with `gamingOptions`
  * `New-StoreBrokerConfigFile` now populates those values
  * `Update-ApplicationSubmission` / `Patch-ApplicationSubmission` updated to
    support `-UpdateGamingOptions`
  * `Format-Application` updated to print out hasAdvancedListingSupport
  * `Format-ApplicationSubmission` updated to print out gaming options when available

+ Adds trailers support
  * Updated the PDP schema to support trailers
  * `ConvertFrom-ExistingSubmission` now exports trailer info to the PDP's.
  * `New-SubmissionPackage` will coalesce trailer information into the
     generated json
  * `Update-ApplicationSubmission` / `Patch-ApplicationSubmission` updated to
    support `-UpdateTrailers`

+ Adds support for additional image/screenshot types
  * Adds support for all remaining "AdditonalAssets" (all of the other
    image types that aren't explicitly screenshots with captions), like
    "hero images".

Documentation/PDP.md

@@ -9,6 +9,8 @@
 *   [Sections](#sections)
     *   [Screenshots and Captions](#screenshots-and-captions)
         *   [Folder Structure](#folder-structure)
+    *   [Additional Assets](#additional-assets)
+        *   [Trailers](#trailers)
     *   [Icons](#icons)
     *   [Fallback Language Support](#fallback-language-support)
 *   [Schemas And Samples](#schemas-and-samples)
@@ -114,6 +116,80 @@ where:
     looking recusively for the specific filename
  * `img.png`: the filename that you specified in the caption's platform-specific image attribute
 
+### Additional Assets
+
+> Only relevant for Application submissions
+
+There are three different types of images that can be used for a listing:
+  1. Screenshots (these have captions)
+  2. Additional Assets (these are images that have no concept of captions)
+  3. Trailer screenshots (which also don't have captions, but are tied to trailers)
+
+In the [previous section](#screenshots-and-captions), we talked about screenshots
+(and their captions).  Now we will talk about #2 (Additional Assets).
+
+You can learn more about the specifics of these different images and how they're used by referring to the
+[dev portal's online documentation](https://docs.microsoft.com/en-us/windows/uwp/publish/app-screenshots-and-images),
+and the related [API documentation](https://docs.microsoft.com/en-us/windows/uwp/monetize/manage-app-submissions#image-object).
+
+To define these assets, there is a top-level element called `AdditionalAssets` (which
+is a sibling to `ScreenshotCaptions`).  It can contain any (or all) of the following
+elements:
+
+ * `StoreLogo9x16`
+ * `StoreLogoSquare`
+ * `Icon`
+ * `PromotionalArt16x9`
+ * `PromotionalArtwork2400X1200`
+ * `XboxBrandedKeyArt`
+ * `XboxTitledHeroArt`
+ * `XboxFeaturedPromotionalArt`
+ * `SquareIcon358X358`
+ * `BackgroundImage1000X800`
+ * `PromotionalArtwork414X180`
+
+These elements do not have any InnerText/content -- they only have a single attribute
+called `FileName` which should reference the .png file for that image type.
+
+Similar to Screenshots, there is full [fallback language support](#fallback-language-support).
+You can add the `FallbackLanguage` attribute on an individual element to only affect that one
+image type, or you can add it to `AdditionalAssets` to affect them all (or to
+`ProductDescription` to affect all asset types).
+
+#### Trailers
+
+> Only relevant for Application submissions
+
+> Can only be set on applications that have
+> [`Advanced Listing Permission`](https://docs.microsoft.com/en-us/windows/uwp/monetize/manage-app-submissions#advanced-listings).
+
+You can learn more about the specifics of trailers and how they're used by referring to the
+[dev portal's online documentation](https://docs.microsoft.com/en-us/windows/uwp/publish/app-screenshots-and-images#trailers).
+
+A single trailer consists of the following information:
+  * trailer filename
+  * trailer title (localizable)
+  * trailer screenshot filename (only one permitted)
+  * trailer screenshot description (metadata only, never seen be a user)
+
+From an authoring perspective, it looks like this (with loc comment/attributes removed for brevity):
+
+    <Trailers>
+        <Trailer FileName="trailer1.mp4">
+            <Title>This is the trailer's title</Title>
+            <Images>
+               <Image FileName="trailer1screenshot.png">The user will never see this text</Image>
+            </Images>
+        </Trailer>
+    </Trailers>
+
+While companies may or may not provide localized screenshots per region, most companies will only
+ever produce their trailers for a limited number of different languages/regions, and re-use
+those same trailers across most other locales.  Therefore, it is highly advised that you leverage
+[fallback language support](#fallback-language-support) when authoring your trailers
+so that trailers are propery re-used, thus reducing the size of the final package that needs
+to be uploaded to the Store.
+
 ### Icons
 
 > Only relevant for In-App Product (IAP) ("add-on") submissions
@@ -143,6 +219,13 @@ screenshots, the attribute is available on both the `<ScreenshotCaptions />` _an
 It can be set on either, or both, of those elements.  If specified on both, the value in the `<Caption />`
 node value will win, since it is the more-specific value.
 
+Similarly, there is support for `AdditionalAsset` images (on the individual element nodes as well as on
+the `AdditionalAsset` node itself), and for trailers on the `Trailers`, `Trailer`, `Images` and `Image`
+elements).
+
+You can also set `FallbackLanguage` at the root element (`ProductDescription` or `InAppProductDescription`)
+to affect every media type.
+
 As usual, StoreBroker will first search for any media files referenced by that element in that PDP's
 langcode-specific images/media sub-folder.  If not found, it will then look in the fallback language's
 images/media sub-folder.  Only then will StoreBroker fail if the file still cannot be found.

Documentation/USAGE.md

@@ -65,7 +65,7 @@ when the module is loaded.
 
  **`$global:SBLogPath`** - [string] The logfile. Defaults to
    `$env:USERPROFILE\Documents\StoreBroker.log`
-    
+
  **`$global:SBLoggingEnabled`** [bool] Defaults to `$true`. To disable file-based logging,
     set to `$false`
 
@@ -158,7 +158,7 @@ following the instructions in [SETUP.md](SETUP.md):
 
 Generating the submission request JSON/zip package is done with
 
-    New-SubmissionPackage -ConfigPath <config-path> -PDPRootPath <path> [[-Release] <string>] -PDPInclude <filename> [-PDPExclude <filename>] -ImagesRootPath <path> -AppxPath <full-path>[, <additional-path>]+ -OutPath <output-dir> -OutName <output-name>  
+    New-SubmissionPackage -ConfigPath <config-path> -PDPRootPath <path> [[-Release] <string>] -PDPInclude <filename> [-PDPExclude <filename>] -ImagesRootPath <path> -AppxPath <full-path>[, <additional-path>]+ -OutPath <output-dir> -OutName <output-name>
 
 > Items in brackets ('[]') are optional.
 
@@ -167,13 +167,13 @@ files. For more info, run:
 
     Get-Help New-SubmissionPackage -Parameter PdpRootPath
     Get-Help New-SubmissionPackage -Parameter Release
-    
+
 > If one of your parameters does not change often, you can specify a value in the config file and
 > leave out this parameter at runtime. In this case, you should specify the remaining parameters
 > to `New-SubmissionPackage` with their parameter names.  As an example, it is possible to leave
 > out `OutPath` but if you don't specify the remaining parameters by name, then the value of the
 > next parameter, `OutName`, will be mapped to the `OutPath` parameter, causing a failure.
-    
+
 As part of its input, `New-SubmissionPackage` expects a configuration file, which you should
 have [already created](SETUP.md#getting-your-config).
 
@@ -242,7 +242,7 @@ cloned submission:
    > **WARNING:** Use this switch with care.  If you use this switch and your StoreBroker
    > payload doesn't have all the packages for all the OS versions & platforms that you currently
    > support (and want to continue to support), then you risk making your app unavailable to some
-   > of your users.   
+   > of your users.
 
  * **`-UpdateListings`** - This will replace the cloned submission's listings metadata with yours
    (the localized content from the PDP's), deleting any existing screenshots along the way.  This
@@ -263,6 +263,17 @@ cloned submission:
    `canInstallOnRemovableMedia`, `automaticBackupEnabled`, and `isGameDvrEnabled` of
    the cloned submission to that which is specified in your json.
 
+ * **`-UpdateGamingOptions`** - This will update all values under the `gamingOptions`
+   node specified in your json.  Please note that your application must have
+   ["Advanced Listing Permission"](https://docs.microsoft.com/en-us/windows/uwp/monetize/manage-app-submissions#advanced-listings)
+   enabled for this to work.
+
+ * **`-UpdateTrailers`** - This will replace the cloned submission's trailers metadata with yours
+   (the localized content from the PDP's), deleting any existing data along the way.
+   Please note that your application must have
+   ["Advanced Listing Permission"](https://docs.microsoft.com/en-us/windows/uwp/monetize/manage-app-submissions#advanced-listings)
+   enabled for this to work.  For more info on trailers, review [PDP.md](./PDP.md#trailers).
+
  * **`-UpdateNotesForCertification`** - This will change the `notesForCertification` field of
    the cloned submission to that which is specified in your json.
 
@@ -344,14 +355,14 @@ with a single command.  However, should one choose to do so, you can perform all
 manually.
 
  * Clone the existing published submission so that you can generate an update.
- 
+
           $sub = New-ApplicationSubmission -AppId <appId> [-Force]
 
     * By using the `-Force` switch, it will call `Remove-ApplicationSubmission` behind the
       scenes if it finds that there's an existing pending submission for your app.
 
  * Read in the content of the json file from your `New-SubmissionPackage` payload:
- 
+
           $json = (Get-Content .\submission.json -Encoding UTF8) | ConvertFrom-Json
 
  * If you need to update any content for the cloned submission, here is where you'd "patch in"
@@ -536,7 +547,7 @@ While most of those parameters are straight-forward, the last two deserve explan
 
 > If for some reason you have an existing pending submission that you want to update (as opposed
 > to cloning the existing published submission), use `-SubmissionId` to specify it, and that
-> will be used instead of creating a new cloned submission.  That parameter 
+> will be used instead of creating a new cloned submission.  That parameter
 
 The following key switches can be added in any order or combination, and they will indicate what
 content from the .json that you are providing needs to be added to or replaced within the
@@ -735,7 +746,7 @@ following the instructions in [SETUP.md](SETUP.md):
 
 Generating the submission request JSON/zip package is done with
 
-    New-InAppProductSubmissionPackage -ConfigPath <config-path> -PDPRootPath <path> [[-Release] <string>] -PDPInclude <filename> [-PDPExclude <filename>] -ImagesRootPath <path> -OutPath <output-dir> -OutName <output-name>  
+    New-InAppProductSubmissionPackage -ConfigPath <config-path> -PDPRootPath <path> [[-Release] <string>] -PDPInclude <filename> [-PDPExclude <filename>] -ImagesRootPath <path> -OutPath <output-dir> -OutName <output-name>
 
 > Items in brackets ('[]') are optional.
 
@@ -744,14 +755,14 @@ files. For more info, run:
 
     Get-Help New-InAppProductSubmissionPackage -Parameter PdpRootPath
     Get-Help New-InAppProductSubmissionPackage -Parameter Release
-    
+
 > If one of your parameters does not change often, you can specify a value in the config file and
 > leave out this parameter at runtime. In this case, you should specify the remaining parameters
 > to `New-InAppProductSubmissionPackage` with their parameter names.  As an example, it is
 > possible to leave out `OutPath` but if you don't specify the remaining parameters by name,
 > then the value of the next parameter, `OutName`, will be mapped to the `OutPath` parameter,
 > causing a failure.
-    
+
 As part of its input, `New-InAppProductSubmissionPackage` expects a configuration file, which
 you should have [already created](SETUP.md#getting-your-iap-config).
 
@@ -775,7 +786,7 @@ The basic syntax looks of the update command looks like this:
 
 > If for some reason you have an existing pending submission that you want to update (as opposed
 > to cloning the existing published submission), use `-SubmissionId` to specify it, and that
-> will be used instead of creating a new cloned submission.  That parameter 
+> will be used instead of creating a new cloned submission.  That parameter
 
 The following key switches can be added in any order or combination, and they will indicate what
 content from the .json that you are providing needs to be added to or replaced within the
@@ -1117,7 +1128,7 @@ us for analysis.  We expose it here for complete transparency.
      to all the languages that you want it localized for.  If different languages need
      a different set of captions (e.g. screenshots), then that means that you simply
      need to have multiple English PDP files, and localize the different English PDP's into
-     the right set of languages appropriate for that content. 
+     the right set of languages appropriate for that content.
 
 * **What I submit to the Store is the result of multiple builds.  How can I submit the results
   in a single submission?**
@@ -1131,9 +1142,9 @@ us for analysis.  We expose it here for complete transparency.
 
      We offer an additional command that can be used to combine two payload into a single payload
      (and if you have more than two, just daisy chain the output from one as the input to the next).
-    
+
             Join-SubmissionPackage -MasterJsonPath <path> -AdditionalJsonPath <path> -OutJsonPath <path> -AddPackages
-     
+
      As you'll recall, a payload is a json/zip pair.  The <path> specified in each of these
      parameters is the path to the json file, and the .zip file is determined from that same base
      name.  The resulting output will be identitical to the json/zip pair provided for

Extensions/ConvertFrom-ExistingIapSubmission.ps1

@@ -21,6 +21,9 @@
         The most recent submission for IapId will be used unless a value for this parameter is
         provided.
 
+    .PARAMETER SubmissionId
+        The submission object that you want to convert, which was previously retrieved.
+
     .PARAMETER Release
         The release to use.  This value will be placed in each new PDP and used in conjunction with '-OutPath'.
         Some examples could be "1601" for a January 2016 release, "March 2016", or even just "1".
@@ -36,15 +39,49 @@
         Each of these sub-folders will have region-specific subfolders for their file content.
 
     .EXAMPLE
-        .\ConvertFrom-ExistingSubmission -IapId 0ABCDEF12345 -Release "March Release" -OutPath "C:\NewPDPs"
+        .\ConvertFrom-ExistingIapSubmission -IapId 0ABCDEF12345 -Release "March Release" -OutPath "C:\NewPDPs"
+
+        Converts the data from the last published submission for IapId 0ABCDEF12345.  The generated files
+        will use the default name of "PDP.xml" and be located in lang-code specific sub-directories within
+        c:\NewPDPs.
+
+    .EXAMPLE
+        .\ConvertFrom-ExistingIapSubmission -IapId 0ABCDEF12345 -SubmissionId 1234567890123456789 -Release "March Release" -PdpFileName "InAppProductDescription.xml" -OutPath "C:\NewPDPs"
+
+        Converts the data from submission 1234567890123456789 for IapId 0ABCDEF12345 (which might be a
+        published or pending submission).  The generated files will be named "InAppProductDescription.xml" and
+        will be located in lang-code specific sub-directories within c:\NewPDPs.
+
+    .EXAMPLE
+        .\ConvertFrom-ExistingIapSubmission -Submission $sub -Release "March Release" -OutPath "C:\NewPDPs"
+
+        Converts the data from a submission object that was captured earlier in your PowerShell session.
+        It might have come from Get-InAppProductSubmission, or it might have been generated some other way.
+        This method of running the script was created more for debugging purposes, but others may find it
+        useful. The generated files will use the default name of "PDP.xml" and be located in lang-code
+        specific sub-directories within c:\NewPDPs.
 #>
-[CmdletBinding()]
+[CmdletBinding(
+    SupportsShouldProcess,
+    DefaultParametersetName = "UseApi")]
 param(
-    [Parameter(Mandatory)]
+    [Parameter(
+        Mandatory,
+        ParameterSetName = "UseApi",
+        Position = 0)]
     [string] $IapId,
 
+    [Parameter(
+        ParameterSetName = "UseApi",
+        Position = 1)]
     [string] $SubmissionId = $null,
 
+    [Parameter(
+        Mandatory,
+        ParameterSetName = "ProvideSubmission",
+        Position = 0)]
+    [PSCustomObject] $Submission = $null,
+
     [Parameter(Mandatory)]
     [string] $Release,
 
@@ -205,7 +242,7 @@ function Add-Title
     $maxChars = 100
     $paramSet = @{
         "Element" = $elementNode;
-        "Attribute" = @{ $script:LocIdAttribute = $script:LocIdFormat -f $elementName };
+        "Attribute" = @{ $script:LocIdAttribute = ($script:LocIdFormat -f $elementName) };
         "Comment" = @(
             " [required] ",
             ($script:CommentFormat -f $maxChars, "IAP $elementName"))
@@ -242,7 +279,7 @@ function Add-Description
     $maxChars = 200
     $paramSet = @{
         "Element" = $elementNode;
-        "Attribute" = @{ $script:LocIdAttribute = $script:LocIdFormat -f $elementName };
+        "Attribute" = @{ $script:LocIdAttribute = ($script:LocIdFormat -f $elementName) };
         "Comment" = @(
             " [optional] ",
             ($script:CommentFormat -f $maxChars, "IAP $elementName"))
@@ -552,18 +589,22 @@ function Main
         throw $message
     }
 
-    if ([String]::IsNullOrEmpty($SubmissionId))
+    $sub = $Submission
+    if ($null -eq $sub)
     {
-        $iap = Get-InAppProduct -IapId $IapId
-        $SubmissionId = $iap.lastPublishedInAppProductSubmission.id
         if ([String]::IsNullOrEmpty($SubmissionId))
         {
-            $SubmissionId = $iap.pendingInAppProductSubmission.id
-            Write-Log -Message "No published submission exists for this In-App Product.  Using the current pending submission." -Level Warning
+            $iap = Get-InAppProduct -IapId $IapId
+            $SubmissionId = $iap.lastPublishedInAppProductSubmission.id
+            if ([String]::IsNullOrEmpty($SubmissionId))
+            {
+                $SubmissionId = $iap.pendingInAppProductSubmission.id
+                Write-Log -Message "No published submission exists for this In-App Product.  Using the current pending submission." -Level Warning
+            }
         }
-    }
 
-    $sub = Get-InAppProductSubmission -IapId $IapId -SubmissionId $SubmissionId
+        $sub = Get-InAppProductSubmission -IapId $IapId -SubmissionId $SubmissionId
+    }
 
     $langImageNames = @{}
     $langs = ($sub.listings | Get-Member -type NoteProperty)