Update docs and examples (#505)

Author: mdanish-kh

.github/ISSUE_TEMPLATE/Bug_Report.yml

@@ -43,14 +43,10 @@ body:
     attributes:
       label: Environment
       placeholder: |
-        [wingetcreate --help]
+        [wingetcreate info]
         Windows Package Manager Manifest Creator version
-
-        [winget --info]
-        Windows Package Manager version
+        Operating System: Windows.Desktop version
         System Architecture: CPU architecture
-        Windows: Windows.Desktop version
-        Package: Microsoft.DesktopAppInstaller version
 
         Any other software?
       render: shell

NOTICE.txt

@@ -521,6 +521,28 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
+---------------------------------------------------------
+
+---------------------------------------------------------
+
+Microsoft.WindowsPackageManager.Utils 1.7.2 - MIT
+
+
+(c) Microsoft Corporation
+CopyrightUrl ShortDescription
+Copyright (c) Microsoft Corporation
+Copyright PackageUrl ShortDescription CopyrightUrl
+
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 ---------------------------------------------------------
 
 ---------------------------------------------------------

README.md

@@ -68,6 +68,7 @@ You can use WingetCreate to update your existing app manifest as part of your CI
 - [PowerToys](https://github.com/microsoft/PowerToys/blob/main/.github/workflows/package-submissions.yml)
 - [Terminal](https://github.com/microsoft/terminal/blob/main/.github/workflows/winget.yml)
 
+You can also check out this [episode of Open at Microsoft](https://learn.microsoft.com/en-us/shows/open-at-microsoft/wingetcreate-keeping-winget-packages-up-to-date) where we cover the same topic.
 
 ### Using the standalone exe:
 
@@ -89,7 +90,8 @@ Or you can utilize a PowerShell task and run the following script.
     .\dotnet-install.ps1 -Runtime dotnet -Architecture x64 -Version 6.0.13 -InstallDir $env:ProgramFiles\dotnet
 ```
 
-> **Note**: Make sure your build machine has the [Microsoft Visual C++ Redistributable for Visual Studio](https://support.microsoft.com/en-us/topic/the-latest-supported-visual-c-downloads-2647da03-1eea-4433-9aff-95f26a218cc0) already installed. Without this, the standalone WingetCreate exe will fail to execute and likely show a "DllNotFoundException" error.
+> [!IMPORTANT]
+> Make sure your build machine has the [Microsoft Visual C++ Redistributable for Visual Studio](https://support.microsoft.com/en-us/topic/the-latest-supported-visual-c-downloads-2647da03-1eea-4433-9aff-95f26a218cc0) already installed. Without this, the standalone WingetCreate exe will fail to execute and likely show a "DllNotFoundException" error.
 
 To execute the standalone exe, add another PowerShell task to download and run the ./wingetcreate.exe to update your existing manifest. You will need a GitHub personal access token if you would like to submit your updated manifest. It is not recommended to hardcode your PAT in your script as this poses as a security threat. You should instead store your PAT as a [secret pipeline variable](https://docs.microsoft.com/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables) or a [repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) in case of GitHub Actions.
 
@@ -102,7 +104,8 @@ To execute the standalone exe, add another PowerShell task to download and run t
 
 Windows Server 2022 now supports App Execution Aliases, which means the alias `wingetcreate` can be used to run the tool after installing the msixbundle. The latest version of the msixbundle can be found at https://aka.ms/wingetcreate/latest/msixbundle. Similar to the standalone exe steps, download the msixbundle, add the package, and run `wingetcreate` to update your manifest.
 
-> **Note**: Winget-Create has a dependency on the [C++ Runtime Desktop framework package](https://docs.microsoft.com/en-us/troubleshoot/developer/visualstudio/cpp/libraries/c-runtime-packages-desktop-bridge). Be sure to also download and install this package prior to installing wingetcreate as shown in the steps below.
+> [!IMPORTANT]
+> Winget-Create has a dependency on the [C++ Runtime Desktop framework package](https://docs.microsoft.com/en-us/troubleshoot/developer/visualstudio/cpp/libraries/c-runtime-packages-desktop-bridge). Be sure to also download and install this package prior to installing wingetcreate as shown in the steps below.
 
 ```yaml
 - powershell: |
@@ -136,10 +139,14 @@ You can install the prerequisites in one of two ways:
 
 #### Using the configuration file
 
-1. Clone the repository.
-2. Configure the system using the [configuration file](.configurations/configuration.dsc.yaml). This can be applied by either:
-    - [Dev Home](https://github.com/microsoft/devhome)'s machine configuration tool
-    - [WinGet configuration](https://learn.microsoft.com/windows/package-manager/configuration/). If you have the [experimental feature](https://aka.ms/winget-settings#configuration) enabled, run `winget configure -f .configurations/configuration.dsc.yaml` from an elevated shell.
+1. Clone the repository
+2. Configure your system
+   * Please use the [configuration file](.configurations/configuration.dsc.yaml). This can be applied by either:
+     * [Dev Home](https://github.com/microsoft/devhome)'s machine configuration tool
+     * WinGet configuration. If you have WinGet version [v1.6.2631 or later](https://github.com/microsoft/winget-cli/releases), run `winget configure .configurations/configuration.dsc.yaml` in an elevated shell from the project root so relative paths resolve correctly
+   * Alternatively, if you already are running the minimum OS version, have Visual Studio installed, and have developer mode enabled, you may configure your Visual Studio directly via the .vsconfig file. To do this:
+     * Open the Visual Studio Installer, select “More” on your product card and then "Import configuration"
+     * Specify the .vsconfig file at the root of the repo and select “Review Details”
 
 #### Manual set up
 
@@ -176,7 +183,8 @@ Running unit and E2E tests are a great way to ensure that functionality is prese
 * Set the solution wide runsettings file for the tests
     * Go to `Test` menu > `Configure Run Settings` -> `Select Solution Wide runsettings File` -> Choose your configured runsettings file
 
-> **Warning**: You should treat your access token like a password. To avoid exposing your PAT, be sure to reset changes to the `WingetCreateTests/Test.runsettings` file before committing your changes. You can also use the command `git update-index --skip-worktree src/WingetCreateTests/WingetCreateTests/Test.runsettings` command to untrack changes to the file and prevent it from being committed.
+> [!CAUTION]
+> You should treat your access token like a password. To avoid exposing your PAT, be sure to reset changes to the `WingetCreateTests/Test.runsettings` file before committing your changes. You can also use the command `git update-index --skip-worktree src/WingetCreateTests/WingetCreateTests/Test.runsettings` command to untrack changes to the file and prevent it from being committed.
 
 ## Contributing
 
@@ -212,3 +220,5 @@ You can also opt-out of telemetry by configuring the `settings.json` file and se
 See the [privacy statement](/PRIVACY.md) for more details.
 
 ## Known Issues
+
+Certain functionalities of wingetcreate, particularly input prompting, may not be fully supported on certain shells such as PowerShell ISE. The supported shells for the prompting package utilized by wingetcreate are specified [here](https://github.com/shibayan/Sharprompt#supported-platforms)

doc/cache.md

@@ -15,3 +15,4 @@ The following arguments are available:
 | **-c, --clean** | Deletes all downloaded installers in the cache folder |
 | **-l, --list** | Lists out all the downloaded installers stored in cache |
 | **-o, --open** | Opens the cache folder storing the downloaded installers |
+| **-?, --help** |  Gets additional help on this command. |

doc/help.md

@@ -6,5 +6,3 @@ The **help** command of the [Winget-Create](../README.md) tool displays help for
 
 * Display help for all commands: `wingetcreate.exe -?`
 * View options for a command: `wingetcreate.exe <command> -?`
-
- 

doc/new.md

@@ -1,12 +1,12 @@
  # new command (Winget-Create)
- 
-The **new** command of the [Winget-Create](../README.md) tool begins the process of generating a manifest file.  This command is used if you need to create a [manifest file](https://docs.microsoft.com/windows/package-manager/package/manifest) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub.  
+
+The **new** command of the [Winget-Create](../README.md) tool begins the process of generating a manifest file.  This command is used if you need to create a [manifest file](https://docs.microsoft.com/windows/package-manager/package/manifest) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub.
 
 ## Usage
 
 `wingetcreate.exe new [<urls>] [\<options>]`
 
-The **new** command can be called with the optional URL(s). **Winget-Create** will download each provided installer as it begins.  If the URL is not included, the user will need to add it when prompted. 
+The **new** command can be called with the optional URL(s). **Winget-Create** will download each provided installer as it begins.  If the URL is not included, the user will need to add it when prompted.
 
 ### Multiple URLs in command line:
 
@@ -32,9 +32,9 @@ The following arguments are available:
 
 ## Winget-Create New Command flow
 
-### Downloading the installer  
+### Downloading the installer
 
-The first action **Winget-Create** will take is to download the installer. **Winget-Create** will attempt to access the meta data associated with the installer.  If the metadata is discovered, it will pre-populate the default strings.  
+The first action **Winget-Create** will take is to download the installer. **Winget-Create** will attempt to access the meta data associated with the installer.  If the metadata is discovered, it will pre-populate the default strings.
 As can be seen in this image, the Windows SDK was used as the URL and the PackageIdentifier is pre-populated.
 
 ![new command](./images/create-new.png)
@@ -45,26 +45,27 @@ By typing **ENTER** you will accept the string, and the wizard will move on.
 
 ![new command PackageIdentifier](./images/create-packageidentifier.png)
 
-### Remaining required fields  
+### Remaining required fields
 
 Like the **PackageIdentifier** you will have the opportunity to accept or modify the remaining fields.
 
 ![new command default values](./images/create-defaults.png)
 
 ### Review Changes
-Once you have successfully filled in the details, fields, **Winget-Create** will display the results for you to review.  
+Once you have successfully filled in the details, fields, **Winget-Create** will display the results for you to review.
 
 ![new command review](./images/create-review.png)
 
-If you would like to make changes, **Winget-Create** will walk you through the fields again allowing you to change them.  
+If you would like to make changes, **Winget-Create** will walk you through the fields again allowing you to change them.
 
 If you are content with the changes, choose **no** and the manifest will be saved.
 
-### Submit  
+### Submit
 
-The last option **Winget-Create** will offer is for you to submit the manifest to the [Windows Package Manager repository](https://github.com/microsoft/winget-pkgs).  
+The last option **Winget-Create** will offer is for you to submit the manifest to the [Windows Package Manager repository](https://github.com/microsoft/winget-pkgs).
 If you choose yes, you will automatically submit your Pull Request (PR) to the [Windows Package Manager repository](https://github.com/microsoft/winget-pkgs).
 
 If you have provided your [GitHub token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) on the command line, you can skip the login process. Instructions on setting up GitHub Token for Winget-Create can be found [here](../README.md#github-personal-access-token-classic-permissions).
 
-> **Note**: If you have not logged on to GitHub, you will be taken to the GitHub authentication web page before allowing you to submit your manifest. 
+> [!NOTE]
+> If you have not logged on to GitHub, you will be taken to the GitHub authentication web page before allowing you to submit your manifest.

doc/settings.md

@@ -45,7 +45,7 @@ The `intervalInDays` setting specifies how often Winget-Create will remove tempo
 
 ## WindowsPackageManagerRepository
 
-The `WindowsPackageManagerRepository` setting specifies which repository Winget-Create targets. By default, this setting targets the main [`microsoft/winget-pkgs`](https://github.com/microsoft/winget-pkgs) repository but can be changed to target a forked copy of the main repository like a [test](https://github.com/microsoft/winget-pkgs-submission-test) or private production repository. 
+The `WindowsPackageManagerRepository` setting specifies which repository Winget-Create targets. By default, this setting targets the main [`microsoft/winget-pkgs`](https://github.com/microsoft/winget-pkgs) repository but can be changed to target a forked copy of the main repository like a [test](https://github.com/microsoft/winget-pkgs-submission-test) or private production repository.
 
 ### Owner
 The `owner` setting specifies who owns the targeted GitHub repository. By default, this is set to `microsoft`.

doc/show.md

@@ -28,5 +28,6 @@ The following arguments are available:
 | **-l, --locale-manifests** |  Switch to display all locale manifests.
 | **--version-manifest** |  Switch to display the version manifest.
 | **-t, --token** |  GitHub personal access token used for authenticated access to the GitHub API. It is recommended to provide a token to get a higher [API rate limit](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting).
+| **-?, --help** |  Gets additional help on this command. |
 
 Instructions on setting up GitHub Token for Winget-Create can be found [here](../README.md#github-personal-access-token-classic-permissions).

doc/submit.md

@@ -18,6 +18,7 @@ The following arguments are available:
 | **-p, --prtitle** |  The title of the pull request submitted to GitHub.
 | **-r, --replace** |  Boolean value for replacing an existing manifest from the Windows Package Manager repo. Optionally provide a version or else the latest version will be replaced. Default is false.
 | **-t, --token** |  GitHub personal access token used for direct submission to the Windows Package Manager repo. If no token is provided, tool will prompt for GitHub login credentials.
+| **-?, --help** |  Gets additional help on this command. |
 
 If you have provided your [GitHub token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) on the command line with the **submit** command and the device is registered with GitHub, **Winget-Create** will submit your PR to [Windows Package Manager repo](https://docs.microsoft.com/windows/package-manager/).
 

doc/token.md

@@ -1,6 +1,6 @@
 # token command (Winget-Create)
 
-The **token** command of the [Winget-Create](../README.md) tool is designed to manage cached GitHub personal access tokens used by the tool for interacting with the [Windows Package Manager repo](https://docs.microsoft.com/windows/package-manager/) automatically.  
+The **token** command of the [Winget-Create](../README.md) tool is designed to manage cached GitHub personal access tokens used by the tool for interacting with the [Windows Package Manager repo](https://docs.microsoft.com/windows/package-manager/) automatically.
 To use the **token** command, you can specify whether you want to store a new [GitHub token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) or clear any existing cached tokens. If you choose not to provide a token when storing, the tool will initiate an OAuth flow and prompt for your GitHub login credentials.
 
 Instructions on setting up GitHub Token for Winget-Create can be found [here](../README.md#github-personal-access-token-classic-permissions).
@@ -9,6 +9,14 @@ Instructions on setting up GitHub Token for Winget-Create can be found [here](..
 
 `wingetcreate.exe token [\<options>]`
 
+### Store a new GitHub token in your local cache
+
+`wingetcreate.exe token --store --token <GitHubPersonalAccessToken>`
+
+### Clear the cached GitHub token
+
+`wingetcreate.exe token --clear`
+
 ## Arguments
 
 The following arguments are available:
@@ -17,4 +25,5 @@ The following arguments are available:
 |----------------  |-------------|
 | **-c, --clear**  | Required. Clear the cached GitHub token
 | **-s, --store**  | Required. Set the cached GitHub token. Can specify token to cache with --token parameter, otherwise will initiate OAuth flow.
-| **-t, --token**   | GitHub personal access token used for direct submission to the Windows Package Manager repo. If no token is provided, tool will prompt for GitHub login credentials.
+| **-t, --token**   | GitHub personal access token used for direct submission to the Windows Package Manager repo. If no token is provided, tool will prompt for GitHub login credentials.
+| **-?, --help** |  Gets additional help on this command. |