Update the module to 1.20.1 and improve documentation (#211)

* Updates the module version number

* Improved the installation documentation (to note that PowerShellGallery
is now an option).  Also did some other minor documentation cleanup.
This commit is contained in:
Howard Wolosky 2020-08-27 13:49:18 -07:00 коммит произвёл GitHub
Родитель e8c052842c
Коммит 93787985f7
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
5 изменённых файлов: 358 добавлений и 130 удалений

Просмотреть файл

@ -1,6 +1,31 @@
# StoreBroker PowerShell Module
## Changelog
## [1.20.1](https://github.com/Microsoft/StoreBroker/tree/1.20.1) - (2020/08/27)
### Features:
+ Added the ability to suppress the telemetry warning shown at the start of each new StoreBroker
session by setting `$global:SBSuppressTelemetryWarning=$true`.
[[pr]](https://github.com/Microsoft/StoreBroker/pull/206) | [[cl]](https://github.com/microsoft/StoreBroker/commit/49e289e1c10e581fe5638b1be592a7b131acb96a)
### Fixes
- Removed erroneous call to `Get-GitHubConfiguration` which was causing an ignorable exception
initializing the telemetry stack.
[[pr]](https://github.com/Microsoft/StoreBroker/pull/204) | [[cl]](https://github.com/microsoft/StoreBroker/commit/20d94bb463bbf300dcf25a7248dfb6a0a138cdcc)
- Fixed how `targetPublishDate` was being populated in new configuration files (as it was being
converted into the JSON file incorrectly.
[[pr]](https://github.com/Microsoft/StoreBroker/pull/180) | [[cl]](https://github.com/microsoft/StoreBroker/commit/658cba691b9bace2cf87d4d99e555f14fbb3d566)
- Partner Center changed its URL scheme, and so some of the generated URL's that StoreBroker uses
needed to be updated. This also deprecates the ShowFlight switch for Open-DevPortal as
there no longer appears to be an equivalent destination in the updated Partner Center.
[[pr]](https://github.com/Microsoft/StoreBroker/pull/209) | [[cl]](https://github.com/microsoft/StoreBroker/commit/e8c052842c4ab94f4ae34797a5a8ceb4826039f8)
Authors:
* [**@HowardWolosky**](https://github.com/HowardWolosky)
* [**@riverar**](https://github.com/riverar)
## [1.20.0](https://github.com/Microsoft/StoreBroker/tree/1.20.0) - (2020/08/23)
### Features:

Просмотреть файл

@ -7,12 +7,14 @@
* [Overview](#overview)
* [Installation](#installation)
* [ExecutionPolicy](#executionpolicy)
* [Choosing a Folder](#choosing-a-folder)
* [Get the Module](#get-the-module)
* [Using Git](#using-git)
* [Using NuGet](#using-nuget)
* [Downloading a Zip](#downloading-a-zip)
* [PowerShellGallery](#powershellgallery)
* [NuGet](#nuget)
* [Installing From GitHub](#installing-from-github)
* [ExecutionPolicy](#executionpolicy)
* [Choosing a Folder](#choosing-a-folder)
* [Get the Module](#get-the-module)
* [Using Git](#using-git)
* [Downloading a Zip](#downloading-a-zip)
* [Automatic Dependency Downloads](#automatic-dependency-downloads)
* [Setup](#setup)
* [Prerequisites](#prerequisites)
@ -57,24 +59,97 @@ potential confusion. At a high level, all you're doing is:
The following section describes how to configure your system for use with StoreBroker,
and lists the available options for installing the module contents.
### ExecutionPolicy
### PowerShellGallery
[![powershellgallery](https://img.shields.io/powershellgallery/v/StoreBroker)](https://www.powershellgallery.com/packages/StoreBroker)
The easiest way to install StoreBroker is with
[PowerShellGallery](https://www.powershellgallery.com/packages/StoreBroker).
```powershell
Install-Module -Name StoreBroker
```
If you already have it installed and want to get the latest version, you can use:
```powershell
Update-Module -Name StoreBroker
```
> If you'll be installing this on a machine that frequently gets reimaged, you may wish to first
> call `Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted` to trust PowerShellGallery
> modules and thus avoid any prompting during installation.
### NuGet
[![nuget](https://img.shields.io/nuget/v/Microsoft.Windows.StoreBroker)](https://www.nuget.org/packages/Microsoft.Windows.StoreBroker/)
An alternate way to download a versioned copy of StoreBroker is to get it through
[NuGet](https://www.nuget.org/packages/Microsoft.Windows.StoreBroker/). This might make sense
if you're incorporating it as part of a build step.
We continue to make the NuGet available since we've provided a NuGet for StoreBroker ever since
StoreBroker was released back in 2016, however now that it is available for installation via
[PowerShellGallery](#powershellgallery), there really isn't a compelling reason to use the NuGet
installation method anymore.
Assuming you have the NuGet command-line utility
[installed](https://dist.nuget.org/index.html) on your machine:
```powershell
$desiredPath = c:\StoreBroker # Set this to whatever location you want StoreBroker to be installed to
Push-Location -Path $desiredPath
nuget install Microsoft.Windows.StoreBroker
Push-Location -Path ".\Microsoft.Windows.StoreBroker.*\StoreBroker"
Import-Module .\StoreBroker.psd1
```
This will install the lastest available version of the StoreBroker module as a directory named
`Microsoft.Windows.StoreBroker.<version>`, and then import the module for use.
> The StoreBroker NuGet package contains *only* the scripts needed to use StoreBroker. For
> any documentation, get started with [the README.md](../README.md).
> Note that the NuGet package installation option is a *snapshot* of the StoreBroker module,
> and is more difficult to keep up-to-date. To sync your local module with the newest package,
> you will need to delete the folder created above and follow the installation instructions
> again.
### Installing From GitHub
The previous two approaches allow you to download versioned snapshots of StoreBroker where the
files have been digitally signed by Microsoft. An alternative approach is to simply get the
module directly from GitHub (either by cloning the repo or by downloading a zip of the sources).
#### ExecutionPolicy
Since the files from GitHub are _not_ digitially signed (we only sign them when we release to
[PowerShellGallery](#powershellgallery) and [NuGet.org](#nuget)), you may need to update the
`PowerShell ExecutionPolicy` on your machine to be `RemoteSigned` (which means that PowerShell
scripts that are local to your machine don't need to be signed in order to execute).
Update the `PowerShell ExecutionPolicy` to be `RemoteSigned` (which means
that PowerShell scripts that are local to your machine don't need to be signed in order to execute).
From an **Administrator** PowerShell console, run the following command:
Set-ExecutionPolicy RemoteSigned -Force
```powershell
Set-ExecutionPolicy RemoteSigned -Force
```
### Choosing a Folder
#### Choosing a Folder
You need to choose a folder that you're going to store the module in. We recommend choosing to
use a **new sub-folder** within one of the folders in your `$env:PSModulePath`. By default,
even if the folder doesn't exist yet,
`Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'WindowsPowerShell\Modules'`
is one of those folders -- this is the one that we'd recommend that you use. If it doesn't exist yet, just
go ahead and create it:
even if the folder doesn't exist yet, the following path is one of those folders and is the one that
we'd recommend that you use:
New-Item -Type Directory -Force -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'WindowsPowerShell\Modules\StoreBroker')
```powershell
Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'WindowsPowerShell\Modules'
```
If it doesn't exist yet, just go ahead and create it:
```powershell
New-Item -Type Directory -Force -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'WindowsPowerShell\Modules\StoreBroker')
```
If you follow that advice, then the module will automatically be available in any PowerShell
console session implicitly. If you choose to store the module somewhere else, then you will need
@ -86,16 +161,19 @@ StoreBroker command will work.
> `Import-Module` command. When storing the module within a `$env:PSModulePath` folder, PowerShell
> just figures that out for you.
### Get The Module
#### Get The Module
There are currently three options for installing the StoreBroker module.
We recommend the Git option, as it is the simplest for staying up-to-date with StoreBroker changes.
There are two options for getting the code from GitHub: cloning with get and a zip download.
We recommend the cloning with git option, as it is the simplest for staying up-to-date with
StoreBroker changes.
#### Using Git
##### Using Git
Assuming you already have `git` on your machine, just run:
git clone https://github.com/Microsoft/StoreBroker.git <folderFromStep2>
```powershell
git clone https://github.com/microsoft/StoreBroker.git <StoreBrokerCloneFolder>
```
You'll then want to update your PowerShell profile to just run a `git pull` on that folder
every time you open your console window in order to keep it up to date.
@ -103,47 +181,33 @@ every time you open your console window in order to keep it up to date.
> Your PowerShell Profile is a ps1 script that PowerShell automatically runs every time a
> new PowerShell console window is opened.
notepad $profile
```powershell
notepad $profile
```
That will open your profile. If it doesn't exist, accept Notepad's prompts to create the file.
From there, just add the following:
Push-Location -Path "<folderFromStep2>"
git pull
Pop-Location
```powershell
Push-Location -Path "<StoreBrokerCloneFolder>"
git pull
Pop-Location
```
#### Using NuGet
Assuming you have the NuGet command-line utility
[installed](https://dist.nuget.org/index.html) on your machine:
Push-Location -Path "<folderFromStep2>"
nuget install Microsoft.Windows.StoreBroker
Move-Item -Path ".\Microsoft.Windows.StoreBroker.*" -Destination ".\StoreBroker"
This will install the lastest available version of the StoreBroker module as a directory named
`Microsoft.Windows.StoreBroker.<version>`, then rename that directory to `StoreBroker`.
> The StoreBroker NuGet package contains *only* the scripts needed to use StoreBroker. For
> any documentation, get started with [the README.md](../README.md).
> Note that the NuGet package installation option is a *snapshot* of the StoreBroker module,
> and is more difficult to keep up-to-date. To sync your local module with the newest package,
> you will need to delete the folder created above and follow the installation instructions
> again.
#### Downloading A Zip
##### Downloading A Zip
Download the following file to get a snapshot of the current state of the module:
https://github.com/Microsoft/StoreBroker/archive/master.zip
https://github.com/microsoft/StoreBroker/archive/master.zip
Unzip that to the `<folderFromStep2>`.
Unzip that to the `<StoreBrokerFolder>`.
Because you downloaded the file the zip, you may have to "unblock" the contents and tell your
operating system that you trust the zip's contents:
Get-ChildItem -Recurse -File -Path "<folderFromStep2>" | ForEach-Object { Unblock-File -Path $_.FullName }
```powershell
Get-ChildItem -Recurse -File -Path "<StoreBrokerFolder>" | ForEach-Object { Unblock-File -Path $_.FullName }
```
> For more information on `Unblock-File`, review [its documentation](https://technet.microsoft.com/en-us/library/hh849924.aspx)
@ -263,18 +327,24 @@ they are needed.
In order to cache the tenantId, call:
Set-StoreBrokerAuthentication -TenantId <tenantId>
```powershell
Set-StoreBrokerAuthentication -TenantId <tenantId>
```
That will cache the `TenantId` for that session, and it will also prompt you for the
`ClientId` and `ClientSecret` so it can cache those in the same session as well.
If you would rather be prompted every time for those two values, you can call:
Set-StoreBrokerAuthentication -TenantId <tenantId> -OnlyCacheTenantId
```powershell
Set-StoreBrokerAuthentication -TenantId <tenantId> -OnlyCacheTenantId
```
When using `Set-StoreBrokerAuthentication`, it is only caching those values for the current
PowerShell session. They can be cleared by simply closing your PowerShell window, or by calling:
Clear-StoreBrokerAuthentication
```powershell
Clear-StoreBrokerAuthentication
```
If you want to be use this module without requiring any user-interaction at the console,
it is necessary to leverage `Set-StoreBrokerAuthentication -Credential` and provide
@ -287,14 +357,18 @@ One way to do this would be the following:
password into a plain-text file, and only the same user logged-in to the exact same computer
will be able to decrypt it.
$cred.Password | ConvertFrom-SecureString | Set-Content -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'clientSecret.txt')
```powershell
$cred.Password | ConvertFrom-SecureString | Set-Content -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'clientSecret.txt')
```
4. When you want to create the credentials yourself later on and authenticate (being sure to
replace `<tenantId>` and `<clientId>` with the proper values):
$clientSecret = Get-Content -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'clientSecret.txt') | ConvertTo-SecureString
$cred = New-Object System.Management.Automation.PSCredential "<clientId>", $clientSecret
Set-StoreBrokerAuthentication -TenantId <tenantId> -Credential $cred
```powershell
$clientSecret = Get-Content -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'clientSecret.txt') | ConvertTo-SecureString
$cred = New-Object System.Management.Automation.PSCredential "<clientId>", $clientSecret
Set-StoreBrokerAuthentication -TenantId <tenantId> -Credential $cred
```
> **PowerShell Tip**
>
@ -327,7 +401,9 @@ For more information on how to deploy your own Proxy, refer to its [documentatio
If you have a Proxy up and running, then to use it, simply call:
Set-StoreBrokerAuthentication -UseProxy -ProxyEndpoint <proxyUri>
```powershell
Set-StoreBrokerAuthentication -UseProxy -ProxyEndpoint <proxyUri>
```
where `<proxyUri>` is the base part of your Uri (like `https://mystorebrokerproxy`).
@ -344,7 +420,9 @@ That setting (being configured to use the proxy) will be stored for the duration
To stop authenticating with the proxy, at any time simply close your PowerShell console window, or
call:
Clear-StoreBrokerAuthentication
```powershell
Clear-StoreBrokerAuthentication
```
### Getting Your AppId
@ -361,12 +439,16 @@ Alternatively, you can find this value directly with StoreBroker by running the
getting the `id` that is shown there (it looks like this: `0ABCDEF12345`).
That's your `AppId` (replace `<appName>` with all or part your app's name to limit the results):
Get-Applications -GetAll | Where-Object primaryName -like "*<appName>*" | Format-Application
```powershell
Get-Applications -GetAll | Where-Object primaryName -like "*<appName>*" | Format-Application
```
If you run into issues with this command, it's possible that you're having trouble with your search
with `Where-Object`. Instead, just try running this:
Get-Applications -GetAll | Format-Applications
```powershell
Get-Applications -GetAll | Format-Applications
```
> The Windows Store Submission API does not allow for the *creation* of new apps.
> To use StoreBroker, you must have already created **and published** an app submission via the
@ -393,7 +475,9 @@ listing for.
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 app's PDP files based on your current published submission.
.\Extensions\ConvertFrom-ExistingSubmission.ps1 -AppId <appId> -Release <release> -PdpFileName <pdpFileName> -OutPath <outPath>
```powershell
.\Extensions\ConvertFrom-ExistingSubmission.ps1 -AppId <appId> -Release <release> -PdpFileName <pdpFileName> -OutPath <outPath>
```
Where:
* `<appId>` is your app's ID.
@ -537,7 +621,9 @@ To run the next command, you'll need your [AppId](#getting-your-appid) from abov
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
```powershell
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.
@ -565,7 +651,9 @@ Store listing for.
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>
```powershell
.\Extensions\ConvertFrom-ExistingIapSubmission.ps1 -IapId <iapId> -Release <release> -PdpFileName <pdpFileName> -OutPath <outPath>
```
Where:
* `<iapId>` is your IAP's ID.
@ -633,7 +721,9 @@ While not required, there are other things that you can do to make your usage ev
global variable for it in your `$profile` so that you can just refer to it by name with
tab-completion? Just run `notepad $profile` to open up your profile, and add the following:
$global:appName = '<appId>'
```powershell
$global:appName = '<appId>'
```
set `appName` to whatever you want, and replace `<appId>` with your actual
[appId](#getting-your-appid). Then, in any new PowerShell console window, you can just start

Просмотреть файл

@ -39,16 +39,22 @@ Once loaded, usage is straight-forward for PowerShell users.
To see all of the available Commands, simply run:
(Get-Module StoreBroker).ExportedCommands
```powershell
(Get-Module StoreBroker).ExportedCommands
```
All Commands are fully documented, so to understand one better, simply run **Get-Help** on it.
For instance:
Get-Help Get-Applications -ShowWindow
```powershell
Get-Help Get-Applications -ShowWindow
```
or
Get-Help Get-Applications -Full
```powershell
Get-Help Get-Applications -Full
```
### Formatting Results
@ -82,7 +88,9 @@ when the module is loaded.
log file for each StoreBroker process. An easy way to view the filtered
entries for a session is (replacing `PID` with the PID that you are interested in):
Get-Content -Path $global:SBLogPath -Encoding UTF8 | Where { $_ -like '*[[]PID[]]*' }
```powershell
Get-Content -Path $global:SBLogPath -Encoding UTF8 | Where { $_ -like '*[[]PID[]]*' }
```
> **PowerShell Tip**
@ -129,7 +137,9 @@ All commands also support the `-WhatIf` switch (along with the corresponding `-C
Sometimes, you just want to look at the webpage instead of the commandline. For quick access
to the appropriate page on the dev portal for what you're looking for, make use of
Open-DevPortal -AppId <appId> [-SubmissionId <submissionId> [-ShowFlight]]
```powershell
Open-DevPortal -AppId <appId> [-SubmissionId <submissionId> [-ShowFlight]]
```
* If you just specify `AppId`, you'll be taken directly to that app page within the dev portal.
* If you also specify `SubmissionId`, you can view that specific submission in the dev portal
@ -158,15 +168,19 @@ 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>
```powershell
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.
The `-Release` parameter is technically optional, depending on how you choose to store your PDP
files. For more info, run:
Get-Help New-SubmissionPackage -Parameter PdpRootPath
Get-Help New-SubmissionPackage -Parameter Release
```powershell
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
@ -204,7 +218,9 @@ order for anything to be changed.**
The basic syntax looks of the command looks like this:
Update-ApplicationSubmission -AppId <appId> -SubmissionDataPath ".\submission.json" -PackagePath ".\package.zip" -AutoCommit -Force
```powershell
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:
@ -352,41 +368,55 @@ manually.
* Clone the existing published submission so that you can generate an update.
$sub = New-ApplicationSubmission -AppId <appId> [-Force]
```powershell
$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.
* 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
```powershell
$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"
applicable values from `$json` into `$sub`.
* For example, here's how you can change a simple content that has a single value:
$sub.hardwarePreferences = $json.hardwarePreferences
```powershell
$sub.hardwarePreferences = $json.hardwarePreferences
```
* For nested content, you will need to ensure that all nested values are applied. The easiest way to do this
is to inspect the json and then manually assign the nested values. For a more generic way, you can implement
a function similar to `DeepCopy-Object` in Helpers.ps1.
$sub.allowTargetFutureDeviceFamilies.Xbox = $json.allowTargetFutureDeviceFamilies.Xbox
$sub.allowTargetFutureDeviceFamilies.Team = $json.allowTargetFutureDeviceFamilies.Team
... repeat for all nested values ...
```powershell
$sub.allowTargetFutureDeviceFamilies.Xbox = $json.allowTargetFutureDeviceFamilies.Xbox
$sub.allowTargetFutureDeviceFamilies.Team = $json.allowTargetFutureDeviceFamilies.Team
#... repeat for all nested values ...
```
* Send the updated submission content so that the API knows what should be updated:
Set-ApplicationSubmission -AppId $appId -UpdatedSubmission $sub
```powershell
Set-ApplicationSubmission -AppId $appId -UpdatedSubmission $sub
```
* If you're updating screenshots or packages, you'll need to upload the supporting .zip file:
Set-SubmissionPackage -PackagePath <pathToYourZip> -UploadUrl ($sub.fileUploadUrl)
```powershell
Set-SubmissionPackage -PackagePath <pathToYourZip> -UploadUrl ($sub.fileUploadUrl)
```
* Tell the API that you're done with the submission and to start validation / certification:
Complete-ApplicationSubmission -AppId $appId -SubmissionId ($sub.id)
```powershell
Complete-ApplicationSubmission -AppId $appId -SubmissionId ($sub.id)
```
The `-AutoCommit` switch should not be confused with publishing of the submission. A submission
won't enter into certification until it has been "committed", and a submission can only be committed
@ -408,19 +438,27 @@ in the [Store documentation](https://docs.microsoft.com/en-us/windows/uwp/publis
To view the current package rollout status:
Get-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
```powershell
Get-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
```
To update the current package rollout percentage:
Update-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId> -Percentage <percentage>
```powershell
Update-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId> -Percentage <percentage>
```
To halt the current package rollout:
Stop-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
```powershell
Stop-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
```
To finalize the current package rollout:
Complete-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
```powershell
Complete-ApplicationSubmissionPackageRollout -AppId <appId> -SubmissionId <submissionId>
```
## Monitoring A Submission
@ -435,7 +473,9 @@ just in case you're away from the computer when the status changes.
The basic syntax looks like this:
Start-SubmissionMonitor -AppId <appId> -SubmissionId <submissionId>
```powershell
Start-SubmissionMonitor -AppId <appId> -SubmissionId <submissionId>
```
This will just start a loop that checks every 60 seconds to see if the status has changed for
this submission. All changes will be printed to the console window. The monitoring will
@ -466,11 +506,15 @@ If you want to have it also email you, you must first configure StoreBroker for
Then you can add a list of one or more email addresses for it to notify
Start-SubmissionMonitor -AppId <appId> -SubmissionId <submissionId> -EmailNotifyTo <emailAddress>
```powershell
Start-SubmissionMonitor -AppId <appId> -SubmissionId <submissionId> -EmailNotifyTo <emailAddress>
```
Multiple email addresses are separated by a comma
Start-SubmissionMonitor -AppId <appId> -SubmissionId <submissionId> -EmailNotifyTo <emailAddress1>,<emailAddress2>
```powershell
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
@ -523,7 +567,9 @@ update.
The basic syntax looks of the command looks like this:
Update-ApplicationFlightSubmission -AppId <appId> -FlightId <flightId> -SubmissionDataPath ".\submission.json" -PackagePath ".\package.zip" -AutoCommit -Force
```powershell
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:
@ -647,11 +693,15 @@ or want to upload it again.
View all the flights assigned to a given app:
Get-ApplicationFlights -AppId <appId> | Format-ApplicationFlights
```powershell
Get-ApplicationFlights -AppId <appId> | Format-ApplicationFlights
```
View the details of a specific flight
Get-ApplicationFlight -AppId <appId> -FlightId <flightId> | Format-ApplicationFlight
```powershell
Get-ApplicationFlight -AppId <appId> -FlightId <flightId> | Format-ApplicationFlight
```
##### Creating and/or Removing Flights
@ -663,7 +713,9 @@ View the details of a specific flight
To create a new flight:
New-ApplicationFlight -AppId <appId> -FriendlyName <name> [-RankHigherThan <name>] [-Groupids <id>]
```powershell
New-ApplicationFlight -AppId <appId> -FriendlyName <name> [-RankHigherThan <name>] [-Groupids <id>]
```
If you don't specify the friendly name of an existing flight to rank this higher than, it will be
ranked highest of all current flights.
@ -673,18 +725,24 @@ ranked highest of all current flights.
To delete a flight:
Remove-ApplicationFlight -AppId <appId> -FlightId <flightId>
```powershell
Remove-ApplicationFlight -AppId <appId> -FlightId <flightId>
```
##### Flight Submissions
To view an existing flight submission:
Get-ApplicationFlightSubmission -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId> | Format-ApplicationFlightSubmission
```powershell
Get-ApplicationFlightSubmission -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId> | Format-ApplicationFlightSubmission
```
To delete a flight submission:
Remove-ApplicationFlightSubmission -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```powershell
Remove-ApplicationFlightSubmission -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```
To monitor a flight submission:
Follow the same steps for [monitoring an application submission](#monitoring-a-submission), but
@ -697,19 +755,27 @@ in the [Store documentatin](https://docs.microsoft.com/en-us/windows/uwp/publish
To view the current package rollout status:
Get-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```powershell
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>
```powershell
Update-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId> -Percentage <percentage>
```
To halt the current package rollout:
Stop-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```powershell
Stop-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```
To finalize the current package rollout:
Complete-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```powershell
Complete-ApplicationFlightSubmissionPackageRollout -AppId <appId> -FlightId <flightId> -SubmissionId <submissionId>
```
## In App Products
@ -742,15 +808,19 @@ 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>
```powershell
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.
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
```powershell
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
@ -774,7 +844,9 @@ For every Get-* command there is a corresponding Format-* command that you can l
The basic syntax looks of the update command looks like this:
Update-InAppProductSubmission -IapId <iapId> -SubmissionDataPath ".\submission.json" -PackagePath ".\package.zip" -AutoCommit -Force
```powershell
Update-InAppProductSubmission -IapId <iapId> -SubmissionDataPath ".\submission.json" -PackagePath ".\package.zip" -AutoCommit -Force
```
> 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
@ -857,18 +929,24 @@ or want to upload it again.
View all the IAP's available in the dev account:
Get-InAppProducts | Format-InAppProducts
```powershell
Get-InAppProducts | Format-InAppProducts
```
View all the IAP's that a specific app offers:
Get-ApplicationInAppProducts -AppId <appId> | Format-ApplicationInAppProducts
```powershell
Get-ApplicationInAppProducts -AppId <appId> | Format-ApplicationInAppProducts
```
##### Creating and/or Removing IAP's
To create a new IAP:
New-InAppProduct -ProductId <productId> -ProductType <productType> -ApplicationIds <applicationIds>
```powershell
New-InAppProduct -ProductId <productId> -ProductType <productType> -ApplicationIds <applicationIds>
```
where
* **`<productId>`** is a unique name that you provide to refer to this IAP in this API and in your
@ -883,18 +961,24 @@ where
To delete an IAP:
Remove-InAppProduct -IapId <iapId>
```powershell
Remove-InAppProduct -IapId <iapId>
```
##### IAP Submissions
To view an existing IAP submission:
Get-InAppProductSubmission -IapId <iapId> -SubmissionId <submissionId> | Format-InAppProductSubmission
```powershell
Get-InAppProductSubmission -IapId <iapId> -SubmissionId <submissionId> | Format-InAppProductSubmission
```
To delete an IAP submission:
Remove-InAppProductSubmission -IapId <iapId> -SubmissionId <submissionId>
```powershell
Remove-InAppProductSubmission -IapId <iapId> -SubmissionId <submissionId>
```
To monitor an IAP submission:
Follow the steps in [monitoring a submission](#monitoring-a-submission), and be sure to include
@ -1010,7 +1094,9 @@ If you want to try using this module in the INT (internal / testing) environment
the changes you make will never be seen by the outside world), then simply set this global session
variable before performing any operation:
$global:SBUseInt = $true
```powershell
$global:SBUseInt = $true
```
The effect of that value will last for the duration of your session (until you close your
console window) or until you change its value to `$false`.
@ -1030,13 +1116,17 @@ information, refer to the [Privacy Policy](../README.md#privacy-policy) and
With every new PowerShell session, StoreBroker will show you a reminder that telemetry is being
used. You can suppress this reminder in the future by setting the following:
$global:SBSuppressTelemetryReminder = $true
```powershell
$global:SBSuppressTelemetryReminder = $true
```
We recommend that you always leave the telemetry feature enabled, but a situation may arise where
it must be disabled for some reason. In this scenario, you can disable telemetry by setting
the following global variable:
$global:SBDisableTelemetry = $true
```powershell
$global:SBDisableTelemetry = $true
```
The effect of that value will last for the duration of your session (until you close your
console window), or until you change its value back to its default of `$false`.
@ -1057,7 +1147,9 @@ in the form of an SHA512 Hash (to protect PII (personal identifiable information
The hashing of the above items can be disabled (meaning that the plaint-text data will be reported
instead of the _hash_ of the data) by setting
$global:SBDisablePiiProtection = $true
```powershell
$global:SBDisablePiiProtection = $true
```
Similar to `SBDisableTelemetry`, the effect of this value will only last for the duration of
your session (until you close your console window), or until you change its value back to its
@ -1065,7 +1157,9 @@ default of `$false`.
Finally, the Application Insights Key that the telemetry is reported to is exposed as
$global:SBApplicationInsightsKey
```powershell
$global:SBApplicationInsightsKey
```
It is requested that you do not change this value, otherwise the telemetry will not be reported to
us for analysis. We expose it here for complete transparency.
@ -1090,19 +1184,25 @@ us for analysis. We expose it here for complete transparency.
(hence, the name of the switch: `-AddPackages`). If you want to clean these up from the
commandline, jsut do the following:
$appId = <yourAppId>
$sub = New-ApplicationSubmission -AppId $appId -Force
for ($i = 0; $i -lt $sub.applicationPackages.Count; $i++) { Write-Host "`$sub.applicationPackages[$i] :" -ForegroundColor Yellow; $sub.applicationPackages[$i] }
```powershell
$appId = <yourAppId>
$sub = New-ApplicationSubmission -AppId $appId -Force
for ($i = 0; $i -lt $sub.applicationPackages.Count; $i++) { Write-Host "`$sub.applicationPackages[$i] :" -ForegroundColor Yellow; $sub.applicationPackages[$i] }
```
> At that point, you'll see all the packages in your current submisssion,
> and the index that they're at. For any package that you want to delete, just do the following:
> At that point, you'll see all the packages in your current submisssion,
> and the index that they're at. For any package that you want to delete, just do the following:
$sub.applicationPackages[<index>].FileStatus = 'PendingDelete'
```powershell
$sub.applicationPackages[<index>].FileStatus = 'PendingDelete'
```
> After you've updated all the packages that you want, just run the following commands:
> After you've updated all the packages that you want, just run the following commands:
Set-ApplicationSubmission -AppId $appId -UpdatedSubmission $sub
Commit-ApplicationSubmission -AppId $appId -SubmissionId ($sub.id)
```powershell
Set-ApplicationSubmission -AppId $appId -UpdatedSubmission $sub
Commit-ApplicationSubmission -AppId $appId -SubmissionId ($sub.id)
```
* **Does StoreBroker support adding region-specific listings for languages that the app itself
doesn't directly support? (e.g. Can I specify a listing in French, even if my app is English-only)?**
@ -1139,15 +1239,17 @@ 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
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
MasterJsonPath, except that it will also include the packages that were defined in
AdditionalJsonPath and its zip. This payload can then be provided to StoreBroker
for submission to the Store as a single submission.
```powershell
Join-SubmissionPackage -MasterJsonPath <path> -AdditionalJsonPath <path> -OutJsonPath <path> -AddPackages
```
* **Can I have different screenshots for different platforms?**
* Yes. Since the PDP is localization-centric, it tracks _captions_, and each caption _must_

Просмотреть файл

@ -1,5 +1,8 @@
# StoreBroker PowerShell Module
[![powershellgallery](https://img.shields.io/powershellgallery/v/StoreBroker)](https://www.powershellgallery.com/packages/StoreBroker)
[![nuget](https://img.shields.io/nuget/v/Microsoft.Windows.StoreBroker)](https://www.nuget.org/packages/Microsoft.Windows.StoreBroker/)
#### Table of Contents
* [Overview](#overview)
@ -7,6 +10,7 @@
* [Goals](#goals)
* [Current Functionality](#current-functionality)
* [Prerequisites](#prerequisites)
* [What's New](#whats-new)
* [Installation and Setup](#installation-and-setup)
* [Usage](#usage)
* [Developing and Contributing](#developing-and-contributing)
@ -83,6 +87,13 @@ or higher.
----------
## What's New
Check out [CHANGELOG.md](./CHANGELOG.md) to review the details of the current release as well as
all past releases.
----------
## Installation and Setup
Refer to [SETUP.md](Documentation/SETUP.md) for the Installation and Setup instructions.

Просмотреть файл

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