README.md (9300B)
1 # Windows Package Manager PowerShell Modules 2 3 ## History 4 This set of PowerShell modules was originally built as a Microsoft Hackathon project in 2021. 5 6 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. 7 8 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. 9 10 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. 11 12 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. 13 14 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](https://github.com/microsoft/winget-cli/issues/221) feature request. The "Microsoft.WinGet.Create" module in the [winget-cli-restsource repository](https://github.com/microsoft/winget-cli-restsource) is expected to support building and modifying manifests in private sources (related to the Windows Package Manager Manifest Creator [REST support feature](https://github.com/microsoft/winget-create/issues/3)). The third module "Microsoft.WinGet.Source" is intended to simplify working the private REST sources like the [reference implementation](https://github.com/microsoft/winget-cli-restsource). A fourth module may be created for the [winget create tool](https://github.com/microsoft/wingetcreate). 15 16 ## Terms and Conventions used 17 18 ### Package 19 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](https://github.com/microsoft/winget-pkgs). 20 21 22 ### Manifest 23 The term "manifest" is used to reference the metadata about an application or program. In the [Windows Package Manager Community App Repository](https://github.com/microsoft/winget-pkgs) 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. 24 25 26 ### Conventions 27 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. 28 29 ### Status 30 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. 31 32 ### Future 33 We expect to enhance the COM interface to support JSON output in the future so the client module can provide rich PowerShell objects. 34 35 --- 36 >Drafted in October and preserved for context. 37 38 ## WinGet Modules 39 * Microsoft.Winget 40 * Microsoft.WinGet.Client 41 * Microsoft.WinGet.Create 42 * Microsoft.WinGet.Source 43 44 ## Microsoft.WinGet.Client cmdlets 45 46 ### Add-WinGetSource 47 Adds a source for the Windows Package Manager to use 48 49 ### Disable-WinGetLocalManifest 50 >This must be run in administrator mode 51 52 ### Edit-WinGetClientSetting 53 Open Windows Package Manager settings file 54 55 ### Enable-WinGetLocalManifest 56 >This must be run in administrator mode 57 58 ### Find-WinGetPackage 59 Searches for packages in configured sources 60 61 ### Get-WinGetPackage 62 Displays the list of packages installed on the local system 63 64 ### Get-WinGetSource 65 Displays the list of sources configured for the Windows Package Manager 66 67 ### Get-WinGetVersion 68 Gets the version for the Windows Package Manager Manifest Creator 69 70 ### Install-WinGetPackage 71 Installs the given package 72 73 ### Remove-WinGetSource 74 Removes a configured source from the Windows Package Manager 75 76 ### Reset-WinGetSource 77 Resets the default sources for the Windows Package Manager 78 79 ### Uninstall-WinGetPackage 80 Uninstalls a package from the local system 81 82 ### Upgrade-WinGetPackage 83 Upgrades a package installed on the local system 84 85 ### Get-WinGetInstaller (ToDo) 86 Displays the installer Install-WinGetPackage would select for the local system 87 88 --- 89 ## Microsoft.WinGet.Create Module cmdlets 90 91 ### Get-WinGetCreateVersion (ToDo) 92 Gets the version for the Windows Package Manager Manifest Creator 93 94 ### Edit-WinGetCreateSetting (ToDo) 95 Open Windows Package Manager Manifest Creator settings file 96 97 ### New-WinGetManifest -Path (ToDo) 98 Creates a new Manifest 99 100 ### Set-WinGetManifest - Path (ToDo) 101 Updates fields of an existing manifest 102 103 ### Submit-WinGetManifest -Path (ToDo) 104 Submits a manifest to the Windows Package Manager App Repository for validation 105 106 ### Add-WinGetManifestVersion (ToDo) 107 Adds a version to an existing manifest 108 109 ### Test-WinGetManifest (ToDo) 110 Validates a manifest 111 112 ### Open-WinGetCreateCache (ToDo) 113 Opens the cache folder storing the downloaded installers 114 115 ### Get-WinGetCreateCache (ToDo) 116 Lists out all the downloaded installers stored in cache 117 118 ### Clear-WinGetCreateCache (ToDo) 119 Deletes all downloaded installers in the cache folder 120 121 --- 122 ## Microsoft.WinGet.Source Module cmdlets 123 124 ** Focus on Private Repository (Rest), If there is time.. then we can look at future support of Public WinGet Source. 125 126 ### Add-WinGetManifest 127 Example: Add-WinGetManifest -Path "C:\Folder\File.json" -Source PrivateRepo 128 * Submit a Manifest to a repository 129 * -Version: Returns only a specific version of the Manifest as a manifest. 130 * If Version not specified, then return the latest version only as part of the manifest. 131 132 ### Get-WinGetManifest 133 Example: Get-WinGetManifest -Id Microsoft.PowerToys -Source PrivateRepo 134 * Gets a Manifest 135 * Needs to have the returned results "Beautified" when shown to the screen. 136 137 ### Set-WinGetManifestVersion 138 Set-WinGetManifestVersion [-Id] Microsoft.PowerToys [--Source] PrivateRepo --ShortDescription "New Description" [--Version] "33.0.0.0" 139 --Source {(PrivateRepo)} 140 141 ### Add-WinGetManifestVersion 142 Does not overwrite previously existing values. User must run "Set" to modify. 143 144 ### Get-WinGetManifestVersion 145 Example: Get-WinGetManifestVersion [-Id] Microsoft.PowerToys -Version 3.0.0.0 146 Returns the values of a specific version in a Manifest 147 148 ### Remove-WinGetManifestVersion 149 This will remove manifest versions from a manifest located in the Private Source only. 150 151 ### Remove-WinGetManifest 152 This will remove manifests from the Private Source only. 153 154 --- 155 156 ## ToDo 157 158 This is not an exhaustive list, but is here as guide for work that needs to be performed. 159 160 * Localization Support 161 * Handle error messages from the client in several scenarios 162 * Handle Group Policy messages 163 * Header is only valid in the context of a single source parameter. We may want to validate in the cmdlet 164 * Validation needs to be built 165 * The Modules should be moved to a new GitHub repository patterned after [Crescendo](https://www.powershellgallery.com/packages/PSPackageProject/0.1.18) 166 * Ultimately, the child modules will be moved to their respective GitHub repositories and the parent will stay in its own repository. 167 * Validation should be implemented 168 * A CI Pipeline should be built to sign and publish the modules to the PowerShell gallery 169 * Packaging with [PSPackageProject](https://www.powershellgallery.com/packages/PSPackageProject/0.1.18) 170 * Documentation with [platyPS](https://www.powershellgallery.com/packages/platyPS/0.14.2) 171 * Support changes from https://github.com/microsoft/winget-cli/issues/1597 172 173 --- 174 175 ## Parking Lot 176 177 PowerShell modules should provide at least parity with the Windows Package Manager 178 179 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.