v1.1.0 - Create PDP XSD for IAP's, and add New-IapSubmissionPackage

* Added new PDP schema and example file for IAP's and updated the
  corresonding PDP.md documentation.
* Adds ConvertFrom-ExistingIapSubmission.ps1, mirroring
  ConvertFrom-ExistingSubmission.ps1, to auto-generate the IAP
  PDP set from an existing publishing or pending submission.
* Added the ability to generate a new IAP StoreBroker configuration
  file based on a default config file, as well as based on a
  current submission for that IAP, similar to what we do for
  applications.
* Added New-InAppProductSubmissionPackage to generate a StoreBroker
  payload from a config file and IAP PDP's (and optional icons).
* Updated PackageTool's Resolve-PackageParameters helper method to
  optionally skip a list of parameters so that the same method could
  be used for both packaging commands since they're so similar, even
  though IAP's don't use appx packages.
* Updated Update-InAppProductSubmission to do a similar iapId check
  of the commandline vs the payload's json value, similar to what we
  do for Update-ApplicationSubmission.
* Updated SETUP.md and USAGE.md documentation to reflect these changes,
  and removed the note in README.md that this work hasn't been done yet.

Additionally:
* Fixed telemetry property typos for Iap's (referencing an Iap property
  instead of IapId), along with other AppId->IapId references for the
  IAP methods.
* Fixed documentation example typo in ConvertFrom-ExistingSubmission.ps1
* Minor related Comment-Based-Help (CBH) changes to PackageTool.

Author: HowardWolosky

Documentation/PDP.md

