commit d68a1a69346e7ca16a5d07eef38a2c93172eb991
parent 199e60cda177fbfa56f05cdfabaa147bef52087a
Author: denelon <denelon@microsoft.com>
Date: Tue, 8 Jun 2021 14:10:23 -0700
Adding troubleshooting (#1134)
* Adding troubleshooting
* Update README.md
* Update expect.txt
Diffstat:
3 files changed, 204 insertions(+), 123 deletions(-)
diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
@@ -77,6 +77,7 @@ CYRL
Debian
deigh
deleteifnotneeded
+desktopappinstaller
dirs
dnld
dustojnikhummer
@@ -312,6 +313,7 @@ URIs
URLs
URLZONE
userfilesetting
+userprofile
USHORT
Utils
UWP
diff --git a/README.md b/README.md
@@ -1,123 +1,127 @@
-# Welcome to the Windows Package Manager Client (aka winget.exe) repository
-
-This repository contains the source code for the Windows Package Manager Client (aka winget.exe).
-
-
-
-The packages available to the client are in the [Community repo](https://github.com/microsoft/winget-pkgs).
-
-> The Windows Package Manager project is in Preview. We welcome all feedback, and that feedback might lead to big (maybe even breaking) changes.
-
-## Installing the client
-
-> The client requires Windows 10 1809 (build 17763) or later at this time.
-
-### Microsoft Store [Recommended]
-
-The client is distributed within the [App Installer](https://www.microsoft.com/en-us/p/app-installer/9nblggh4nns1) package. While this package is pre-installed on Windows, the client will not be made generally available during the Preview period. In order to get automatic updates from the Microsoft Store that contain the client, one must do one of the following:
-
-* Install a [Windows 10 Insider](https://insider.windows.com/) build
-* Join the Preview flight ring by [signing up](http://aka.ms/winget-InsiderProgram)
-
-Note: it may take a few days to get the updated App Installer after you receive e-mail confirmation from joining the Windows Package Manager Insider program. If you decide to install the latest release from GitHub, and you have successfully joined the insider program, you will receive updates when the next stable release has been added to the Microsoft Store.
-
-Once you have received the updated App Installer you should be able to execute `winget`. Some users have reported [issues](https://github.com/microsoft/winget-cli/issues/210) with the client not being on their PATH.
-
-### Manually Update
-
-The same Microsoft Store package will be made available via our [Releases](https://github.com/microsoft/winget-cli/releases). Note that installing this package will give you the WinGet client, but it will not enable automatic updates from the Microsoft Store.
-
-> You may need to install the [VC++ v14 Desktop Framework Package](https://docs.microsoft.com/en-us/troubleshoot/cpp/c-runtime-packages-desktop-bridge#how-to-install-and-update-desktop-framework-packages).
-> This should only be necessary on older builds of Windows 10 and only if you get an error about missing framework packages.
-
-## Administrator considerations
-
-Installer behavior can be different depending on whether you are running **winget** with administrator privileges.
-
-* When running **winget** without administrator privileges, some applications may [require elevation](https://docs.microsoft.com/windows/security/identity-protection/user-account-control/) to install. When the installer runs, Windows will prompt you to [elevate](https://docs.microsoft.com/windows/security/identity-protection/user-account-control). If you choose not to elevate, the application will fail to install.
-
-* When running **winget** in an Administrator Command Prompt, you will not see [elevation prompts](/windows/security/identity-protection/user-account-control/how-user-account-control-works) if the application requires it. Always use caution when running your command prompt as an administrator, and only install applications you trust.
-
-### Build your own
-
-You can also [build the client yourself](#building-the-client). While the client should be perfectly functional, we are not ready to provide full support for clients running outside of the official distribution mechanisms yet. Feel free to file an Issue, but know that it may get lower prioritization.
-
-## Build Status
-
-[](https://dev.azure.com/ms/winget-cli/_build/latest?definitionId=344&branchName=master)
-
-## Windows Package Manager 1.0 Roadmap
-The plan for delivering Windows Package Manager v1.0 [is described here](doc/windows-package-manager-v1-roadmap.md), and will be updated as the project proceeds.
-
-## Overview of the Windows Package Manager
-The **Windows Package Manager** is a tool designed to help you quickly and easily discover and install those tools that make your PC environment special. By using the **Windows Package Manager**, from one command, you can install your favorite tool:
-```winget install <tool>```
-
-For Preview, the goal is to get something usable in your hands as soon as possible. At preview you can **search**, **show**, and **install** packages. Soon we will have **uninstall**, **list** and **update**. These items are available on our [backlog](https://github.com/microsoft/winget-cli/issues), so feel free to upvote the features you want.
-
-## Overview
-
-### Client Repository
-This winget-cli repository includes the source code designed to build the client. You are encouraged to participate in the development of this client. We have plenty of backlog features in our [Issues](https://github.com/microsoft/winget-cli/issues). You can upvote the ones you want, add more, or even [get started on one.](https://github.com/microsoft/winget-cli/projects/1)
-
-### Sources
-The client is built around the concept of sources; a set of packages effectively. Sources provide the ability to discover and retrieve the metadata about the packages, so that the client can act on it.
-
-The default source reflects that data available from the [Community repo](https://github.com/microsoft/winget-pkgs).
-
-We plan to better support additional sources, and additional types of sources, in the future. For now, additional sources can be configured, but only one used at a time.
-
-### Package Manager Service
-The **Package Manager Service** is responsible for approving Pull Requests. It validates the YAML and [manifest spec](/doc/ManifestSpecv1.0.md) for spec compliance.
-
-
-## Building the client
-
-### Prerequisites
-
-* Windows 10 1809 (17763) or later
-* [Developer Mode enabled](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development)
-* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
- * Or use winget to install it ;) (although you may need to adjust the workloads via Tools->Get Tools and Features...)
-* The following workloads:
- * .NET Desktop Development
- * Desktop Development with C++
- * Universal Windows Platform Development
-* The following extensions:
- * [Microsoft Visual Studio Installer Projects](https://marketplace.visualstudio.com/items?itemName=VisualStudioClient.MicrosoftVisualStudio2017InstallerProjects)
-
-### Building
-
-We currently only build using the solution; command line methods of building a VS solution should work as well.
-
-## Credit
-
-We would like to thank [Keivan Beigi (@kayone)](https://github.com/kayone) for his work on AppGet which helped us on the initial project direction for Windows Package Manager.
-
-
-## Contributing
-
-This project welcomes contributions and suggestions. Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. More
-information is available in our [CONTRIBUTING.md](/CONTRIBUTING.md) file.
-
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
-
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information, please refer to the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
-
-## Data/Telemetry
-
-The winget.exe client is instrumented to collect usage and diagnostic (error) data and sends it to Microsoft to help improve the product.
-
-If you build the client yourself the instrumentation will not be enabled and no data will be sent to Microsoft.
-
-The winget.exe client respects machine wide privacy settings and users can opt-out on their device, as documented in the Microsoft Windows privacy statement [here](https://support.microsoft.com/en-us/help/4468236/diagnostics-feedback-and-privacy-in-windows-10-microsoft-privacy).
-
-In short to opt-out, go to `Start`, then select `Settings` > `Privacy` > `Diagnostics & feedback`, and select `Basic`.
-
-See the [privacy statement](privacy.md) for more details.
+# Welcome to the Windows Package Manager Client (aka winget.exe) repository
+
+This repository contains the source code for the Windows Package Manager Client (aka winget.exe).
+
+
+
+The packages available to the client are in the [Community repo](https://github.com/microsoft/winget-pkgs).
+
+> The Windows Package Manager project is in Preview. We welcome all feedback, and that feedback might lead to big (maybe even breaking) changes.
+
+## Installing the client
+
+> The client requires Windows 10 1809 (build 17763) or later at this time.
+
+### Microsoft Store [Recommended]
+
+The client is distributed within the [App Installer](https://www.microsoft.com/en-us/p/app-installer/9nblggh4nns1) package. While this package is pre-installed on Windows, the client will not be made generally available during the Preview period. In order to get automatic updates from the Microsoft Store that contain the client, one must do one of the following:
+
+* Install a [Windows 10 Insider](https://insider.windows.com/) build
+* Join the Preview flight ring by [signing up](http://aka.ms/winget-InsiderProgram)
+
+Note: it may take a few days to get the updated App Installer after you receive e-mail confirmation from joining the Windows Package Manager Insider program. If you decide to install the latest release from GitHub, and you have successfully joined the insider program, you will receive updates when the next stable release has been added to the Microsoft Store.
+
+Once you have received the updated App Installer you should be able to execute `winget`. Some users have reported [issues](https://github.com/microsoft/winget-cli/issues/210) with the client not being on their PATH.
+
+### Manually Update
+
+The same Microsoft Store package will be made available via our [Releases](https://github.com/microsoft/winget-cli/releases). Note that installing this package will give you the WinGet client, but it will not enable automatic updates from the Microsoft Store.
+
+> You may need to install the [VC++ v14 Desktop Framework Package](https://docs.microsoft.com/en-us/troubleshoot/cpp/c-runtime-packages-desktop-bridge#how-to-install-and-update-desktop-framework-packages).
+> This should only be necessary on older builds of Windows 10 and only if you get an error about missing framework packages.
+
+### Troubleshooting
+
+Please read our [troubleshooting guide](/doc/troubleshooting/README.md).
+
+## Administrator considerations
+
+Installer behavior can be different depending on whether you are running **winget** with administrator privileges.
+
+* When running **winget** without administrator privileges, some applications may [require elevation](https://docs.microsoft.com/windows/security/identity-protection/user-account-control/) to install. When the installer runs, Windows will prompt you to [elevate](https://docs.microsoft.com/windows/security/identity-protection/user-account-control). If you choose not to elevate, the application will fail to install.
+
+* When running **winget** in an Administrator Command Prompt, you will not see [elevation prompts](/windows/security/identity-protection/user-account-control/how-user-account-control-works) if the application requires it. Always use caution when running your command prompt as an administrator, and only install applications you trust.
+
+### Build your own
+
+You can also [build the client yourself](#building-the-client). While the client should be perfectly functional, we are not ready to provide full support for clients running outside of the official distribution mechanisms yet. Feel free to file an Issue, but know that it may get lower prioritization.
+
+## Build Status
+
+[](https://dev.azure.com/ms/winget-cli/_build/latest?definitionId=344&branchName=master)
+
+## Windows Package Manager 1.0 Roadmap
+The plan for delivering Windows Package Manager v1.0 [is described here](doc/windows-package-manager-v1-roadmap.md), and will be updated as the project proceeds.
+
+## Overview of the Windows Package Manager
+The **Windows Package Manager** is a tool designed to help you quickly and easily discover and install those tools that make your PC environment special. By using the **Windows Package Manager**, from one command, you can install your favorite tool:
+```winget install <tool>```
+
+For Preview, the goal is to get something usable in your hands as soon as possible. At preview you can **search**, **show**, and **install** packages. Soon we will have **uninstall**, **list** and **update**. These items are available on our [backlog](https://github.com/microsoft/winget-cli/issues), so feel free to upvote the features you want.
+
+## Overview
+
+### Client Repository
+This winget-cli repository includes the source code designed to build the client. You are encouraged to participate in the development of this client. We have plenty of backlog features in our [Issues](https://github.com/microsoft/winget-cli/issues). You can upvote the ones you want, add more, or even [get started on one.](https://github.com/microsoft/winget-cli/projects/1)
+
+### Sources
+The client is built around the concept of sources; a set of packages effectively. Sources provide the ability to discover and retrieve the metadata about the packages, so that the client can act on it.
+
+The default source reflects that data available from the [Community repo](https://github.com/microsoft/winget-pkgs).
+
+We plan to better support additional sources, and additional types of sources, in the future. For now, additional sources can be configured, but only one used at a time.
+
+### Package Manager Service
+The **Package Manager Service** is responsible for approving Pull Requests. It validates the YAML and [manifest spec](/doc/ManifestSpecv1.0.md) for spec compliance.
+
+
+## Building the client
+
+### Prerequisites
+
+* Windows 10 1809 (17763) or later
+* [Developer Mode enabled](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development)
+* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
+ * Or use winget to install it ;) (although you may need to adjust the workloads via Tools->Get Tools and Features...)
+* The following workloads:
+ * .NET Desktop Development
+ * Desktop Development with C++
+ * Universal Windows Platform Development
+* The following extensions:
+ * [Microsoft Visual Studio Installer Projects](https://marketplace.visualstudio.com/items?itemName=VisualStudioClient.MicrosoftVisualStudio2017InstallerProjects)
+
+### Building
+
+We currently only build using the solution; command line methods of building a VS solution should work as well.
+
+## Credit
+
+We would like to thank [Keivan Beigi (@kayone)](https://github.com/kayone) for his work on AppGet which helped us on the initial project direction for Windows Package Manager.
+
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. More
+information is available in our [CONTRIBUTING.md](/CONTRIBUTING.md) file.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information, please refer to the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Data/Telemetry
+
+The winget.exe client is instrumented to collect usage and diagnostic (error) data and sends it to Microsoft to help improve the product.
+
+If you build the client yourself the instrumentation will not be enabled and no data will be sent to Microsoft.
+
+The winget.exe client respects machine wide privacy settings and users can opt-out on their device, as documented in the Microsoft Windows privacy statement [here](https://support.microsoft.com/en-us/help/4468236/diagnostics-feedback-and-privacy-in-windows-10-microsoft-privacy).
+
+In short to opt-out, go to `Start`, then select `Settings` > `Privacy` > `Diagnostics & feedback`, and select `Basic`.
+
+See the [privacy statement](privacy.md) for more details.
diff --git a/doc/troubleshooting/README.md b/doc/troubleshooting/README.md
@@ -0,0 +1,75 @@
+# Troubleshooting
+
+## How do I get the Windows Package Manager?
+
+### Prerequisites
+
+The first thing to check is which version of Windows 10 you have.
+
+[Check your version of Windows](https://support.microsoft.com/en-us/windows/see-which-version-of-windows-10-you-have-12d35019-4da9-0cb1-ba47-f8b031b712ad).
+
+The Windows Package Manager requires at least Version 1809 (October 2018 Update).
+
+The next requirement is ensuring you have the [App Installer](https://www.microsoft.com/en-us/p/app-installer/9nblggh4nns1) from the Microsoft Store. The Windows Package Manager is delivered as an MSIX package. The App Installer is required to install MSIX packages on Windows 10.
+
+>Note: The Windows Package Manager is shipped with later versions of the App Installer.
+
+### Stable Releases
+
+The first stable release of the Windows Package Manager was v1.0.11451. This release was **not** published as an automatic update to all Windows 10 users on a supported version of Windows 10. This was an intentional decision made to provide enterprise customers (IT Professionals) sufficient time to configure and deploy Group Policy for the Windows Package Manager.
+
+Customers may install the [latest stable release](https://github.com/microsoft/winget-cli/releases/latest/) directly from the GitHub repository. These packages are signed, and customers will receive automatic updates if IT Policy does not block the Microsoft Store.
+
+### Developer Releases (Pre-Release)
+
+>Note: There is a known problem restoring the client to the latest stable App Installer release. We will be distributing the latest stable builds and providing instructions once they are made available.
+
+During the initial Windows Package Manager Preview period, releases were distributed to all Windows Insider channels. Customers who [sign up](http://aka.ms/winget-InsiderProgram) to become members of the Windows Package Manager Insider program also receive pre-release builds. The final process for inclusion into the program requires manual steps, so the App Installer update may not be available for a few days **after** receiving their e-mail notification.
+
+Customers may install any [release](https://github.com/microsoft/winget-cli/releases/) including pre-release builds directly from the GitHub repository. These packages are signed, and customers will receive automatic updates if IT Policy does not block the Microsoft Store.
+
+>Note: Insiders will receive updates to the latest build (stable or pre-release) if IT Policy does not block the Microsoft Store. Other customers will receive updates to the latest stable build once a newer stable version is published if IT Policy does not block the Microsoft Store.
+
+Only the Windows Insider DEV channel will continue receiving pre-release builds of the Windows Package Manager after v1.0.11451. Other Windows Insider channels will only receive stable release candidates or updated versions of the Windows Package Manager with critical bug fixes.
+
+## Common Issues
+
+### Executing `winget` doesn't display help
+
+The following error is displayed when executed in CMD. `The system cannot execute the specified program.`
+
+The following error is displayed when executed in PowerShell.
+
+```
+Program 'winget.exe' failed to run: The file cannot be accessed by the systemAt line:1 char:1
++ winget
++ ~~~~~~.
+At line:1 char:1
++ winget
++ ~~~~~~
+ + CategoryInfo : ResourceUnavailable: (:) [], ApplicationFailedException
+ + FullyQualifiedErrorId : NativeCommandFailed
+```
+
+These errors most commonly occur for one of three reasons.
+1. The App Installer does not contain the Windows Package Manager. You should check to ensure the version of App Installer is greater than 1.11.11451. You can check by executing the following command in PowerShell:
+
+ >`Get-AppxPackage microsoft.desktopappinstaller`
+
+2. The App Execution Alias for the Windows Package Manager is disabled. You should enable the App Execution Aias for the Windows Package Manager
+3. The App Installer did not automatically add the PATH environment variable. You should add the path environment variable. The value to add is "%userprofile%\AppData\Local\Microsoft\WindowsApps".
+
+## Common Errors
+
+
+#### Error 0x801901a0
+
+This error is related to Delivery Optimization (DO). You may configure the Windows Package Manager settings to use the standard `WININET` library. Add the following network setting:
+
+>`"network": {"downloader": "wininet"}`
+
+#### Error 0x80d03002
+
+This error is related to Delivery Optimization (DO). You may configure the Windows Package Manager settings to use the standard `WININET` library. Add the following network setting:
+
+>`"network": {"downloader": "wininet"}`
