commit 93ac7be9416c188b77781406e9e541a87ba424c4 parent 8e30e7b9d1933928642785d7ff4b07609fae0a13 Author: Ryan Fu <69221034+ryfu-msft@users.noreply.github.com> Date: Fri, 2 Dec 2022 18:04:13 -0800 Add PowerShell cmdlet help text and examples (#2732) Diffstat:
10 files changed, 300 insertions(+), 232 deletions(-)
diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_AddRemoveSource.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_AddRemoveSource.ps1 @@ -0,0 +1,25 @@ +<# + .SYNOPSIS + Example for 'Get-WinGetSource', 'Add-WinGetSource', 'Remove-WinGetSource', and 'Reset-WinGetSource' cmdlet. + Cmdlets to allow you to manage sources for the Windows Package Manager. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# List current sources. +Get-WinGetSource + +# Add REST source +Add-WinGetSource -Name 'Contoso' -Argument 'https://www.contoso.com/cache' -Type 'Microsoft.Rest' + +# Remove source by name +Remove-WinGetSource -Name 'Contoso' + +# Reset to default sources +Reset-WinGetSource+ \ No newline at end of file diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_EnableSettings.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_EnableSettings.ps1 @@ -0,0 +1,19 @@ +<# + .SYNOPSIS + Example for 'Enable-WinGetSetting' and 'Disable-WinGetSetting' cmdlets. + Cmdlet for enabling/disabling a specified WinGet setting. May require elevation. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# Enables the 'LocalManifestFiles' setting. +Enable-WinGetSetting -Name LocalManifestFiles + +# Disables the 'LocalManifestFiles' setting. +Disable-WinGetSetting -Name LocalManifestFiles + \ No newline at end of file diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_FindPackage.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_FindPackage.ps1 @@ -0,0 +1,28 @@ +<# + .SYNOPSIS + Example for 'Find-WinGetPackage' cmdlet. + Displays all applications available for instasllation. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# Find all available packages +Find-WinGetPackage + +# Find package by name +Find-WinGetPackage -Name git + +# Find 10 packages by name +Find-WinGetPackage -Name git -Count 10 + +# Find package by package identifier +Find-WinGetPackage -Id git.git + +# Find exact package from a specific source. +Find-WinGetPackage -Id Git.Git -Source winget -Exact+ \ No newline at end of file diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_GetPackage.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_GetPackage.ps1 @@ -0,0 +1,28 @@ +<# + .SYNOPSIS + Example for 'Get-WinGetPackage' cmdlet. + Displays a list of the applications currently installed on your computer. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# List all installed packages +Get-WinGetPackage + +# List installed package by name +Get-WinGetPackage -Name git + +# List 10 packages by name +Get-WinGetPackage -Name git -Count 10 + +# List package by package identifier +Get-WinGetPackage -Id git.git + +# List exact package from a specific source. +Get-WinGetPackage -Id Git.Git -Source winget -Exact+ \ No newline at end of file diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_GetVersion.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_GetVersion.ps1 @@ -0,0 +1,17 @@ +<# + .SYNOPSIS + Example for 'Get-WinGetVersion' cmdlet. + Prints the current client version. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +$version = Get-WinGetVersion + +Write-Host($version);+ \ No newline at end of file diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_InstallPackage.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_InstallPackage.ps1 @@ -0,0 +1,25 @@ +<# + .SYNOPSIS + Example for 'Install-WinGetPackage' cmdlet. + Installs the specified application based on the provided arguments. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# Install a package by name +Install-WinGetPackage -Name powertoys + +# Install a package by version and package identifier. +Install-WinGetPackage -Id Microsoft.PowerToys -Version 0.15.2 + +# Install a package from a specific source +Install-WinGetPackage -Id Microsoft.PowerToys -Source winget + +# Install a package with a specific architecture and scope. +Install-WinGetPackage -Id Microsoft.PowerToys -Architecture X64 -Scope User diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_UninstallPackage.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_UninstallPackage.ps1 @@ -0,0 +1,22 @@ +<# + .SYNOPSIS + Example for 'Uninstall-WinGetPackage' cmdlet. + Uninstalls the specified application. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# Uninstall a package by name +Uninstall-WinGetPackage -Name powertoys + +# Uninstall a package by version and package identifier. +Uninstall-WinGetPackage -Id Microsoft.PowerToys -Version 0.15.2 + +# Uninstall a package from a specific source +Uninstall-WinGetPackage -Id Microsoft.PowerToys -Source winget diff --git a/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_UpdatePackage.ps1 b/src/PowerShell/Microsoft.WinGet.Client/Examples/Sample_UpdatePackage.ps1 @@ -0,0 +1,25 @@ +<# + .SYNOPSIS + Example for 'Update-WinGetPackage' cmdlet. + Updates the specified application. +#> + +# TODO: Replace parameter with actual module name from PSGallery once module is released. +Param ( + [Parameter(Mandatory)] + $ModulePath +) + +Import-Module -Name $ModulePath + +# Update a package by name +Update-WinGetPackage -Name powertoys + +# Update a package by version and package identifier. +Update-WinGetPackage -Id Microsoft.PowerToys -Version 0.15.2 + +# Update a package with silent mode +Update-WinGetPackage -Id Microsoft.PowerToys -Mode Silent + +# Force update a package +Update-WinGetPackage -Id Microsoft.PowerToys -Force+ \ No newline at end of file diff --git a/src/PowerShell/Microsoft.WinGet.Client/Microsoft.WinGet.Client.psd1 b/src/PowerShell/Microsoft.WinGet.Client/Microsoft.WinGet.Client.psd1 @@ -76,7 +76,6 @@ else { # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. FunctionsToExport = @( 'Get-WinGetVersion' - 'Get-WinGetVersion', 'Enable-WinGetSetting', 'Disable-WinGetSetting', 'Add-WinGetSource', @@ -120,7 +119,8 @@ PrivateData = @{ 'PSEdition_Desktop', 'PSEdition_Core', 'Windows', - 'WindowsPackageManager' + 'WindowsPackageManager', + 'WinGet' ) # A URL to the license for this module. diff --git a/src/PowerShell/Microsoft.WinGet.Client/Microsoft.WinGet.Client.psm1 b/src/PowerShell/Microsoft.WinGet.Client/Microsoft.WinGet.Client.psm1 @@ -11,10 +11,10 @@ class PowerShellCustomFunctionAttribute : System.Attribute { -function Get-WinGetVersion +function Get-WinGetVersion { [PowerShellCustomFunctionAttribute(RequiresElevation=$False)] -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( ) @@ -81,49 +81,27 @@ PROCESS { } # end PROCESS <# -.SYNOPSIS -Windows Package Manager (Preview) v1.3.1391-preview -Copyright (c) Microsoft Corporation. All rights reserved. - -The winget command line utility enables installing applications and other packages from the command line. - -usage: winget [<command>] [<options>] - -The following commands are available: - install Installs the given package - show Shows information about a package - source Manage sources of packages - search Find and show basic info of packages - list Display installed packages - upgrade Shows and performs available upgrades - uninstall Uninstalls the given package - hash Helper to hash installer files - validate Validates a manifest file - settings Open settings or set administrator settings - features Shows the status of experimental features - export Exports a list of the installed packages - import Installs all the packages in a file - -For more details on a specific command, pass it the help argument. [-?] - -The following options are available: - -v,--version Display the version of the tool - --info Display general info of the tool - -More help can be found at: https://aka.ms/winget-command-help - -.DESCRIPTION See help for winget.exe + .SYNOPSIS + Displays the version of the tool. -#> -} + .DESCRIPTION + Displays the version of the winget.exe tool. + .INPUTS + None. + .OUTPUTS + None + .EXAMPLE + PS> Get-WinGetVersion +#> +} -function Enable-WinGetSetting +function Enable-WinGetSetting { [PowerShellCustomFunctionAttribute(RequiresElevation=$False)] -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( [Parameter(Position=0,ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true,Mandatory=$true)] @@ -204,54 +182,34 @@ PROCESS { } # end PROCESS <# -.SYNOPSIS -Windows Package Manager (Preview) v1.3.1391-preview -Copyright (c) Microsoft Corporation. All rights reserved. - -The winget command line utility enables installing applications and other packages from the command line. - -usage: winget [<command>] [<options>] - -The following commands are available: - install Installs the given package - show Shows information about a package - source Manage sources of packages - search Find and show basic info of packages - list Display installed packages - upgrade Shows and performs available upgrades - uninstall Uninstalls the given package - hash Helper to hash installer files - validate Validates a manifest file - settings Open settings or set administrator settings - features Shows the status of experimental features - export Exports a list of the installed packages - import Installs all the packages in a file - -For more details on a specific command, pass it the help argument. [-?] - -The following options are available: - -v,--version Display the version of the tool - --info Display general info of the tool - -More help can be found at: https://aka.ms/winget-command-help - -.DESCRIPTION See help for winget.exe - -.PARAMETER Name + .SYNOPSIS + Enables the WinGet setting specified by the `Name` parameter. + + .DESCRIPTION + Enables the WinGet setting specified by the `Name` parameter. + Supported settings: `LocalManifestFiles` + .PARAMETER Name + Specifies the name of the setting to be enabled. + .INPUTS + None. + .OUTPUTS + None + .EXAMPLE + PS> Enable-WinGetSetting -name LocalManifestFiles #> } -function Disable-WinGetSetting +function Disable-WinGetSetting { [PowerShellCustomFunctionAttribute(RequiresElevation=$False)] -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( [Parameter(Position=0,ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true,Mandatory=$true)] @@ -332,60 +290,37 @@ PROCESS { } # end PROCESS <# -.SYNOPSIS -Windows Package Manager (Preview) v1.3.1391-preview -Copyright (c) Microsoft Corporation. All rights reserved. - -The winget command line utility enables installing applications and other packages from the command line. - -usage: winget [<command>] [<options>] - -The following commands are available: - install Installs the given package - show Shows information about a package - source Manage sources of packages - search Find and show basic info of packages - list Display installed packages - upgrade Shows and performs available upgrades - uninstall Uninstalls the given package - hash Helper to hash installer files - validate Validates a manifest file - settings Open settings or set administrator settings - features Shows the status of experimental features - export Exports a list of the installed packages - import Installs all the packages in a file - -For more details on a specific command, pass it the help argument. [-?] - -The following options are available: - -v,--version Display the version of the tool - --info Display general info of the tool - -More help can be found at: https://aka.ms/winget-command-help - -.DESCRIPTION See help for winget.exe - -.PARAMETER Name + .SYNOPSIS + Disables the WinGet setting specified by the `Name` parameter. + + .DESCRIPTION + Disables the WinGet setting specified by the `Name` parameter. + Supported settings: `LocalManifestFiles` + .PARAMETER Name + Specifies the name of the setting to be disabled. + .INPUTS + None. + .OUTPUTS + None + .EXAMPLE + PS> Disable-WinGetSetting -name LocalManifestFiles #> } - - - -function Add-WinGetSource +function Add-WinGetSource { [PowerShellCustomFunctionAttribute(RequiresElevation=$False)] -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( [Parameter(Position=0,ValueFromPipelineByPropertyName=$true,Mandatory=$true)] -[string]$Name, +[string]$Name, [Parameter(Position=1,ValueFromPipelineByPropertyName=$true,Mandatory=$true)] -[string]$Argument, +[string]$Argument, [Parameter(Position=2,ValueFromPipelineByPropertyName=$true)] [string]$Type ) @@ -480,62 +415,39 @@ PROCESS { } # end PROCESS <# -.SYNOPSIS -Windows Package Manager (Preview) v1.3.1391-preview -Copyright (c) Microsoft Corporation. All rights reserved. - -The winget command line utility enables installing applications and other packages from the command line. - -usage: winget [<command>] [<options>] - -The following commands are available: - install Installs the given package - show Shows information about a package - source Manage sources of packages - search Find and show basic info of packages - list Display installed packages - upgrade Shows and performs available upgrades - uninstall Uninstalls the given package - hash Helper to hash installer files - validate Validates a manifest file - settings Open settings or set administrator settings - features Shows the status of experimental features - export Exports a list of the installed packages - import Installs all the packages in a file - -For more details on a specific command, pass it the help argument. [-?] - -The following options are available: - -v,--version Display the version of the tool - --info Display general info of the tool - -More help can be found at: https://aka.ms/winget-command-help - -.DESCRIPTION See help for winget.exe - -.PARAMETER Name - + .SYNOPSIS + Add a new source. + .DESCRIPTION + Add a new source. A source provides the data for you to discover and install packages. + Only add a new source if you trust it as a secure location. -.PARAMETER Argument + .PARAMETER Name + Name of the source. + .PARAMETER Argument + Argument to be given to the source. + .PARAMETER Type + Type of the source. -.PARAMETER Type - + .INPUTS + None. + .OUTPUTS + None. + .EXAMPLE + PS> Add-WinGetSource -Name Contoso -Argument https://www.contoso.com/cache #> } - - -function Remove-WinGetSource +function Remove-WinGetSource { [PowerShellCustomFunctionAttribute(RequiresElevation=$False)] -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( [Parameter(Position=0,ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true,Mandatory=$true)] @@ -616,54 +528,31 @@ PROCESS { } # end PROCESS <# -.SYNOPSIS -Windows Package Manager (Preview) v1.3.1391-preview -Copyright (c) Microsoft Corporation. All rights reserved. - -The winget command line utility enables installing applications and other packages from the command line. - -usage: winget [<command>] [<options>] - -The following commands are available: - install Installs the given package - show Shows information about a package - source Manage sources of packages - search Find and show basic info of packages - list Display installed packages - upgrade Shows and performs available upgrades - uninstall Uninstalls the given package - hash Helper to hash installer files - validate Validates a manifest file - settings Open settings or set administrator settings - features Shows the status of experimental features - export Exports a list of the installed packages - import Installs all the packages in a file - -For more details on a specific command, pass it the help argument. [-?] - -The following options are available: - -v,--version Display the version of the tool - --info Display general info of the tool - -More help can be found at: https://aka.ms/winget-command-help - -.DESCRIPTION See help for winget.exe - -.PARAMETER Name + .SYNOPSIS + Remove a specific source. + .DESCRIPTION + Remove a specific source. The source must already exist to be removed. + .PARAMETER Name + Name of the source. + .INPUTS + None. -#> -} - + .OUTPUTS + None. + .EXAMPLE + PS> Remove-WinGetSource -Name Contoso +#> +} -function Reset-WinGetSource +function Reset-WinGetSource { [PowerShellCustomFunctionAttribute(RequiresElevation=$False)] -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( [Parameter(Position=0,ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true)] @@ -745,43 +634,27 @@ PROCESS { } # end PROCESS <# -.SYNOPSIS -Windows Package Manager (Preview) v1.3.1391-preview -Copyright (c) Microsoft Corporation. All rights reserved. - -The winget command line utility enables installing applications and other packages from the command line. - -usage: winget [<command>] [<options>] - -The following commands are available: - install Installs the given package - show Shows information about a package - source Manage sources of packages - search Find and show basic info of packages - list Display installed packages - upgrade Shows and performs available upgrades - uninstall Uninstalls the given package - hash Helper to hash installer files - validate Validates a manifest file - settings Open settings or set administrator settings - features Shows the status of experimental features - export Exports a list of the installed packages - import Installs all the packages in a file - -For more details on a specific command, pass it the help argument. [-?] - -The following options are available: - -v,--version Display the version of the tool - --info Display general info of the tool - -More help can be found at: https://aka.ms/winget-command-help - -.DESCRIPTION See help for winget.exe - -.PARAMETER Name + .SYNOPSIS + Drops existing sources. Without any argument, this command will drop all sources and add the defaults. + + .DESCRIPTION + Drops existing sources, potentially leaving any local data behind. Without any argument, it will drop all sources and add the defaults. + If a named source is provided, only that source will be dropped. + + .PARAMETER Name + Name of the source. + + .INPUTS + None. + .OUTPUTS + None. + .EXAMPLE + PS> Reset-WinGetSource + .EXAMPLE + PS> Reset-WinGetSource -Name Contoso #> }