@@ -9,6 +9,7 @@
 *   [Sections](#sections)
     *   [Screenshots and Captions](#screenshots-and-captions)
         *   [Folder Structure](#folder-structure)
+    *   [Icons](#icons)
 *   [Schemas And Samples](#schemas-and-samples)
 *   [Loc Attributes and Comments](#loc-attributes-and-comments)
     *   [Marking A String To Not Be Localized](#marking-a-string-to-not-be-localized)
@@ -43,6 +44,8 @@ localize the relevant content.
 The main sections that you'll find in the PDP (depending on which schema version is in use)
 are as follows:
 
+**For Application Submissions**
+ * AppStoreName
  * Keywords
  * Description
  * ReleaseNotes
@@ -55,12 +58,19 @@ are as follows:
  * SupportContactInfo
  * PrivacyPolicyURL
 
+**For In-App Product (IAP) ("add-on") Submissions**
+ * Title
+ * Description
+ * Icon
+
 These should map fairly clearly to the sections you're already familiar with in the DevPortal.
 For additional requirements on number of elements or length of individual elements, refer to
 the schema (or sample file).
 
 ### Screenshots and Captions
 
+> Only relevant for Application submissions
+
 It's worth a little bit of additional time to explain how screenshots and captions work.
 
 The DevPortal has different screenshot sections per platform, and you need to specify a caption
@@ -103,17 +113,33 @@ where:
     looking recusively for the specific filename
  * `img.png`: the filename that you specified in the caption's platform-specific image attribute
 
+### Icons
+
+> Only relevant for In-App Product (IAP) ("add-on") submissions
+
+Unlike screenshots, icons have no associated captions with them.  However, it is possible that
+your IAP may need to use a different icon based on the region (maybe a different symbol or color
+is needed based on that region's culture), and so the icon is part of the PDP.
+
+The only thing that can be specified for the Icon is the filename of that icon.  It is expected
+that the filename will be found within the defined [folder structure](#folder-structure).
 
 ----------
 
 ## Schemas and Samples
 
-At this time, StoreBroker only has a single PDP schema in use:
+At this time, StoreBroker has two PDP schemas in use:
 
+### Application Submissions
  * **Uri**: `http://schemas.microsoft.com/appx/2012/ProductDescription`
  * **XSD**: [PDP\ProductDescription.xsd](..\PDP\ProductDescription.xsd)
  * **Sample XML**: [PDP\ProductDescription.xml](..\PDP\ProductDescription.xml)
 
+### In-App Product (IAP) ("add-on") Submissions
+ * **Uri**: `http://schemas.microsoft.com/appx/2012/InAppProductDescription`
+ * **XSD**: [PDP\InAppProductDescription.xsd](..\PDP\InAppProductDescription.xsd)
+ * **Sample XML**: [PDP\InAppProductDescription.xml](..\PDP\InAppProductDescription.xml)
+
 ----------
 
 ## Loc Attributes and Comments

Documentation/SETUP.md

@@ -23,6 +23,11 @@
     *   [Getting Your PDPs](#getting-your-pdps)
         *   [Collecting Your Screenshots](#collecting-your-screenshots)
     *   [Getting Your Config](#getting-your-config)
+*   [IAP Setup](#iap-setup)
+    *   [Getting Your IapId](#getting-your-iapid)
+    *   [Getting Your IAP PDPs](#getting-your-iap-pdps)
+        *   [Collecting Your Icons](#collecting-your-icons)
+    *   [Getting Your IAP Config](#getting-your-iap-config)
 *   [Other Convenience Changes](#other-convenience-changes)
 *   [Using StoreBroker](#using-storebroker)
 
@@ -196,7 +201,7 @@ to authenticate against the developer account that you are trying to modify.
 
 #### Getting Credentials
 
->  You only need to perform this task once per user.  You'll re-use these credentials as if they
+> You only need to perform this task once per user.  You'll re-use these credentials as if they
 > were your username and password.
 
 First you have to get three key pieces of information:
@@ -393,11 +398,12 @@ Every project should have its own StoreBroker config file.  The config file has
    to name this file whatever you want).
 
 2. Once you have the config, review all of the app properties at the bottom half of the file.
-   These are the values for these properties as they are configured for your app in the store today.
-   Some users have realized that the values in the store (and thus in this file) are not what they
+   These are the values for these properties as they are configured for your app in the Store today.
+   Some users have realized that the values in the Store (and thus in this file) are not what they
    expected, so it's worth checking them here and fixing them if need be.  (If you do change any of
-   these properties, you'll need to use the appropriate _switch_ to the `Update-ApplicationSubmission`
-   later on to make sure that your changes are applied).
+   these properties, you'll need to use the appropriate _switch_ to
+   [`Update-ApplicationSubmission`](USAGE.md#creating-a-new-application-submission) later on
+   to make sure that your changes are applied).
 
 3. Now you need to set the `New-SubmissionPackage` parameter values at the top half of the file.
    These parameter values are very well documented within the config file, but here's an additional
@@ -481,6 +487,105 @@ Every project should have its own StoreBroker config file.  The config file has
 
 4. [Optional] Check this file in side-by-side with your code for version control support.
 
+----------
+
+## IAP Setup
+
+The [prerequisites](#prerequisites) and [authentication steps](#authentication) are identical here
+as they are for applications (as explained above), and so they will not be repeated here.
+
+### Getting Your IapId
+
+The next steps require you to know the IapId for the In-App Product ("add on") that you are trying
+to use with StoreBroker.
+
+To run the next command, you'll need your [AppId](#getting-your-appid) from above.
+Run the following and get the `ID` that is shown there (it looks like this: `0ABCDEF12345`).
+That's your `IapId`.
+
+    Get-ApplicationInAppProducts -AppId <appId> -GetAll | Format-ApplicationInAppProducts
+
+> The Windows Store Submission API does not currently support IAP's that are "Store Managed Consumables."
+> You will not be able to use StoreBroker to manage that type of IAP until the API has been updated.
+> Additionally, if your application _has_ one of those IAPS's, the above command will fail with
+> a `409` error.  In this scenario, you'll need to manually get the `IapId` by copying it from the
+> URL of the Dev Center web portal when trying to edit that IAP.
+
+### Getting Your IAP PDPs
+
+A major benefit of using the StoreBroker to do your updates, is that it can submit all of the
+metadata (title, description, icons, etc...) automatically.
+However, in order to create the "payload" (json and zip) required to use the API, it needs to have
+a uniform way of getting that metadata content.
+
+Enter the [PDP](PDP.md) XML format.  PDP stands for Product Description Page, and the PDP.xml file
+is a schema that Microsoft uses internally to store all of the localizable metadata for an
+In-App Product.  That XML file then gets localized into every language that the application has a
+Store listing for.
+
+> You don't _have_ to use PDP files to store your metadata in the event that you already have a
+> different method of localization.  However, if you don't choose to use the PDP format, then
+> you will have to write your own version of `New-InAppProductSubmissionPackage` in order to
+> create the payload (json and zip) that the other StoreBroker commands require.
+
+You can read [PDP.md](PDP.md) for greater detail on PDP files.  Right now, we just need to get you
+started by generating your IAP's PDP files based on your current published (or pending) submission.
+
+    .\Extensions\ConvertFrom-ExistingIapSubmission.ps1 -IapId <iapId> -Release <release> -PdpFileName <pdpFileName> -OutPath <outPath>
+
+Where:
+  * `<iapId>` is your IAP's ID.
+  
+  * `<release>` is the name of this release.  Many teams name their releases as `YYMM`
+    (depending on how often they release).  This value will be added to each of the PDP's that are
+    generated, and will impact the expected location of the screenshots being referenced.  More on
+    that folder structure in the [next section](#getting-your-config).
+
+  * `<pdpFileName>` - The name you want to give to the PDP files -- people often use `PDP.xml`.
+
+  * `<outPath>` - The folder that the PDP files should be stored in.  _Langcode_ sub-folders will
+    be created for storing the PDP files, as `New-InAppProductSubmissionPackage` depends on
+    that folder structure for determining what _langcode_ a PDP file is associated with.
+
+#### Collecting Your Icons
+
+The API does not provide any ability to download the existing icons for an IAP listing.  When
+the script completes, it will tell you what icons it expects you to gather up manually, and the
+folder structure that you should be putting them in to.
+
+### Getting Your IAP Config
+
+Every IAP should have its own StoreBroker config file.  The config file has two parts to it:
+
+ * The top part lets you specify parameters to `New-InAppProductSubmissionPackage` that remain
+   static, so that you don't have to specify them at the commandline each time.
+ * The bottom part lets you specify In-App Product submission properties that generally remain static
+   between submissions and aren't localized.
+
+#### IAP Config Setup Steps
+
+1. Now run `New-StoreBrokerInAppProductConfigFile -Path $home\desktop\SBConfig.json -IapId <IapId>`,
+   substituting in your [IapId](#getting-your-iapid), and that will generate a pre-populated config
+   file to your desktop, based on the current configuration of your IAP in the Store. (Feel free
+   to name this file whatever you want).
+
+2. Once you have the config, review all of the properties at the bottom half of the file.
+   These are the values for these properties as they are configured for your IAP in the Store today.
+   Some users have realized that the values in the Store (and thus in this file) are not what they
+   expected, so it's worth checking them here and fixing them if need be.  (If you do change any of
+   these properties, you'll need to use the appropriate _switch_ to
+   [`Update-InAppProductSubmission`](USAGE.cmd#iap-commands) later on to make sure that your
+   changes are applied).
+
+3. Now you need to set the `New-InAppProductSubmissionPackage` parameter values at the top half
+   of the file.  These parameter values are very well documented within the config file, but for
+   more detailed information on what you'll _likely_ want to change, refer to **step 3** in
+   [Config Setup Steps](#config-setup-steps) above.
+
+4. [Optional] Check this file in side-by-side with your code for version control support.
+
+----------
+
 ## Other Convenience Changes
 
 Well, you did it.  You're now _fully_ setup to start using StoreBroker.
@@ -505,6 +610,8 @@ While not required, there are other things that you can do to make your usage ev
   create global variables to reference other common Ids (flightId, IapId), paths (like the path to
   your StoreBroker config file), etc...
 
+----------
+
 ## Using StoreBroker
 
 To learn how to use StoreBroker now that it's all setup, head on over to [README.md](../README.md).

Documentation/USAGE.md

@@ -9,7 +9,7 @@
     *   [Logging](#logging)
     *   [Common Switches](#common-switches)
     *   [Accessing the Portal](#accessing-the-portal)
-*   [Creating Your Payload](#creating-your-payload)
+*   [Creating Your Application Payload](#creating-your-application-payload)
 *   [Creating A New Application Submission](#creating-a-new-application-submission)
     *    [The Easy Way](#the-easy-way)
     *    [Manual Submissions](#manual-submissions)
@@ -20,6 +20,7 @@
     *   [Flighting Commands](#flighting-commands)
 *   [In App Products](#in-app-products)
     *   [IAP Overview](#iap-overview)
+    *   [Creating Your IAP Payload](#creating-your-iap-payload)
     *   [IAP Commands](#iap-commands)
 *   [Using INT vs PROD](#using-int-vs-prod)
 *   [Telemetry](#telemetry)
@@ -95,7 +96,7 @@ to the appropriate page on the dev portal for what you're looking for, make use
    you'll be taken to the page where you can view/edit the flight that the flight submission is
    associated with.
 
-## Creating Your Payload
+## Creating Your Application Payload
 
 In StoreBroker, a "payload" is a combination of a json file and a zip file.  The **json** file
 has the entire content of a Windows Store Submission.  This content _could_ be submitted as-is,
@@ -115,7 +116,7 @@ following the instructions in [SETUP.md](SETUP.md):
 
 Generating the submission request JSON/zip package is done with
 
-    New-SubmissionPackage <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.
 
@@ -474,7 +475,7 @@ submissions).
 **Return Values**:
 `Update-ApplicationFlightSubmission` returns back two values to you at its completion:
 the new submission id, and the UploadURL.  You can use that UploadUrl to upload your submission's
-.zip with `Upload-SubmissionPackage`, in the event that you didn't specify the `PackagePath`
+.zip with `Upload-SubmissionPackage` in the event that you didn't specify the `PackagePath`
 or want to upload it again.
 
 #### Other Common Flight-related Tasks:
@@ -534,20 +535,57 @@ In-App Products (IAP's) are additional features that are offered to users of you
 In the Store, IAP's are considered siblings to Applications, as opposed to children,
 because the same IAP can be associated with more than one Application.
 
-### IAP Commands
+### Creating Your IAP Payload
+
+> These instructions very closely mirror those for [Creating Your Application Payload](#creating-your-application-payload),
+> by design.
+
+In StoreBroker, a "payload" is a combination of a json file and a zip file.  The **json** file
+has the entire content of a Windows Store Submission.  This content _could_ be submitted as-is,
+but usually only selected portions of it are "patched" into a new submission.  The **zip** file
+usually has the icons for the localized listings, although depending on how you create your payload,
+those might be missing.
+
+To create your payload, you need to have the following (which you should already have from
+following the instructions in [SETUP.md](SETUP.md):
+ * [StoreBroker config file](SETUP.md#getting-your-iap-config)
+ * [PDP files](SETUP.md#getting-your-iap-pdps)
+ * Icons (if you use them in your listing)
+
+> In order to use New-InAppProductSubmissionPackage, it is highly recommended that you read the
+> documentation (`Get-Help New-InAppProductSubmissionPackage -Full`) and read the
+> documentation in the configuration file.
+
+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>  
 
-> As noted in [limitations](../README.md#limitations), we have full support for IAP's, but unlike
-> App Submissions and Flights, we do not yet have a [PDP](PDP.md) format for IAP
-> metadata, nor a function like `New-SubmissionPackage` to generate the json/zip payload that the
-> IAP functions require.  This is [on our backlog](https://github.com/Microsoft/StoreBroker/issues/3).
-> If you use IAP's and would like to help, please refer to [CONTRIBUTING.md](../CONTRIBUTING.md).
+> Items in brackets ('[]') are optional.
+
+The `-Release` parameter is technically optional, depending on how you choose to store your PDP
+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).
+
+### IAP Commands
 
 You'll find the layout of these commands to mimic those for Applications and Flights.
 For every Get-* command there is a corresponding Format-* command that you can leverage.
 
 > All IAP commands use the fully-spelled-out "InAppProduct".  Even though PowerShell supports tab
 > completion at the commandline, aliases also exist for all of these commands as well.  Any time
-> you see a command that has the phrase "InAppProduct", there exits an alias for that same command
+> you see a command that has the phrase "InAppProduct", there exists an alias for that same command
 > that replaces that phrase with "Iap" (e.g. Get-InAppProducts -> Get-Iaps).
 
 The basic syntax looks of the update command looks like this:
@@ -619,13 +657,13 @@ fully override the publication and visibility of your IAP submission.
 
 `Update-InAppProductSubmission` is a convenience method that wraps a number of individual
 commands into a single command.  If you want to understand exactly what it does, refer to the
-previous section on ["manual submissions."](#manual-submissions) (similar methods exist for IAP
-submissions).
+previous section on ["manual submissions"](#manual-submissions) for applications (similarly-named
+methods exist for IAP submissions).
 
 **Return Values**:
 `Update-InAppProductSubmission` returns back two values to you at its completion:
 the new submission id, and the UploadURL.  You can use that UploadUrl to upload your submission's
-.zip with `Upload-SubmissionPackage`, in the event that you didn't specify the `PackagePath`
+.zip with `Upload-SubmissionPackage` in the event that you didn't specify the `PackagePath`
 or want to upload it again.
 
 #### Other Common IAP-related Tasks:
@@ -648,10 +686,15 @@ To create a new IAP:
     New-InAppProduct -ProductId <productId> -ProductType <productType> -ApplicationIds <applicationIds>
 
 where
- * **`<applicationIds>`** is a comma-separated list of ApplicationIds that should be able to offer
-   this IAP.
  * **`<productId>`** is a unique name that you provide to refer to this IAP in this API and in your
    actual application sourcecode.
+ * **`<productType>`** is either `Consumable` for a "Developer managed consumable", or
+   `Durable` for a "durable managed consumable".  Please note that at this time, although the
+   Developer Web Portal supports the creation of "Store Managed Consumables", the Store Submission
+   API _does not_.  For more information on these types, see the online
+   [documentation](http://go.microsoft.com/fwlink/?LinkId=787042).
+ * **`<applicationIds>`** is a comma-separated list of ApplicationIds that should be able to offer
+   this IAP.
 
 To delete an IAP: