Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create #658 - WinGet Download.md #2953

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/actions/spelling/expect.txt
Original file line number Diff line number Diff line change
Expand Up @@ -478,6 +478,7 @@ VALUENAMECASE
vclib
VERSI
VERSIE
visualstudiocode
vns
vsconfig
vstest
Expand Down
159 changes: 159 additions & 0 deletions doc/specs/#658 - WinGet Download.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
---
author: Roy MacLachlan @RDMaclachlan, Ryan Fu @ryfu-msft
created on: 2023-02-09
last updated: 2024-02-15
issue id: 658
---

# `Download` command

"For [#658](https://github.com/microsoft/winget-cli/issues/658)"

## Abstract

This spec describes the functionality and high-level implementation design for downloading package installers using the Windows Package Manager.

## Inspiration

This is inspired by customer feedback, and a need for broader application deployments:
* Customers want to share the installer with an offline device.
ryfu-msft marked this conversation as resolved.
Show resolved Hide resolved

## Solution Design

The `download` command will provide users with the ability to download any installer from a single package. The following command options are available:

```
-d,--download-directory Directory where the installers are downloaded to
-m,--manifest The path to the manifest of the package
--id Filter results by id
--name Filter results by name
--moniker Filter results by moniker
-v,--version Use the specified version; default is the latest version
-s,--source Find package using the specified source
--scope Select install scope (user or machine)
-a,--architecture Select the architecture
--installer-type Select the installer type
-e,--exact Find package using exact match
--locale Locale to use (BCP47 format)
--ignore-security-hash Ignore the installer hash check failure
--skip-dependencies Skips processing package dependencies and Windows features
--header Optional Windows-Package-Manager REST source HTTP header
--authentication-mode Specify authentication window preference (silent, silentPreferred or interactive)
--authentication-account Specify the account to be used for authentication
--accept-package-agreements Accept all license agreements for packages
--accept-source-agreements Accept all source agreements during source operations
-?,--help Shows help about the selected command
--wait Prompts the user to press any key before exiting
--logs,--open-logs Open the default logs location
--verbose,--verbose-logs Enables verbose logging for winget
--disable-interactivity Disable interactive prompts
ryfu-msft marked this conversation as resolved.
Show resolved Hide resolved
```

### Selecting the installer
A new command argument for `--installer-type` has been added to support selecting a specific installer type to download. A package installer should also be able to be selected by `--scope`, `--architecture`, and `--locale`.

### Downloading the installer
Downloading the package's installer will still require that the package's installer hash be verified before becoming available to the user to interact with. By default, installers will be downloaded to a unique folder name located in the `%USERPROFILE%/Downloads` directory. The default download directory can be modified in the user's settings. The unique folder name is comprised of the package identifier and package version. The installer will be comprised of the package identifier, package version, scope, architecture, and locale. This naming pattern ensures that the installer is unique and identifiable based on the installer filters applied:

> Example installer download path name: `%USER_PROFILE%\Downloads\Microsoft.PowerToys_0.78.0\PowerToys (Preview)_0.78.0_User_X64_burn_en-US.exe`

When downloading the package's installer, if a file with the same name exists the new download will overwrite the existing file.
ryfu-msft marked this conversation as resolved.
Show resolved Hide resolved

### Downloading the manifest
Along with downloading the installer, a merged manifest will be generated and outputted in the same installer download directory. The naming of the file will be exactly the same as the installer except for the extension which will be `.yaml`. The manifest is useful for providing information about the installer such as scope, product code, installer switches, etc.

## UI/UX Design

### WinGet Command Line
Downloading an installer will output information relative to each step performed. Informing the user of any license agreements that must be accepted prior to download. Acceptance of license agreements will trigger the download to begin, displaying a progress bar that shows the download status. Upon download, the user will then be informed of the file hash validation status before being notified of the download status.

The following is representative of the user experience.

```PowerShell
PS C:\> WinGet download --id Microsoft.VisualStudioCode
Found Microsoft Visual Studio Code [Microsoft.VisualStudioCode] Version 1.73.1
This application is licensed to you by its owner.
Microsoft is not responsible for, nor does it grant any licenses to, third-party packages.
Starting package download...
\
Successfully verified installer hash
Installer downloaded:%USERPROFILE%\Downloads\Microsoft.VisualStudioCode_1.86.1\Microsoft Visual Studio Code_1.86.1_User_X64_inno_en-US.exe
```

When the user runs `download` command with the `--help` argument, the following information will be provided:

```
PS C:\> WinGet Download --help
Windows Package Manager v1.1.1
Copyright (c) Microsoft Corporation. All rights reserved.

Downloads the installer from the selected package, either found by searching a configured source or directly from a manifest. By default, the query must case-insensitively match the id, name, or moniker of the package. Other fields can be used by passing their appropriate option. By default, download command will download the appropriate installer to the user's Downloads folder.

usage: winget download [[-q] <query>] [<options>]
```

### WinGet Setting - Default Download Output

The following items will be included in the WinGet Settings Schema

```json
"DownloadBehavior: {
"defaultDownloadDirectory":"%USERPROFILE%/Downloads/"
}"
```

The "defaultDownloadDirectory" setting will be used as the default folder where the package installer and manifest is downloaded to.

### WinGet PowerShell Cmdlet
WinGet PowerShell cmdlet will download the identified package's installer and manifest based on the user specified parameters. While downloading the package's installer, PowerShell will show a progress bar displaying the progress. Afterwards, it will return the downloaded directory where the files were downloaded to.:

```PS
PS C:\> Get-Help Save-WinGetPackage

NAME
Save-WinGetPackage

SYNOPSIS
Downloads a package installer from a WinGet configured source.

SYNTAX
Save-WinGetPackage [-ID <System.String>] [-Name <System.String>] [-Moniker <System.String>]
[-Scope <System.String>] [-Locale <System.String>] [-FileName <System.String>]
[-Version <System.String>] [-Source <System.String>] [-Architecture <System.String>] [-Exact]
[-Output <System.String>] [InstallerType <System.String>] [-IgnoreSecurityHash]
[-AcceptPackageAgreement] [-Wait] [-Verbose]

DESCRIPTION
Downloads a package installer and manifest, either found by searching a configured source or
directly from a manifest. By default, the query must case-insensitively match the id, name, or
moniker of the package. Other fields can be used by passing their appropriate option.

```

## Capabilities

### Accessibility

Accessibility should not be impacted by this change. There will be a new column in WinGet search that will appear if an application is downloadable.

### Security

Security of the Windows Package Manager should not be impacted by this change.

### Reliability

There will be no change to the reliability of the Windows Package Manager.

### Compatibility

There will be no breaking changes to the code. A subsection of the WinGet Install functionality will be leveraged for this new functionality.

### Performance, Power, and Efficiency

## Potential Issues

## Future considerations

* AAD Authentication

## Resources
Loading