tools/PowerShell/README.md
This set of PowerShell modules was originally built as a Microsoft Hackathon project in 2021.
We started this project as an exploration to design the right set of cmdlets with PowerShell approved nouns and verbs. As we began to explore wrapping the Windows Package Manager we identified several areas of complexity. Rather than slow down progress on building PowerShell cmdlets, we decided to forge ahead and call out the areas where the experience with pipelines is sub-optimal.
For example, the Windows Package Manager (later referenced as just CLI) CLI was designed for displaying output in the standard width Windows Terminal. As such, long package names and "Id"s are truncated with a single width ellipsis character. Users wanting to use the PowerShell pipeline to pass values to another cmdlet will likely encounter undesired behavior due to this truncation. We have decided to declare the "Microsoft.WinGet" module as an alpha release until these problems have been resolved. We are planning to change the status of "PreRelease" to beta once we believe we have addressed the issues related to piping the output to other cmdlets.
The module and associated cmdlets were essentially handcrafted as the Hackathon team came up to speed with PowerShell idioms. The module and associated cmdlets in the Microsoft.WinGet.Client/crescendo directory were crafted using the "Microsoft.PowerShell.Crescendo" module. Several manual changes were applied to these files as well, but the idea was to leverage crescendo to speed up development.
As we continued, we also identified work being done in support of private REST sources. We decided to create separate modules to speed up development in that are of the product as well as standardizing some of the module work.
The "Microsoft.WinGet" module is a top level module to organize the others. They child modules are "Microsoft.WinGet.Client" intended to represent the native PowerShell module feature request. The "Microsoft.WinGet.Create" module in the winget-cli-restsource repository is expected to support building and modifying manifests in private sources (related to the Windows Package Manager Manifest Creator REST support feature). The third module "Microsoft.WinGet.Source" is intended to simplify working the private REST sources like the reference implementation. A fourth module may be created for the winget create tool.
The term "package" is used to reference an application or program. For example, Windows Terminal is a package. It's identifier "Microsoft.WindowsTerminal" is available in the Windows Package Manager Community App Repository.
The term "manifest" is used to reference the metadata about an application or program. In the Windows Package Manager Community App Repository manifests are represented as YAML files. In a REST source, manifests are represented as JSON structured data. For the sake of transparency, the manifests downloaded by the Windows Package Manager from the default "winget" source, the manifests are taken from the GitHub repository and merged into a single YAML file per package version.
We attempted to make use of the approved verbs for PowerShell. In areas where the verb may have been contentious, we decided to at least be consistent with ourselves. The Open verb is used to open a directory in file explorer (Windows Package Manager Manifest Creator installer cache). The Edit verb is used to open the settings.json file for the Windows Package Manager Manifest Creator and the Windows Package Manager.
The modules should be treated as experimental at this stage of development. They are essentially calling the Windows Package Manager executable and attempting to parse text output that wasn't designed for PowerShell.
We expect to enhance the COM interface to support JSON output in the future so the client module can provide rich PowerShell objects.
Drafted in October and preserved for context.
Adds a source for the Windows Package Manager to use
This must be run in administrator mode
Open Windows Package Manager settings file
This must be run in administrator mode
Searches for packages in configured sources
Displays the list of packages installed on the local system
Displays the list of sources configured for the Windows Package Manager
Gets the version for the Windows Package Manager Manifest Creator
Installs the given package
Removes a configured source from the Windows Package Manager
Resets the default sources for the Windows Package Manager
Uninstalls a package from the local system
Upgrades a package installed on the local system
Displays the installer Install-WinGetPackage would select for the local system
Gets the version for the Windows Package Manager Manifest Creator
Open Windows Package Manager Manifest Creator settings file
Creates a new Manifest
Updates fields of an existing manifest
Submits a manifest to the Windows Package Manager App Repository for validation
Adds a version to an existing manifest
Validates a manifest
Opens the cache folder storing the downloaded installers
Lists out all the downloaded installers stored in cache
Deletes all downloaded installers in the cache folder
** Focus on Private Repository (Rest), If there is time.. then we can look at future support of Public WinGet Source.
Example: Add-WinGetManifest -Path "C:\Folder\File.json" -Source PrivateRepo
Example: Get-WinGetManifest -Id Microsoft.PowerToys -Source PrivateRepo
Set-WinGetManifestVersion [-Id] Microsoft.PowerToys [--Source] PrivateRepo --ShortDescription "New Description" [--Version] "33.0.0.0" --Source {(PrivateRepo)}
Does not overwrite previously existing values. User must run "Set" to modify.
Example: Get-WinGetManifestVersion [-Id] Microsoft.PowerToys -Version 3.0.0.0 Returns the values of a specific version in a Manifest
This will remove manifest versions from a manifest located in the Private Source only.
This will remove manifests from the Private Source only.
This is not an exhaustive list, but is here as guide for work that needs to be performed.
PowerShell modules should provide at least parity with the Windows Package Manager
The CLI is inefficient at returning multiple versions / installers. If we expand beyond what it can do, when we inevitably switch over to the CLI as the tool for running, then the community will see this as a loss of functionality.