commit f149246787aee66480f6d817038e18df406559f6 parent 38fc8f9cb688c675d931221b6e7d2a9fb602883a Author: Kevin Larkin (MS) <kevinla@microsoft.com> Date: Mon, 3 May 2021 11:15:54 -0700 Build docs (#919) * Baseline docs * fixed typo * add terms Diffstat:
19 files changed, 955 insertions(+), 1 deletion(-)
diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt @@ -12,6 +12,7 @@ APARTMENTTHREADED apfn apiset appinstallertest +appname Archs argumentlist ARMNT @@ -41,6 +42,7 @@ casemap casemappings cch CDEF +cdn cend centralus certmgr @@ -55,9 +57,11 @@ cloudapp CLSID COINIT commandline +compschema Concat contosa contosainstaller +contoso count'th createmanifestmetadata cstdint @@ -74,6 +78,7 @@ dw endian enr enums +EQU ERANGE errno etest @@ -84,6 +89,7 @@ fd fintimes Fixfor flargle +flexera foldc foldcase FOLDERID @@ -97,24 +103,30 @@ GHS gity Globals google +helplib +helplibrary hhx HINSTANCE hkey hlocal hre HRESULTs +htm IAttachment IConfiguration +IHelp IHost IID IInstalled IName INET inor +installshield IPackage IPersist IService ISettings +ishelp ISQ ISVs itr @@ -123,6 +135,7 @@ IWeb IZone JObject jp +jrsoftware jsoncpp kayone Keivan @@ -132,6 +145,7 @@ ktf Langs LATN ldcase +learnxinyminutes lhs libyaml Linq @@ -143,9 +157,12 @@ LPBYTE LPWSTR LSTATUS LTDA +malware MBH megamorf memcpy +minexample +minschema MMmmbbbb monicka msdownload @@ -165,6 +182,7 @@ mytool Newtonsoft NOEXPAND normer +nsis nuffing nullopt objbase @@ -176,9 +194,11 @@ pathpaths pfn pfxpath Pherson +pkgmgr pkindex PMS positionals +powertoys productcode pvk pvm @@ -201,19 +221,22 @@ rowids RRF rrr rzkzqaqjwj -serializer SARL schematab +Screenshot sddl seof +serializer setmetadatabymanifestid SETTINGMAPPING Shlobj sid SIGNATUREHASH Sku +smartscreen sortof sourc +sourceforge spamming SPAPI Srinivasan @@ -253,6 +276,7 @@ UNSCOPED UParse UPSERT URIs +URLs URLZONE userfilesetting USHORT @@ -262,6 +286,7 @@ vamus VERSI VERSIE vns +vscode vy wcslen webpages diff --git a/doc/windows/package-manager/package/images/fork.png b/doc/windows/package-manager/package/images/fork.png Binary files differ. diff --git a/doc/windows/package-manager/package/images/pull-request.png b/doc/windows/package-manager/package/images/pull-request.png Binary files differ. diff --git a/doc/windows/package-manager/package/index.md b/doc/windows/package-manager/package/index.md @@ -0,0 +1,24 @@ +--- +title: Submit packages to Windows Package Manager +description: You can use Windows Package Manager as a distribution channel for software packages containing your applications. +ms.date: 04/29/2020 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Submit packages to Windows Package Manager + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +If you're an Independent Software Vendor (ISV), you can use Windows Package Manager as a distribution channel for software packages containing your applications. Windows Package Manager currently supports installers in the following formats: MSIX, MSI, and EXE. + +To submit software packages to Windows Package Manager, follow these steps: + +1. [Create a package manifest that provides information about your application](manifest.md). Manifests are YAML files that follow the Windows Package Manager schema. +2. [Submit your manifest to the Windows Package Manager repository](repository.md). This is an open source repository on GitHub that contains a collection of manifests that the **winget** tool can access. + +## Related topics + +* [Use the winget tool](../winget/index.md) +* [Create your package manifest](manifest.md) +* [Submit your manifest to the repository](repository.md) diff --git a/doc/windows/package-manager/package/manifest.md b/doc/windows/package-manager/package/manifest.md @@ -0,0 +1,180 @@ +--- +title: Create your package manifest +description: If you want to submit a software package to the Windows Package Manager repository, start by creating a package manifest. +ms.date: 04/29/2020 +ms.topic: article +ms.localizationpriority: medium +--- + +# Create your package manifest + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +If you want to submit a software package to the [Windows Package Manager repository](repository.md), start by creating a package manifest. The manifest is a YAML file that describes the application to be installed. + +This article describes the contents of a package manifest for Windows Package Manager. + +## YAML basics + +The YAML format was chosen for package manifests because of its relative ease of human readability and consistency with other Microsoft development tools. If you are not familiar with YAML syntax, you can learn the basics at [Learn YAML in Y Minutes](https://learnxinyminutes.com/docs/yaml/). + +> [!NOTE] +> Manifests for Windows Package Manager currently do not support all YAML features. Unsupported YAML features include anchors, complex keys, and sets. + +## Conventions + +These conventions are used in this article: + +* To the left of `:` is a literal keyword used in manifest definitions. +* To the right of `:` is a data type. The data type can be a primitive type like **string** or a reference to a rich structure defined elsewhere in this article. +* The notation `[` *datatype* `]` indicates an array of the mentioned data type. For example, `[ string ]` is an array of strings. +* The notation `{` *datatype* `:` *datatype* `}` indicates a mapping of one data type to another. For example, `{ string: string }` is a mapping of strings to strings. + +## Manifest contents + +A package manifest must include a set of required items, and can also include further optional items that can help improve the customer experience of installing your software. This section provides brief summaries of the required manifest schema and complete manifest schemas, and examples of each. + +Each field in the manifest file must be Pascal-cased and cannot be duplicated. + +For a complete list and descriptions of items in a manifest, see the [manifest specification](https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv0.1.md) in the [https://github.com/microsoft/winget-cli](https://github.com/microsoft/winget-cli) repository. + +### Minimal required schema + +#### [Minimal required schema](#tab/minschema/) + +```yaml +Id: string # Publisher.package format. +Publisher: string # The name of the publisher. +Name: string # The name of the application. +Version: string # Version numbering format. +License: string # The open source license or copyright. +InstallerType: string # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx). +Installers: + - Arch: string # Enumeration of supported architectures. + Url: string # Path to download installation file. + Sha256: string # SHA256 calculated from installer. +ManifestVersion: 0.1.0 +``` + +#### [Example](#tab/minexample/) + +```yaml +Id: microsoft.teams +Publisher: Microsoft Corporation +Name: Microsoft Teams +Version: 1.3.0.4461 +License: Copyright (c) Microsoft Corporation. All rights reserved. +InstallerType: exe +Installers: + - Arch: x64 + Url: https://statics.teams.cdn.office.net/production-windows-x64/1.3.00.4461/Teams_windows_x64.exe + Sha256: 712f139d71e56bfb306e4a7b739b0e1109abb662dfa164192a5cfd6adb24a4e1 +ManifestVersion: 0.1.0 +``` + +* * * + +### Complete schema + +#### [Complete schema](#tab/compschema/) + +```yaml +Id: string # Publisher.package format. +Publisher: string # The name of the publisher. +Name: string # The name of the application. +AppMoniker: string # The common name someone may use to search for the package. +Version: string # Version numbering format for package version. +Channel: string # A string representing the flight ring. +License: string # The open source license or copyright. +LicenseUrl: string # Valid secure URL to license. +MinOSVersion: string # Version numbering format for minimum version of Windows supported. +Description: string # Description of the package. +Homepage: string # Valid secure URL for the package. +Tags: list # Additional strings a user would use to search for the package. +FileExtensions: list # List of file extensions the package could support. +Protocols: list # List of protocols the package provides a handler for. +Commands: list # List of commands or aliases the user would use to run the package. +InstallerType: string # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx). +Switches: # These can be used to change the install behavior if supported by the InstallerType. + Custom: string # Custom switches passed to the installer. + Silent: string # Switches passed to the installer for silent installation. + SilentWithProgress: string # Switches passed to the installer for non-interactive install. + Interactive: string # Experimental. + Language: string # Experimental. + Log: string # Specifies log redirection switches and path. + InstallLocation: string # Specifies alternate location to install package. +Installers: # Nested map of keys for specific installer. + - Arch: string # Enumeration of supported architectures. + Url: string # Path to download installation file. + Sha256: string # SHA256 calculated from installer. + SignatureSha256: string # SHA256 calculated from signature file's hash of MSIX file. + Switches: # Collection of entries to override root keys. The primary supported values are: Custom, Silent, SilentWithProgress, Interactive. For a complete list see the specification at https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv0.1.md. + Scope: string # Experimental. + SystemAppId: string # Experimental. +Localization: # Nested map of keys for localization. + - Language: string # Locale for display fields and localized URLs. +ManifestVersion: string # Version number format for manifest version. +``` + +#### [Good example](#tab/good/) + +```yaml +Id: microsoft.teams +Publisher: Microsoft Corporation +Name: Microsoft Teams +Version: 1.3.0.4461 +License: Copyright (c) Microsoft Corporation. All rights reserved. +LicenseUrl: https://docs.microsoft.com/en-us/MicrosoftTeams/assign-teams-licenses +InstallerType: exe +Installers: + - Arch: x64 + Url: https://statics.teams.cdn.office.net/production-windows-x64/1.3.00.4461/Teams_windows_x64.exe + Sha256: 712f139d71e56bfb306e4a7b739b0e1109abb662dfa164192a5cfd6adb24a4e1 +ManifestVersion: 0.1.0 +``` + +#### [Better example](#tab/better/) + +```yaml +Id: microsoft.teams +Publisher: Microsoft Corporation +Name: Microsoft Teams +Version: 1.3.0.4461 +AppMoniker: teams +MinOSVersion: 10.0.0.0 +Description: The hub for teamwork in Microsoft 365 +Homepage: https://www.microsoft.com/microsoft/teams +License: Copyright (c) Microsoft Corporation. All rights reserved. +LicenseUrl: https://docs.microsoft.com/en-us/MicrosoftTeams/assign-teams-licenses +InstallerType: exe +Installers: + - Arch: x64 + Url: https://statics.teams.cdn.office.net/production-windows-x64/1.3.00.4461/Teams_windows_x64.exe + Sha256: 712f139d71e56bfb306e4a7b739b0e1109abb662dfa164192a5cfd6adb24a4e1 +ManifestVersion: 0.1.0 +``` + +* * * + +> [!NOTE] +> if your installer is an .exe and it was built using Nullsoft or Inno, you may specify those values instead. When Nullsoft or Inno are specified, the client will automatically set the silent and silent with progress install behaviors for the installer. + +## Installer switches + +You can often figure out what silent `Switches` are available for an installer by passing in a `-?` to the installer from the command line. Here are some common silent `Switches` that can be used for different installer types. + +| Installer | Command | Documentation | +| :--- | :-- | :--- | +| MSI | `/q` | [MSI Command-Line Options](/windows/win32/msi/command-line-options) | +| InstallShield | `/s` | [InstallShield Command-Line Parameters](https://docs.flexera.com/installshield19helplib/helplibrary/IHelpSetup_EXECmdLine.htm) | +| Inno Setup | `/SILENT or /VERYSILENT` | [Inno Setup documentation](https://jrsoftware.org/ishelp/) | +| Nullsoft | `/S` | [Nullsoft Silent Installers/Uninstallers](https://nsis.sourceforge.io/Docs/Chapter4.html#silent) | + +## Tips and best practices + +* For the best customer experience when finding and installing your software, we recommend that you include as many optional items beyond the required schema as possible. For example, the `AppMoniker` field is optional. However, if you include this field, customers will see results associated with the `AppMoniker` value when performing the [search](../winget/search.md) command (for example, **vscode** for **Visual Studio Code**). If there is only one app with the specified `AppMoniker` value, customers can install your application by specifying the moniker rather than the fully qualified ID. +* The `Id` must be unique. You cannot have multiple submissions with the same package identifier. Avoid spaces, because this will require users to put quotation marks around the `Id` when using the [winget](../index.md) client. +* Avoid creating multiple publisher folders. For example, do not create "Contoso Ltd" if there is already a "Contoso" folder. Also avoid spaces when creating folders. +* All packages should be submitted with a silent install if possible. If you have an executable that does not support a silent install, the user experience will be diminished. +* Limit the length of strings in your manifest to 100 characters before a line break. +* When more than one installer type exists for the specified version of the package, an instance of `InstallerType` can be placed under each of the `Installers`. diff --git a/doc/windows/package-manager/package/repository.md b/doc/windows/package-manager/package/repository.md @@ -0,0 +1,128 @@ +--- +title: Submit your manifest to the repository +description: After you create a package manifest that describes your application, you're ready to submit your manifest to the Windows Package Manager repository. +ms.date: 04/29/2020 +ms.topic: article +ms.localizationpriority: medium +--- + +# Submit your manifest to the repository + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +After you create a [package manifest](manifest.md) that describes your application, you're ready to submit your manifest to the Windows Package Manager repository. This a public-facing repository that contains a collection of manifests that the **winget** tool can access. To submit your manifest, you'll upload it to the open source [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) repository on GitHub. + +After you submit a pull request to add a new manifest to the GitHub repository, an automated process will validate your manifest file and check to make sure the package is not known to be malicious. If this validation is successful, your package will be added to the public-facing Windows Package Manager repository so it can be discovered by the **winget** client tool. Note the distinction between the manifests in the open source GitHub repository and the public-facing Windows Package Manager repository. + +> [!IMPORTANT] +> Microsoft reserves the right to refuse a submission for any reason. + +## Third-party repositories + +There are currently no known third party repositories. Microsoft is working with multiple partners to develop protocols or an API to enable third party repositories. + +## Manifest validation + +When you submit a manifest to the [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) repository on GitHub, your manifest will be automatically validated and evaluated for the safety of the Windows ecosystem. Manifests may also be reviewed manually. + +## How to submit your manifest + +To submit a manifest to the repository, follow these steps. + +### Step 1: Validate your manifest + +The **winget** tool provides the [validate](..\winget\validate.md) command to confirm that you have created your manifest correctly. To validate your manifest, use this command. + +```CMD +winget validate \<manifest-file> +``` + +If your validation fails, use the errors to locate the line number and make a correction. After your manifest is validated, you can submit it to the repository. + +### Step 2: Clone the repository + +Next, create a fork of the repository and clone it. + +1. Go to [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) in your browser and click **Fork**. +  + +2. From a command line environment such as the Windows Command Prompt or PowerShell, use the following command to clone your fork. + ```CMD + git clone \<your-fork-name> + ``` + + 3. If you are making multiple submissions, make a branch instead of a fork. We currently allow only one manifest file per submission. + ```CMD + git checkout -b \<branch-name> + ``` + +### Step 3: Add your manifest to the local repository + +You must add your manifest file to the repository in the following folder structure: + +**manifests** / **publisher** / **application** / **version.yaml** + +* The **manifests** folder is the root folder for all manifests in the repository. +* The **publisher** folder is the name of the company that publishes the software. For example, **Microsoft**. +* The **application** folder is the name of the application or tool. For example, **VSCode**. +* **version.yaml** is the file name of the manifest. The file name must be set to the current version of the application. For example, **1.0.0.yaml**. + +>[!IMPORTANT] +> The `Id` value in the manifest must match the publisher and application names in the manifest folder path, and the `version` value in the manifest must match the version in the file name. For more information, see [Create your package manifest](manifest.md#tips-and-best-practices). + +### Step 4: Submit your manifest to the remote repository + +You're now ready to push your new manifest to the remote repository. + +1. Use the `add` command to prepare for submission. + ```CMD + git add manifests\Contoso\ContosoApp\1.0.0.yaml + ``` + +2. Use the `commit` command to commit the change and provide information on the submission. + ```CMD + git commit -m "Submitting ContosoApp version 1.0.0.yaml" + ``` + +3. Use the `push` command to push the changes to the remote repository. + ```CMD + git push + ``` + +### Step 5: Create a pull request + +After you push your changes, return to [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) and create a pull request to merge your fork or branch to the main branch. + + + +## Validation process + +When you create a pull request, this will start an automation process that validates the manifest and processes your pull request. We add labels to your pull request so you can track progress. + +### Submission expectations + +All application submissions to the Windows Package Manager repository should be well-behaved. Here are some expectations for submissions: + +* The manifest complies with the [schema requirements](manifest.md#manifest-contents). +* All URLs in the manifest lead to safe websites. +* The installer and application are virus free. The package may be identified as malware by mistake. If you believe it's a false positive you can submit the installer to the defender team for analysis from [here](https://www.microsoft.com/wdsi/filesubmission). +* The application installs and uninstalls correctly for both administrators and non-administrators. +* The installer supports non-interactive modes. +* All manifest entries are accurate and not misleading. +* The installer comes directly from the publisher's website. + +### Pull request labels + +During validation, we apply a series of labels to our pull request to communicate progress. + +* **Needs: author feedback**: There is a failure with the submission. We will reassign pull request back to you. If you do not address the issue within 10 days, we will close the pull request. +* **Manifest-Validation-Error**: The submitted manifest contains a syntax error. +* **URL-Validation-Error**: One or more URLs in the submission failed [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) validation. +* **Binary-Validation-Error**: The submitted application installer failed virus scan testing or there is a hash mismatch. +* **Pull-Request-Error**: There is a problem with the pull request. For example, the folder structure does not have the [required format](#step-3-add-your-manifest-to-the-local-repository). +* **Validation-Error**: The submitted application failed a general validation test. +* **Validation-Installation-Error**: The submitted application failed install testing. +* **Validation-Uninstall-Error**: The submitted application failed uninstall testing. +* **Validation-Virus-Scan-Error**: The submitted application failed virus scan testing. +* **Azure-Pipeline-Passed**: The manifest has completed the first portion of validation. After this step, your pull request is assigned to our test team for final validation. +* **Validation-Completed**: The validation is complete and your pull request will be merged.+ \ No newline at end of file diff --git a/doc/windows/package-manager/winget/hash.md b/doc/windows/package-manager/winget/hash.md @@ -0,0 +1,34 @@ +--- +title: winget hash command +description: Generates the SHA256 hash for an installer. +ms.date: 04/28/2020 +ms.topic: article +ms.localizationpriority: medium +--- + +# hash command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **hash** command of the [winget](index.md) tool generates the SHA256 hash for an installer. This command is used if you need to create a [manifest file](../package/manifest.md) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub. In addition, the **hash** command also supports generating a SHA256 certificate hash for MSIX files. + +## Usage + +`winget hash [-f] \<file> [\<options>]` + +The **hash** sub command can only run on a local file. To use the **hash** sub command, download your installer to a known location. Then pass in the file path as an argument to the **hash** sub command. + +## Arguments + +The following arguments are available: + +| Argument | Description | +|--------------|-------------| +| **-f,--file** | The path to the file to be hashed. | +| **-m,--msix** | Specifies that the hash command will also create the SHA 256 SignatureSha256 for use with MSIX installers. | +| **-?, --help** | Gets additional help on this command. | + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) +* [Submit packages to Windows Package Manager](../package/index.md) diff --git a/doc/windows/package-manager/winget/help.md b/doc/windows/package-manager/winget/help.md @@ -0,0 +1,22 @@ +--- +title: winget help Command +description: Displays help for all the supported commands. +ms.date: 04/28/2020 +ms.topic: article +ms.localizationpriority: medium +--- + +# help command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **help** command of the [winget](index.md) tool displays help for all the supported commands and sub commands. In addition, you can pass the **--help** argument to any other command to get details about all additional command options. + +## Usage + +* Display help for all commands: `winget --help` +* View options for a command: `winget <command> --help` + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) diff --git a/doc/windows/package-manager/winget/images/help.png b/doc/windows/package-manager/winget/images/help.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/install.png b/doc/windows/package-manager/winget/images/install.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/search.png b/doc/windows/package-manager/winget/images/search.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/show.png b/doc/windows/package-manager/winget/images/show.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/source.png b/doc/windows/package-manager/winget/images/source.png Binary files differ. diff --git a/doc/windows/package-manager/winget/index.md b/doc/windows/package-manager/winget/index.md @@ -0,0 +1,115 @@ +--- +title: Use the winget tool to install and manage applications +description: The winget command line tool enables developers to discover, install, upgrade, remove and configure applications on Windows 10 computers. +ms.date: 10/22/2020 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Use the winget tool to install and manage applications + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **winget** command line tool enables developers to discover, install, upgrade, remove and configure applications on Windows 10 computers. This tool is the client interface to the Windows Package Manager service. + +The **winget** tool is currently a preview, so not all planned functionality is available at this time. + +## Install winget + +There are several ways to install the **winget** tool: + +* The **winget** tool is included in the flight or preview version of [Windows App Installer](https://www.microsoft.com/p/app-installer/9nblggh4nns1?ocid=9nblggh4nns1_ORSEARCH_Bing&rtc=1&activetab=pivot:overviewtab). You must install the preview version of **App Installer** to use **winget**. To gain early access, submit your request to the [Windows Package Manager Insiders Program](https://aka.ms/AppInstaller_InsiderProgram). Participating in the flight ring will guarantee you see the latest preview updates. + +* Participate in the [Windows Insider flight ring](https://insider.windows.com). + +* Install the Windows Desktop App Installer package located on the [Releases page for the winget repository](https://github.com/microsoft/winget-cli/releases). + +> [!NOTE] +> The **winget** tool requires Windows 10, version 1709 (10.0.16299), or a later version of Windows 10. + +## 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. + +## Use winget + +After **App Installer** is installed, you can run **winget** by typing 'winget' from a Command Prompt. + +One of the most common usage scenarios is to search for and install a favorite tool. + +1. To [search](search.md) for a tool, type `winget search <appname>`. +2. After you have confirmed that the tool you want is available, you can [install](install.md) the tool by typing `winget install <appname>`. The **winget** tool will launch the installer and install the application on your PC. +  + +3. In addition to install and search, **winget** provides a number of other commands that enable you to [show details](show.md) on applications, [change sources](source.md), and [validate packages](validate.md). To get a complete list of commands, type: `winget --help`. +  + +### Commands + +The current preview of the **winget** tool supports the following commands. + +| Command | Description | +|---------|-------------| +| [hash](hash.md) | Generates the SHA256 hash for the installer. | +| [help](help.md) | Displays help for the **winget** tool commands. | +| [install](install.md) | Installs the specified application. | +| [search](search.md) | Searches for an application. | +| [show](show.md) | Displays details for the specified application. | +| [source](source.md) | Adds, removes, and updates the Windows Package Manager repositories accessed by the **winget** tool. | +| [validate](validate.md) | Validates a manifest file for submission to the Windows Package Manager repository. | + +### Options + +The current preview of the **winget** tool supports the following options. + +| Option | Description | +|--------------|-------------| +| **-v,--version** | Returns the current version of winget. | +| **--info** | Provides you with all detailed information on winget, including the links to the license and privacy statement. | +| **-?, --help** | Shows additional help for winget. | + +## Supported installer formats + +The current preview of the **winget** tool supports the following types of installers: + +* EXE +* MSIX +* MSI + +## Scripting winget + +You can author batch scripts and PowerShell scripts to install multiple applications. + +``` CMD +@echo off +Echo Install Powertoys and Terminal +REM Powertoys +winget install Microsoft.Powertoys +if %ERRORLEVEL% EQU 0 Echo Powertoys installed successfully. +REM Terminal +winget install Microsoft.WindowsTerminal +if %ERRORLEVEL% EQU 0 Echo Terminal installed successfully. %ERRORLEVEL% +``` + +> [!NOTE] +> When scripted, **winget** will launch the applications in the specified order. When an installer returns success or failure, **winget** will launch the next installer. If an installer launches another process, it is possible that it will return to **winget** prematurely. This will cause **winget** to install the next installer before the previous installer has completed. + +## Missing tools + +If the [community repository](../package/repository.md) does not include your tool or application, please submit a package to our [repository](https://github.com/microsoft/winget-pkgs). By adding your favorite tool, it will be available to you and everyone else. + +## Customize winget settings + +You can configure the **winget** command line experience by modifying the **settings.json** file. For more information, see [https://aka.ms/winget-settings](https://aka.ms/winget-settings). Note that the settings are still in an experimental state and not yet finalized for the preview version of the tool. + +## Open source details + +The **winget** tool is open source software available on GitHub in the repo [https://github.com/microsoft/winget-cli/](https://github.com/microsoft/winget-cli/). The source for building the client is located in the [src folder](https://github.com/microsoft/winget-cli/tree/master/src). + +The source for **winget** is contained in a Visual Studio 2019 C++ solution. To build the solution correctly, install the latest [Visual Studio with the C++ workload](https://visualstudio.microsoft.com/downloads/). + +We encourage you to contribute to the **winget** source on GitHub. You must first agree to and sign the Microsoft CLA. diff --git a/doc/windows/package-manager/winget/install.md b/doc/windows/package-manager/winget/install.md @@ -0,0 +1,97 @@ +--- +title: install Command +description: Installs the specified application. +ms.date: 04/28/2020 +ms.topic: overview +ms.localizationpriority: medium +--- + +# install command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **install** command of the [winget](index.md) tool installs the specified application. Use the [**search**](search.md) command to identify the application you want to install. + +The **install** command requires that you specify the exact string to install. If there is any ambiguity, you will be prompted to further filter the **install** command to an exact application. + +## Usage + +`winget install [[-q] \<query>] [\<options>]` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the install experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **-m, --manifest** | Must be followed by the path to the manifest (YAML) file. You can use the manifest to run the install experience from a [local YAML file](#local-install). | +| **--id** | Limits the install to the ID of the application. | +| **--name** | Limits the search to the name of the application. | +| **--moniker** | Limits the search to the moniker listed for the application. | +| **-v, --version** | Enables you to specify an exact version to install. If not specified, latest will install the highest versioned application. | +| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. | +| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. | +| **-i, --interactive** | Runs the installer in interactive mode. The default experience shows installer progress. | +| **-h, --silent** | Runs the installer in silent mode. This suppresses all UI. The default experience shows installer progress. | +| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. | +| **--override** | A string that will be passed directly to the installer. | +| **-l, --location** | Location to install to (if supported). | + +### Example queries + +The following example installs a specific version of an application. + +```CMD +winget install powertoys --version 0.15.2 +``` + +The following example installs an application from its ID. + +```CMD +winget install --id Microsoft.PowerToys +``` + +The following example installs an application by version and ID. + +```CMD +winget install --id Microsoft.PowerToys --version 0.15.2 +``` + +## Multiple selections + +If the query provided to **winget** does not result in a single application, then **winget** will display the results of the search. This will provide you with the additional data necessary to refine the search for a correct install. + +The best way to limit the selection to one file is to use the **id** of the application combined with the **exact** query option. For example: + +```CMD +winget install --id Git.Git -e +``` + +## Local install + +The **manifest** option enables you to install an application by passing in a YAML file directly to the client. The **manifest** option has the following usage. + +Usage: `winget install --manifest \<file>` + +| Option | Description | +|-------------|-------------| +| **-m, --manifest** | The path to the manifest of the application to install. | + +### Log files + +The log files for winget unless redirected, will be located in the following folder: **\%temp%\\AICLI\\*.log** + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) diff --git a/doc/windows/package-manager/winget/search.md b/doc/windows/package-manager/winget/search.md @@ -0,0 +1,66 @@ +--- +title: search Command +description: Queries the sources for available applications that can be installed +ms.date: 04/28/2020 +ms.topic: overview +ms.localizationpriority: medium +--- + +# search command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **search** command of the [winget](index.md) tool queries the sources for available applications that can be installed. + +The **search** command can show all applications available, or it can be filtered down to a specific application. The **search** command is used typically to identify the string to use to install a specific application. + +## Usage + +`winget search [[-q] \<query>] [\<options>]` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | + --------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Gets additional help on this command. | + +## Show all + +If the search command includes no filters or options, it will display all available applications in the default source. You can also search for all applications in another source if you pass in just the **source** option. + +## Search strings + +Search strings can be filtered with the following options. + +| Option | Description | + --------------|-------------| +| **--id** | Limits the search to the ID of the application. The ID includes the publisher and the application name. | +| **--name** | Limits the search to the name of the application. | +| **--moniker** | Limits the search to the moniker specified. | +| **--tag** | Limits the search to the tags listed for the application. | +| **--command** | Limits the search to the commands listed for the application. | + +The string will be treated as a substring. The search by default is also case insensitive. For example, `winget search micro` could return the following: + +* Microsoft +* microscope +* MyMicro + +## Search options + +The search commands supports a number of options or filters to help limit the results. + +| Option | Description | + --------------|-------------| +| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. | +| **-n, --count** | Restricts the output of the display to the specified count. | +| **-s, --source** | Restricts the search to the specified [source](source.md) name. | + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) diff --git a/doc/windows/package-manager/winget/show.md b/doc/windows/package-manager/winget/show.md @@ -0,0 +1,87 @@ +--- +title: show Command +description: Displays details for the specified application, including details on the source of the application as well as the metadata associated with the application. +ms.date: 04/28/2020 +ms.topic: overview +ms.localizationpriority: medium +--- + +# show command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **show** command of the [winget](index.md) tool displays details for the specified application, including details on the source of the application as well as the metadata associated with the application. + +The **show** command only shows metadata that was submitted with the application. If the submitted application excludes some metadata, then the data will not be displayed. + +## Usage + +`winget show [[-q] \<query>] [\<options>]` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | +|--------------|-------------| +| **-q,--query** | The query used to search for an application. | +| **-?, --help** | Gets additional help on this command. | + +## Options + +The following options are available. + +| Option | Description | +|--------------|-------------| +| **-m,--manifest** | The path to the manifest of the application to install. | +| **--id** | Filter results by ID. | +| **--name** | Filter results by name. | +| **--moniker** | Filter results by application moniker. | +| **-v,--version** | Use the specified version. The default is the latest version. | +| **-s,--source** | Find the application using the specified [source](source.md). | +| **-e,--exact** | Find the application using exact match. | +| **--versions** | Show available versions of the application. | + +## Multiple selections + +If the query provided to **winget** does not result in a single application, then **winget** will display the results of the search. This will provide you with the additional data necessary to refine the search. + +## Results of show + +If a single application is detected, the following data will be displayed. + +### Metadata + +| Value | Description | +|--------------|-------------| +| **Id** | Id of the application. | +| **Name** | Name of the application. | +| **Publisher** | Publisher of the application. | +| **Version** | Version of the application. | +| **Author** | Author of the application. | +| **AppMoniker** | AppMoniker of the application. | +| **Description** | Description of the application. | +| **License** | License of the application. | +| **LicenseUrl** | The URL to the license file of the application. | +| **Homepage** | Homepage of the application. | +| **Tags** | The tags provided to assist in searching. | +| **Command** | The commands supported by the application. | +| **Channel** | The details on whether the application is preview or release. | +| **Minimum OS Version** | The minimum OS version supported by the application. | + +### Installer details + +| Value | Description | +|--------------|-------------| +| **Arch** | The architecture of the installer. | +| **Language** | The language of the installer. | +| **Installer Type** | The type of installer. | +| **Download Url** | The Url of the installer. | +| **Hash** | The Sha-256 of the installer. | +| **Scope** | Displays whether the installer is per machine or per user. | + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) diff --git a/doc/windows/package-manager/winget/source.md b/doc/windows/package-manager/winget/source.md @@ -0,0 +1,144 @@ +--- +title: source Command +description: Manages the repositories accessed by Windows Package Manager. +ms.date: 04/28/2020 +ms.topic: overview +ms.localizationpriority: medium +--- + +# source command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +> [!NOTE] +> The **source** command is currently for internal use only. Additional sources are not supported at this time. + +The **source** command of the [winget](index.md) tool manages the repositories accessed by Windows Package Manager. With the **source** command you can **add**, **remove**, **list**, and **update** the repositories. + +A source provides the data for you to discover and install applications. Only add a new source if you trust it as a secure location. + +## Usage + +`winget source \<sub command> \<options>` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | +|--------------|-------------| +| **-?, --help** | Gets additional help on this command. | + +## Sub commands + +Source supports the following sub commands for manipulating the sources. + +| Sub command | Description | +|--------------|-------------| +| **add** | Adds a new source. | +| **list** | Enumerates the list of enabled sources. | +| **update** | Updates a source. | +| **remove** | Removes a source. | +| **reset** | Resets **winget** back to the initial configuration. | + +## Options + +The **source** command supports the following options. + +| Option | Description | +|--------------|-------------| +| **-n,--name** | The name to identify the source by. | +| **-a,--arg** | The URL or UNC of the source. | +| **-t,--type** | The type of source. | +| **-?, --help** | Gets additional help on this command. | + +## add + +The **add** sub command adds a new source. This sub command requires the **--name** option and the **name** argument. + +Usage: `winget source add [-n, --name] \<name> [-a] \<url> [[-t] \<type>]` + +Example: `winget source add --name Contoso https://www.contoso.com/cache` + +The **add** sub command also supports the optional **type** parameter. The **type** parameter communicates to the client what type of repository it is connecting to. The following types are supported. + +| Type | Description | +|--------------|-------------| +| **Microsoft.PreIndexed.Package** | The type of source \<default>. | + +## list + +the **list** sub command enumerates the currently enabled sources. This sub-command also provides details on a specific source. + +Usage: `winget source list [-n, --name] \<name>` + +### list all + +The **list** sub-command by itself will reveal the complete list of supported sources. For example: + +```CMD +> C:\winget source list +> Name Arg +> ----------------------------------------- +> winget https://winget.azureedge.net/cache + +``` + +### list source details + +In order to get complete details on the source, pass in the name used to identify the source. For example: + +```CMD +> C:\winget source list --name contoso +> Name : contoso +> Type : Microsoft.PreIndexed.Package +> Arg : https://pkgmgr-int.azureedge.net/cache +> Data : AppInstallerSQLiteIndex-int_g4ype1skzj3jy +> Updated: 2020-4-14 17:45:32.000 +``` + +**Name** displays the name to identify the source by. +**Type** displays the type of repo. +**Arg** displays the URL or path used by the source. +**Data** displays the optional package name used if appropriate. +**Updated** displays the last date and time the source was updated. + +## update + +The **update** sub command forces an update to an individual source or for all. + +usage: `winget source update [-n, --name] \<name>` + +### update all + +The **update** sub command by itself will request and update to each repo. For example: `C:\winget update` + +### update source + +The **update** sub command combined with the **--name** option can direct and update to an individual source. For example: `C:\winget source update --name contoso` + +## remove + +The **remove** sub command removes a source. This sub command requires the **--name** option and **name argument** in order to identify the source. + +Usage: `winget source remove [-n, --name] \<name>` + +For example: `winget source remove --name Contoso` + +## reset + +The **reset** sub-command resets the client back to its original configuration. The **reset** sub-command removes all sources and sets the source to the default. This sub command should only be used in rare cases. + +Usage: `winget source reset` + +For example: `winget source reset` + +## Default repository + +Windows Package Manager specifies a default repository. You can identify the repository by using the **list** command. For example: `winget source list` + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) diff --git a/doc/windows/package-manager/winget/validate.md b/doc/windows/package-manager/winget/validate.md @@ -0,0 +1,31 @@ +--- +title: winget validate Command +description: Validates a manifest file for submitting software to the Microsoft Community Package Manifest Repository on GitHub. +ms.date: 04/28/2020 +ms.topic: article +ms.localizationpriority: medium +--- + +# validate command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **validate** command of the [winget](index.md) tool validates a [manifest file](../package/manifest.md) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub. The manifest must be a YAML file that follows the [specification](https://github.com/microsoft/winget-pkgs/YamlSpec.md). + +## Usage + +`winget validate [--manifest] \<manifest>` + +## Arguments + +The following arguments are available. + +| Argument | Description | +|--------------|-------------| +| **--manifest** | the path to the manifest to be validated. | +| **-?, --help** | get additional help on this command | + +## Related topics + +* [Use the winget tool to install and manage applications](index.md) +* [Submit packages to Windows Package Manager](../package/index.md)
