diff --git a/reference/3.0/Microsoft.PowerShell.Core/Update-Help.md b/reference/3.0/Microsoft.PowerShell.Core/Update-Help.md index d1c3009a26c7..3838c042a7f1 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Update-Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Update-Help.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 5/16/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,10 +7,10 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210614 external help file: System.Management.Automation.dll-Help.xml title: Update-Help --- + # Update-Help ## SYNOPSIS - Downloads and installs the newest help files on your computer. ## SYNTAX @@ -18,39 +18,46 @@ Downloads and installs the newest help files on your computer. ### Path (Default) ``` -Update-Help [[-Module] ] [[-SourcePath] ] [-Recurse] [[-UICulture] ] - [-Credential ] [-UseDefaultCredentials] [-Force] [] +Update-Help [[-Module] ] [[-SourcePath] ] [[-UICulture] ] +[-Recurse] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ### LiteralPath ``` -Update-Help [[-Module] ] [-LiteralPath ] [-Recurse] [[-UICulture] ] - [-Credential ] [-UseDefaultCredentials] [-Force] [] +Update-Help [[-Module] ] [[-UICulture] ] [-LiteralPath ] +[-Recurse] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ## DESCRIPTION -The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on your computer. -You can use the `Get-Help` cmdlet to view the new help files immediately. -You do not have to restart PowerShell to make the change effective. -This feature enables you to install help files for modules that do not include them and to update help files on your computer so that they never become obsolete. +The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on +your computer. You don't need to restart PowerShell to make the change effective. You can use the +`Get-Help` cmdlet to view the new help files immediately. + +`Update-Help` checks the version of the help files on your computer. If you don't have help files +for a module or if your help files are outdated, `Update-Help` downloads the newest help files. The +help files can be downloaded and installed from the internet or a file share. -`Update-Help` checks the version of the help files on your computer. -If you do not have help files for a module or do not have the newest help files for a module, `Update-Help` downloads the newest help files from the Internet or a file share and installs them on your computer in the correct module folder. +Without parameters, `Update-Help` updates the help files for modules in the session and for all +installed modules that support Updatable Help. Modules that are installed but not loaded in the +current session are included. PowerShell modules are stored in a location listed in the +`$env:PSModulePath` environment variable. +For more information, see [about_Updatable_Help](./About/about_Updatable_Help.md). -Without parameters, `Update-Help` updates the help for modules in the session and for all installed modules, in a location listed in the `$env:PSModulePath` environment variable, that support Updatable Help, even if the module is not in the current session. -You can also use the **Module** parameter to update help for a particular module and use the **UICulture** parameter to download help files in multiple languages and locales. +You can use the **Module** parameter to update help files for a particular module. Use the +**UICulture** parameter to download help files in multiple languages and locales. -You can use `Update-Help` even on computers that are not connected to the Internet. -Use the `Save-Help` cmdlet to download help files from the Internet and save them in a file system location, such as a shared folder or file system directory. -Then use the **SourcePath** parameter of `Update-Help` to get the updated help files from a file system location and install them on the computer. +You can use `Update-Help` on computers that aren't connected to the internet. Use the `Save-Help` +cmdlet to download help files from the internet and save them in a file system location, such as a +shared folder or file system directory. Then use the **SourcePath** parameter of `Update-Help` to +download the updated help files from a file system location and install them on the computer. -You can even automate the running of `Update-Help` by adding an `Update-Help` cmdlet to your PowerShell profile. -By default, `Update-Help` runs only one time per day on each computer. -To override the once-per-day limit, use the **Force** parameter. +You can automate help updates by adding the `Update-Help` cmdlet to your PowerShell profile. By +default, `Update-Help` runs only one time per day on each computer. To override the once-per-day +limit, use the **Force** parameter. -This cmdlet was introduced in Windows PowerShell 3.0. +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. > [!IMPORTANT] > `Update-Help` requires administrative privileges. @@ -61,6 +68,7 @@ This cmdlet was introduced in Windows PowerShell 3.0. > To download or update the help files for modules in the PowerShell > installation directory (`$PSHOME\Modules`), including the PowerShell > Core modules, start PowerShell by using the Run as administrator option. +> For example: `Start-Process powershell.exe -Verb RunAs`. > > You can also update help files by using the Update Windows PowerShell Help > menu item in the Help menu in Windows PowerShell Integrated Scripting @@ -73,129 +81,162 @@ This cmdlet was introduced in Windows PowerShell 3.0. ## EXAMPLES -### Example 1: Update help for all modules +### Example 1: Update help files for all modules -This command updates help for all installed modules that support Updatable Help in the language specified by the UI culture that is set for Windows. - -To run this command, start PowerShell with the "Run as administrator" option (`Start-Process PowerShell -Verb RunAs`). +The `Update-Help` cmdlet updates help files for installed modules that support Updatable Help. The +user-interface (UI) culture language is set in the operating system. ```powershell Update-Help ``` -### Example 2: Update help for specified modules - -This command updates help only for the **ServerManager** module and for modules that have names that begin with "Microsoft.PowerShell". +### Example 2: Update help files for specified modules -Because these modules are in the `$pshome\Modules` directory, to run this command, start PowerShell with the "Run as administrator" option. +The `Update-Help` cmdlet updates help files only for module names that begin with +**Microsoft.PowerShell**. ```powershell -Update-Help -Module ServerManager, Microsoft.PowerShell* +Update-Help -Module Microsoft.PowerShell* ``` -### Example 3: Update help in different languages +### Example 3: Update help files for different languages -This command updates the Japanese and English help files for all modules. +The `Update-Help` cmdlet updates the Japanese (ja-JP) and English (en-US) help files for all +modules. -If a module currently does not provide help files for the specified UI culture, the error message lists the UI cultures that the module supports. -In this example, the error message indicates that the **ServerManager** module currently provides help files only in "en-US". +If a module doesn't provide help files for a specified UI culture, an error message is displayed for +the module and UI culture. In this example, the error message indicates that the **ja-JP** help +files were not found for module **Microsoft.PowerShell.Utility**. ```powershell Update-Help -UICulture ja-JP, en-US ``` -```output -Update-Help : Failed to update Help for the module(s) 'ServerManager' with UI culture(s) {ja-JP} : -The specified culture is not supported: ja-JP. Specify a culture from the following list: {en-US}. +```Output +Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Utility' with UI culture(s) {ja-JP} +No UI culture was found that matches the following pattern: ja-JP. ``` -### Example 4: Update help automatically - -This command creates a scheduled job that updates help for all modules on the computer every day at 3:00 in the morning. - -The command uses the `Register-ScheduledJob` cmdlet to create a scheduled job that runs an `Update-Help` command. -The command uses the **Credential** parameter to run the `Update-Help` cmdlet with the credentials of a member of the "Administrators" group on the computer. -The value of the **Trigger** parameter is a `New-JobTrigger` command that creates a job trigger that starts the job every day at "3:00 AM". +### Example 4: Update help files automatically -To run the `Register-ScheduledJob` command, start PowerShell with the "Run as administrator" option. -When you run the command, PowerShell prompts you for the password of the user specified in the value of the **Credential** parameter. -The credentials are stored with the scheduled job; you are not prompted when the job runs. - -You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. -You can also view and manage the scheduled job in Task Scheduler in the following path: "Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs". +This example creates a scheduled job that updates help for all modules every day at 3:00 AM. ```powershell -Register-ScheduledJob -Name UpdateHelpJob -Credential Domain01\User01 -ScriptBlock {Update-Help} -Trigger (New-JobTrigger -Daily -At "3 AM") +$jobParams = @{ + Name = 'UpdateHelpJob' + Credential = 'Domain01\User01' + ScriptBlock = '{Update-Help}' + Trigger = (New-JobTrigger -Daily -At "3 AM") +} +Register-ScheduledJob @jobParams ``` -```output +```Output Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 UpdateHelpJob 1 Update-Help True ``` -### Example 5: Update help on multiple computers from a file share +The `Register-ScheduledJob` cmdlet creates a scheduled job that runs an `Update-Help` command. The +command uses the **Credential** parameter to run `Update-Help` by using the credentials of a member +of the Administrators group on the computer. The value of the **Trigger** parameter is a +`New-JobTrigger` command that creates a job trigger that starts the job every day at 3:00 AM. -These commands download updated help files for system modules from the Internet and save them in file share. -Then the commands install the updated help files from the file share on multiple computers. -You can use a strategy like the one shown here to update the help files on numerous computers, even those that are behind firewalls or are not connected to the Internet. +To run the `Register-ScheduledJob` command, start PowerShell by using the **Run as administrator** +option. PowerShell prompts you for the password of the user specified in the **Credential** +parameter. The credentials are stored with the scheduled job. You aren't prompted when the job runs. -All of the commands in this example were run in a Windows PowerShell session that was started with the "Run as administrator" option. +You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` +cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. You can also view +and manage the scheduled job in Task Scheduler in the following path: -The first command uses the `Save-Help` cmdlet to download the newest help files for all modules that support Updatable Help. The command saves the downloaded help files in the "\\Server01\Share\PSHelp" file share.The command uses the **Credential** parameter of the `Save-Help` cmdlet to specify the credentials of a user who has permission to access the remote file share. By default, the command does not run with explicit credentials and attempts to access the file share might fail. +`Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs`. -The second command uses the `Invoke-Command` cmdlet to run `Update-Help` commands on many computers remotely.The `Invoke-Command` command gets the list of computers from the Servers.txt file. The `Update-Help` command installs the help files from the file share on all of the remote computers. The remote computer must be able to access the file share at the specified path.The `Update-Help` command uses the **SourcePath** parameter to get the updated help files from the file share, instead of the Internet, and the **Credential** parameter to run the command with explicit credentials. By default, the command runs with network token privileges and attempts to access the file share from each remote computer (a "second hop") might fail. +### Example 5: Update help files on multiple computers from a file share -```powershell -Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 -Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Update-Help -SourcePath \\Server01\Share\Help -Credential Domain01\Admin01} +In this example, updated help files are downloaded from the internet and saved in a file share. User +credentials are needed that have permissions to access the file share and install updates. When a +file share is used, it's possible to update computers that are behind firewalls or aren't connected +to the internet. + +``` +PS> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock { + Update-Help -SourcePath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +} ``` -### Example 6: Get a List of Updated Help Files +The `Save-Help` command downloads the newest help files for all modules that support Updatable Help. +The **DestinationPath** parameter saves the files in the `\\Server01\Share\PSHelp` file share. The +**Credential** parameter specifies a user who has permission to access the file share. -This command updates help for two modules. -It uses the **Verbose** common parameter of the `Update-Help` cmdlet to get a list of the help files that the command updated. +The `Invoke-Command` cmdlet runs remote `Update-Help` commands on multiple computers. The +**ComputerName** parameter gets a list of remote computers from the **Servers.txt** file. The +**ScriptBlock** parameter runs the `Update-Help` command and uses the **SourcePath** parameter to +specify the file share that contains the updated help files. The **Credential** parameter specifies +a user who can access the file share and run the remote `Update-Help` command. -Without the **Verbose** parameter, `Update-Help` does not display the results of the command. -The **Verbose** parameter is especially useful when you need to verify that you have updated help files for a particular module or a particular locale. +### Example 6: Get a list of updated help files + +The `Update-Help` cmdlet updates help for a specified module. The cmdlet uses the **Verbose** common +parameter to display the list of help files that were updated. You can use **Verbose** to view +output for all help files or help files for a specific module. + +Without the **Verbose** parameter, `Update-Help` doesn't display the results of the command. The +**Verbose** parameter output is useful to verify that the help files were updated or if the latest +version is installed. ```powershell -Update-Help -Module BestPractices, ServerManager -Verbose +Update-Help -Module Microsoft.PowerShell.Utility -Verbose ``` ### Example 7: Find modules that support Updatable Help -This command gets modules that support Updatable Help. +This example lists modules that support Updatable Help. The command uses the module's +**HelpInfoUri** property to identify modules that support Updatable Help. The **HelpInfoUri** +property contains an address that is redirected when the `Update-Help` cmdlet is run. -The command uses the **HelpInfoUri** property of modules to identify modules that support Updatable Help. -The value of the **HelpInfoUri** property contains the address of the Internet location where the module stores its Updatable Help information file. +```powershell +Get-Module -ListAvailable | Where-Object -Property HelpInfoUri +``` -This command uses the simplified syntax of the `Where-Object` cmdlet. -This syntax is introduced in Windows PowerShell 3.0. +```output + Directory: C:\program files\powershell\6\Modules -```powershell -Get-Module -ListAvailable | Where HelpInfoUri +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 6.1.0.0 CimCmdlets Core {Get-CimAssociatedInstance... } +Manifest 1.2.2.0 Microsoft.PowerShell.Archive Desk {Compress-Archive... } +Manifest 6.1.0.0 Microsoft.PowerShell.Diagnostics Core {Get-WinEvent, New-WinEvent} + + Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules + +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 2.0.1.0 Appx Core,Desk {Add-AppxPackage, ... } +Script 1.0.0.0 AssignedAccess Core,Desk {Clear-AssignedAccess, ... } +Manifest 1.0.0.0 BitLocker Core,Desk {Unlock-BitLocker, ... } ``` ### Example 8: Inventory updated help files -The "Get-UpdateHelpVersion.ps1" script creates an inventory of the Updatable Help files for each module and their version numbers. -Copy the script and paste it in a text file. +In this example, the script `Get-UpdateHelpVersion.ps1` creates an inventory of the Updatable Help +files for each module and their version numbers. -The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of modules. -For modules that support Updatable Help, the script looks for and parses the help information file (HelpInfo XML) to find the latest version number. +The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of +modules. For modules that support Updatable Help, the script looks for and parses the help +information file (*helpinfo.xml) to find the latest version number. The script uses the **PSCustomObject** class and a hash table to create a custom output object. -```powershell +``` # Get-UpdateHelpVersion.ps1 -Param - ( - [parameter(Mandatory=$False)] - [String[]] - $Module - ) -$HelpInfoNamespace = @{helpInfo="http://schemas.microsoft.com/powershell/help/2010/05"} +Param( + [parameter(Mandatory=$False)] + [String[]] + $Module +) +$HelpInfoNamespace = @{helpInfo='http://schemas.microsoft.com/powershell/help/2010/05'} if ($Module) { $Modules = Get-Module $Module -ListAvailable | where {$_.HelpInfoUri} } else { $Modules = Get-Module -ListAvailable | where {$_.HelpInfoUri} } @@ -207,7 +248,8 @@ foreach ($mModule in $Modules) if (Test-Path $mdir\*helpinfo.xml) { $mName=$mModule.Name - $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" + $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | + Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" foreach ($mNode in $mNodes) { $mCulture=$mNode.Node.UICultureName @@ -219,7 +261,7 @@ foreach ($mModule in $Modules) } ``` -```output +```Output ModuleName Culture Version ---------- ------- ------- ActiveDirectory en-US 3.0.0.0 @@ -227,18 +269,20 @@ ADCSAdministration en-US ADCSDeployment en-US 3.0.0.0 ADDSDeployment en-US 3.0.0.0 ADFS en-US 3.0.0.0 -... ``` ## PARAMETERS ### -Credential -Runs the command with credentials of a user who has permission to access the file system location specified by the **SourcePath** parameter. -This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is used in the command. +Specifies credentials of a user who has permission to access the file system location specified by +**SourcePath**. This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is +used in the command. -This parameter enables you to run `Update-Help` commands with the **SourcePath** parameter on remote computers. -By providing explicit credentials, you can run the command on a remote computer and access a file share on a third computer without encountering an "access denied" error or using CredSSP authentication to delegate credentials. +The **Credential** parameter enables you to run `Update-Help` commands with the **SourcePath** +parameter on remote computers. By providing explicit credentials, you can run the command on a +remote computer and access a file share on a third computer without encountering an access denied +error or using CredSSP authentication to delegate credentials. ```yaml Type: PSCredential @@ -254,13 +298,21 @@ Accept wildcard characters: False ### -Force -Overrides the once-per-day limitation, version checking, and the 1 GB per module limit. +Indicates that this cmdlet doesn't follow the once-per-day limitation, skips version checking, and +downloads files that exceed the 1 GB limit. -Without this parameter, `Update-Help` runs only once in each 24-hour period, downloads are limited to 1 GB of uncompressed content per module and help files are installed only when they are newer than the files on the computer. +Without this parameter, `Update-Help` runs only once in each 24-hour period. Downloads are limited +to 1 GB of uncompressed content per module and help files are only installed when they're newer than +the existing files on the computer. -The once-per-day limit protects the servers that host the help files and makes it practical for you to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of repeated connections or downloads. +The once-per-day limit protects the servers that host the help files and makes it practical for you +to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of +repeated connections or downloads. -To update help for a module in multiple UI cultures without the **Force** parameter, include all UI cultures in the same command, such as: `Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` +To update help for a module in multiple UI cultures without the **Force** parameter, include all UI +cultures in the same command, such as: + +`Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` ```yaml Type: SwitchParameter @@ -276,15 +328,17 @@ Accept wildcard characters: False ### -LiteralPath -Gets updated help files from the specified directory instead of downloading them from the Internet. -Use this parameter or the **SourcePath** parameter if you have used the `Save-Help` cmdlet to download help files to a directory. +Specifies the folder for updated help files instead of downloading them from the internet. Use this +parameter or **SourcePath** if you've used the `Save-Help` cmdlet to download help files to a +directory. -You can also pipe a directory object, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to `Update-Help`. +You can pipeline a directory object, such as from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -Unlike the value of the **SourcePath** parameter, the value of the **LiteralPath** parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Unlike the value of **SourcePath**, the value of **LiteralPath** is used exactly as it's typed. No +characters are interpreted as wildcard characters. If the path includes escape characters, enclose +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. ```yaml Type: String[] @@ -300,20 +354,22 @@ Accept wildcard characters: False ### -Module -Updates help for the specified modules. -Enter one or more module names or name patterns in a comma-separated list, or specify a file that lists one module name on each line. -Wildcard characters are permitted. -You can also pipe modules from the `Get-Module` cmdlet, to the `Update-Help` cmdlet. +Updates help for the specified modules. Enter one or more module names or name patterns in a +comma-separated list, or specify a file that lists one module name on each line. Wildcard characters +are permitted. You can pipeline modules from the `Get-Module` cmdlet to the `Update-Help` cmdlet. -The modules that you specify must be installed on the computer, but they do not need to be imported into the current session. -You can specify any module in the session or any module that is installed in a location listed in the **PSModulePath** environment variable. +The modules that you specify must be installed on the computer, but they don't have to be imported +into the current session. You can specify any module in the session or any module that is installed +in a location listed in the `$env:PSModulePath` environment variable. -A value of "*" (all) attempts to update help for all modules that are installed on the computer, including modules that do not support Updatable Help. -This value might generate errors as the command encounters modules that do not support Updatable Help. -Instead, run an `Update-Help` command without parameters. +A value of `*` (all) attempts to update help for all modules that are installed on the computer. +Modules that don't support Updatable Help are included. This value might generate errors when the +command encounters modules that don't support Updatable Help. Instead, run `Update-Help` without +parameters. -The **Module** parameter of the `Update-Help` cmdlet does not accept the full path to a module file or module manifest file. -To update help for a module that is not in a **PSModulePath** location, import the module into the current session before running the `Update-Help` command. +The **Module** parameter of the `Update-Help` cmdlet doesn't accept the full path of a module file +or module manifest file. To update help for a module that isn't in a `$env:PSModulePath` location, +import the module into the current session before you run the `Update-Help` command. ```yaml Type: String[] @@ -321,16 +377,16 @@ Parameter Sets: (All) Aliases: Name Required: False -Position: 1 -Default value: All modules in the current session +Position: 0 +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True ``` ### -Recurse -Searches recursively for help files in the specified directory. -This parameter is valid only when the **SourcePath** parameter is used in the command. +Performs a recursive search for help files in the specified directory. This parameter is valid only +when the command uses the **SourcePath** parameter. ```yaml Type: SwitchParameter @@ -346,16 +402,17 @@ Accept wildcard characters: False ### -SourcePath -Gets updated help files from the specified file system directory, instead of downloading them from the Internet. -Enter the path to a directory. -Do not specify a file name or file name extension. -You can also pipe a directory object, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to `Update-Help`. +Specifies a file system folder where `Update-Help` gets updated help files, instead of downloading +them from the internet. Enter the path of a folder. Don't specify a file name or file name +extension. You can pipeline a folder, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -By default, `Update-Help` downloads updated help files from the Internet. -Use this parameter when you have used the `Save-Help` cmdlet to download updated help files to a directory. +By default, `Update-Help` downloads updated help files from the internet. Use **SourcePath** when +you've used the `Save-Help` cmdlet to download updated help files to a directory. -Administrators can use the "Set the default source path for `Update-Help`" Group Policy setting under Computer Configuration to specify a default value for the **SourcePath** parameter. -This Group Policy setting prevents users from using `Update-Help` to download help files from the Internet. +To specify a default value for **SourcePath**, go to **Group Policy**, **Computer Configuration**, +and **Set the default source path for Update-Help**. This Group Policy setting prevents users from +using `Update-Help` to download help files from the internet. For more information, see [about_Group_Policy_Settings](./About/about_Group_Policy_Settings.md). ```yaml @@ -364,7 +421,7 @@ Parameter Sets: Path Aliases: Required: False -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -372,15 +429,17 @@ Accept wildcard characters: False ### -UICulture -Gets updated help files for the specified UI culture. -Enter one or more language codes, such as "es-ES", a variable that contains culture objects, or a command that gets culture objects, such as a `Get-Culture` or `Get-UICulture` command. -Wildcards are not permitted and you cannot submit a partial language code, such as "de". +Specifies UI culture values that `Update-Help` uses to get updated help files. Enter one or more +language codes, such as **es-ES**, a variable that contains culture objects, or a command that gets +culture objects, such as a `Get-Culture` or `Get-UICulture` command. Wildcard characters aren't +permitted and you can't submit a partial language code, such as **de**. -By default, `Update-Help` gets help files in the UI culture set for Windows or its fallback culture. -If you use the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture, not in any fallback culture. +By default, `Update-Help` gets help files in the UI culture set for the operating system. If you +specify the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture. -Commands that use the **UICulture** parameter succeed only when the module provides help files for the specified UI culture. -If the command fails because the specified UI culture is not supported, the error message includes a list of UI cultures that the module supports. +Commands that use the **UICulture** parameter succeed only when the module provides help files for +the specified UI culture. If the command fails because the specified UI culture isn't supported, an +error message is displayed. ```yaml Type: CultureInfo[] @@ -388,18 +447,19 @@ Parameter Sets: (All) Aliases: Required: False -Position: 3 -Default value: Current UI culture +Position: 2 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -UseDefaultCredentials -Runs the command, including the Internet download, with the credentials of the current user. -By default, the command runs without explicit credentials. +Indicates that `Update-Help` runs the command, including the internet download, by using the +credentials of the current user. By default, the command runs without explicit credentials. -This parameter is effective only when the web download uses **NTLM**, **Negotiate**, or **Kerberos-based** authentication. +This parameter is effective only when the web download uses NT LAN Manager (NTLM), negotiate, or +Kerberos-based authentication. ```yaml Type: SwitchParameter @@ -415,7 +475,9 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](./About/about_CommonParameters.md). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -425,42 +487,67 @@ You can pipe a directory path to `Update-Help`. ### System.Management.Automation.PSModuleInfo -You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. +You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. ## OUTPUTS ### None -`Update-Help` does not generate any output. +`Update-Help` doesn't generate any output. ## NOTES -- To update help for the Windows PowerShell Core modules (which contain the commands that are installed with Windows PowerShell) or any module in the $pshome\Modules directory, start Windows PowerShell with the "Run as administrator" option. - - Only members of the "Administrators" group on the computer can update help for the for the PowerShell Core modules (the commands that are installed with Windows PowerShell) and for modules in the `$pshome\Modules` directory. - If you do not have permission to update help files, you might be able to read the help topics online. - To open the online version of any cmdlet help topic, type `Get-Help \ -Online`. - -- Modules are the smallest unit of updatable help. You cannot update help for a particular cmdlet; only for all cmdlets in module. To find the module that contains a particular cmdlet, use the **ModuleName** property of the `Get-Command` cmdlet, for example, `(Get-Command \).ModuleName` -- Because help files are installed in the module directory, the `Update-Help` cmdlet can install updated help file only for modules that are installed on the computer. However, the `Save-Help` cmdlet can save help for modules that are not installed on the computer. -- If `Update-Help` cannot find updated help files for a module, or cannot find updated help in the specified language, it continues silently without displaying an error message. To see status and progress details, use the **Verbose** parameter. -- The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It does not work in earlier versions of Windows PowerShell. On computers that have both the Windows PowerShell 2.0 engine and Windows PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and update help files. The help files are accessible to both Windows PowerShell 2.0 and Windows PowerShell 3.0. -- The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. -- `Update-Help` supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. -- To update help for a module in a location that is not listed in the **PSModulePath** environment variable, import the module into the current session and then run an `Update-Help` command. Run the `Update-Help` command without parameters or use the **Module** parameter to specify the module name. The **Module** parameter of the `Update-Help` and `Save-Help` cmdlets does not accept the full path to a module file or module manifest file. -- Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules that you author, see "Supporting Updatable Help" in the MSDN Library at http://go.microsoft.com/fwlink/?LinkID=242129. -- The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment (Windows PE). +To update help for the PowerShell Core modules, that contain the commands that are installed with +PowerShell, or any module in the `$PSHOME\Modules` directory, start PowerShell with the option to +**Run as administrator**. + +Only members of the Administrators group on the computer can update help for the PowerShell Core +modules, the commands that are installed together with PowerShell, and for modules in the +`$PSHOME\Modules` folder. If you don't have permission to update help files, you can read the help +files online. For example, `Get-Help Update-Help -Online`. + +Modules are the smallest unit of updatable help. You can't update help for a particular cmdlet. To +find the module that contains a particular cmdlet, use the **ModuleName** property of the +`Get-Command` cmdlet, for example, `(Get-Command Update-Help).ModuleName`. + +Because help files are installed in the module directory, the `Update-Help` cmdlet can install +updated help file only for modules that are installed on the computer. However, the `Save-Help` +cmdlet can save help for modules that aren't installed on the computer. + +If `Update-Help` can't find updated help files for a module, or can't find updated help in the +specified language, it continues silently without displaying an error message. To see status and +progress details, use the **Verbose** parameter. + +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It doesn't work in earlier +versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows +PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and +update help files. The help files are available to both Windows PowerShell 2.0 and Windows +PowerShell 3.0. + +The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 +for HTTP and port 443 for HTTPS. + +`Update-Help` supports all modules and the PowerShell Core snap-ins. It doesn't support any other +snap-ins. + +To update help for a module in a location that isn't listed in the `$env:PSModulePath` environment +variable, import the module into the current session and then run an `Update-Help` command. Run +`Update-Help` without parameters or use the **Module** parameter to specify the module name. The +**Module** parameter of the `Update-Help` and `Save-Help` cmdlets doesn't accept the full path of a +module file or module manifest file. + +Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules +that you author, see [Supporting Updatable Help](/powershell/developer/module/supporting-updatable-help). + +The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment +(Windows PE). ## RELATED LINKS -[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Culture](../Microsoft.PowerShell.Utility/Get-Culture.md) [Get-Help](Get-Help.md) -[Get-Item](../Microsoft.PowerShell.Management/Get-Item.md) - [Get-Module](Get-Module.md) [Get-UICulture](../Microsoft.PowerShell.Utility/Get-UICulture.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/Update-Help.md b/reference/4.0/Microsoft.PowerShell.Core/Update-Help.md index 8d0d116bd257..4640b5add7e4 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Update-Help.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Update-Help.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 5/16/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,10 +7,10 @@ online version: http://go.microsoft.com/fwlink/p/?linkid=289621 external help file: System.Management.Automation.dll-Help.xml title: Update-Help --- + # Update-Help ## SYNOPSIS - Downloads and installs the newest help files on your computer. ## SYNTAX @@ -18,39 +18,46 @@ Downloads and installs the newest help files on your computer. ### Path (Default) ``` -Update-Help [[-Module] ] [[-SourcePath] ] [-Recurse] [[-UICulture] ] - [-Credential ] [-UseDefaultCredentials] [-Force] [] +Update-Help [[-Module] ] [[-SourcePath] ] [[-UICulture] ] +[-Recurse] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ### LiteralPath ``` -Update-Help [[-Module] ] [-LiteralPath ] [-Recurse] [[-UICulture] ] - [-Credential ] [-UseDefaultCredentials] [-Force] [] +Update-Help [[-Module] ] [[-UICulture] ] [-LiteralPath ] +[-Recurse] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ## DESCRIPTION -The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on your computer. -You can use the `Get-Help` cmdlet to view the new help files immediately. -You do not have to restart PowerShell to make the change effective. -This feature enables you to install help files for modules that do not include them and to update help files on your computer so that they never become obsolete. +The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on +your computer. You don't need to restart PowerShell to make the change effective. You can use the +`Get-Help` cmdlet to view the new help files immediately. + +`Update-Help` checks the version of the help files on your computer. If you don't have help files +for a module or if your help files are outdated, `Update-Help` downloads the newest help files. The +help files can be downloaded and installed from the internet or a file share. -`Update-Help` checks the version of the help files on your computer. -If you do not have help files for a module or do not have the newest help files for a module, `Update-Help` downloads the newest help files from the Internet or a file share and installs them on your computer in the correct module folder. +Without parameters, `Update-Help` updates the help files for modules in the session and for all +installed modules that support Updatable Help. Modules that are installed but not loaded in the +current session are included. PowerShell modules are stored in a location listed in the +`$env:PSModulePath` environment variable. +For more information, see [about_Updatable_Help](./About/about_Updatable_Help.md). -Without parameters, `Update-Help` updates the help for modules in the session and for all installed modules, in a location listed in the `$env:PSModulePath` environment variable, that support Updatable Help, even if the module is not in the current session. -You can also use the **Module** parameter to update help for a particular module and use the **UICulture** parameter to download help files in multiple languages and locales. +You can use the **Module** parameter to update help files for a particular module. Use the +**UICulture** parameter to download help files in multiple languages and locales. -You can use `Update-Help` even on computers that are not connected to the Internet. -Use the `Save-Help` cmdlet to download help files from the Internet and save them in a file system location, such as a shared folder or file system directory. -Then use the **SourcePath** parameter of `Update-Help` to get the updated help files from a file system location and install them on the computer. +You can use `Update-Help` on computers that aren't connected to the internet. Use the `Save-Help` +cmdlet to download help files from the internet and save them in a file system location, such as a +shared folder or file system directory. Then use the **SourcePath** parameter of `Update-Help` to +download the updated help files from a file system location and install them on the computer. -You can even automate the running of `Update-Help` by adding an `Update-Help` cmdlet to your PowerShell profile. -By default, `Update-Help` runs only one time per day on each computer. -To override the once-per-day limit, use the **Force** parameter. +You can automate help updates by adding the `Update-Help` cmdlet to your PowerShell profile. By +default, `Update-Help` runs only one time per day on each computer. To override the once-per-day +limit, use the **Force** parameter. -This cmdlet was introduced in Windows PowerShell 3.0. +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. > [!IMPORTANT] > `Update-Help` requires administrative privileges. @@ -61,6 +68,7 @@ This cmdlet was introduced in Windows PowerShell 3.0. > To download or update the help files for modules in the PowerShell > installation directory (`$PSHOME\Modules`), including the PowerShell > Core modules, start PowerShell by using the Run as administrator option. +> For example: `Start-Process powershell.exe -Verb RunAs`. > > You can also update help files by using the Update Windows PowerShell Help > menu item in the Help menu in Windows PowerShell Integrated Scripting @@ -73,129 +81,162 @@ This cmdlet was introduced in Windows PowerShell 3.0. ## EXAMPLES -### Example 1: Update help for all modules +### Example 1: Update help files for all modules -This command updates help for all installed modules that support Updatable Help in the language specified by the UI culture that is set for Windows. - -To run this command, start PowerShell with the "Run as administrator" option (`Start-Process PowerShell -Verb RunAs`). +The `Update-Help` cmdlet updates help files for installed modules that support Updatable Help. The +user-interface (UI) culture language is set in the operating system. ```powershell Update-Help ``` -### Example 2: Update help for specified modules - -This command updates help only for the **ServerManager** module and for modules that have names that begin with "Microsoft.PowerShell". +### Example 2: Update help files for specified modules -Because these modules are in the `$pshome\Modules` directory, to run this command, start PowerShell with the "Run as administrator" option. +The `Update-Help` cmdlet updates help files only for module names that begin with +**Microsoft.PowerShell**. ```powershell -Update-Help -Module ServerManager, Microsoft.PowerShell* +Update-Help -Module Microsoft.PowerShell* ``` -### Example 3: Update help in different languages +### Example 3: Update help files for different languages -This command updates the Japanese and English help files for all modules. +The `Update-Help` cmdlet updates the Japanese (ja-JP) and English (en-US) help files for all +modules. -If a module currently does not provide help files for the specified UI culture, the error message lists the UI cultures that the module supports. -In this example, the error message indicates that the **ServerManager** module currently provides help files only in "en-US". +If a module doesn't provide help files for a specified UI culture, an error message is displayed for +the module and UI culture. In this example, the error message indicates that the **ja-JP** help +files were not found for module **Microsoft.PowerShell.Utility**. ```powershell Update-Help -UICulture ja-JP, en-US ``` -```output -Update-Help : Failed to update Help for the module(s) 'ServerManager' with UI culture(s) {ja-JP} : -The specified culture is not supported: ja-JP. Specify a culture from the following list: {en-US}. +```Output +Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Utility' with UI culture(s) {ja-JP} +No UI culture was found that matches the following pattern: ja-JP. ``` -### Example 4: Update help automatically - -This command creates a scheduled job that updates help for all modules on the computer every day at 3:00 in the morning. - -The command uses the `Register-ScheduledJob` cmdlet to create a scheduled job that runs an `Update-Help` command. -The command uses the **Credential** parameter to run the `Update-Help` cmdlet with the credentials of a member of the "Administrators" group on the computer. -The value of the **Trigger** parameter is a `New-JobTrigger` command that creates a job trigger that starts the job every day at "3:00 AM". +### Example 4: Update help files automatically -To run the `Register-ScheduledJob` command, start PowerShell with the "Run as administrator" option. -When you run the command, PowerShell prompts you for the password of the user specified in the value of the **Credential** parameter. -The credentials are stored with the scheduled job; you are not prompted when the job runs. - -You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. -You can also view and manage the scheduled job in Task Scheduler in the following path: "Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs". +This example creates a scheduled job that updates help for all modules every day at 3:00 AM. ```powershell -Register-ScheduledJob -Name UpdateHelpJob -Credential Domain01\User01 -ScriptBlock {Update-Help} -Trigger (New-JobTrigger -Daily -At "3 AM") +$jobParams = @{ + Name = 'UpdateHelpJob' + Credential = 'Domain01\User01' + ScriptBlock = '{Update-Help}' + Trigger = (New-JobTrigger -Daily -At "3 AM") +} +Register-ScheduledJob @jobParams ``` -```output +```Output Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 UpdateHelpJob 1 Update-Help True ``` -### Example 5: Update help on multiple computers from a file share +The `Register-ScheduledJob` cmdlet creates a scheduled job that runs an `Update-Help` command. The +command uses the **Credential** parameter to run `Update-Help` by using the credentials of a member +of the Administrators group on the computer. The value of the **Trigger** parameter is a +`New-JobTrigger` command that creates a job trigger that starts the job every day at 3:00 AM. -These commands download updated help files for system modules from the Internet and save them in file share. -Then the commands install the updated help files from the file share on multiple computers. -You can use a strategy like the one shown here to update the help files on numerous computers, even those that are behind firewalls or are not connected to the Internet. +To run the `Register-ScheduledJob` command, start PowerShell by using the **Run as administrator** +option. PowerShell prompts you for the password of the user specified in the **Credential** +parameter. The credentials are stored with the scheduled job. You aren't prompted when the job runs. -All of the commands in this example were run in a Windows PowerShell session that was started with the "Run as administrator" option. +You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` +cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. You can also view +and manage the scheduled job in Task Scheduler in the following path: -The first command uses the `Save-Help` cmdlet to download the newest help files for all modules that support Updatable Help. The command saves the downloaded help files in the "\\Server01\Share\PSHelp" file share.The command uses the **Credential** parameter of the `Save-Help` cmdlet to specify the credentials of a user who has permission to access the remote file share. By default, the command does not run with explicit credentials and attempts to access the file share might fail. +`Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs`. -The second command uses the `Invoke-Command` cmdlet to run `Update-Help` commands on many computers remotely.The `Invoke-Command` command gets the list of computers from the Servers.txt file. The `Update-Help` command installs the help files from the file share on all of the remote computers. The remote computer must be able to access the file share at the specified path.The `Update-Help` command uses the **SourcePath** parameter to get the updated help files from the file share, instead of the Internet, and the **Credential** parameter to run the command with explicit credentials. By default, the command runs with network token privileges and attempts to access the file share from each remote computer (a "second hop") might fail. +### Example 5: Update help files on multiple computers from a file share -```powershell -Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 -Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Update-Help -SourcePath \\Server01\Share\Help -Credential Domain01\Admin01} +In this example, updated help files are downloaded from the internet and saved in a file share. User +credentials are needed that have permissions to access the file share and install updates. When a +file share is used, it's possible to update computers that are behind firewalls or aren't connected +to the internet. + +``` +PS> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock { + Update-Help -SourcePath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +} ``` -### Example 6: Get a List of Updated Help Files +The `Save-Help` command downloads the newest help files for all modules that support Updatable Help. +The **DestinationPath** parameter saves the files in the `\\Server01\Share\PSHelp` file share. The +**Credential** parameter specifies a user who has permission to access the file share. -This command updates help for two modules. -It uses the **Verbose** common parameter of the `Update-Help` cmdlet to get a list of the help files that the command updated. +The `Invoke-Command` cmdlet runs remote `Update-Help` commands on multiple computers. The +**ComputerName** parameter gets a list of remote computers from the **Servers.txt** file. The +**ScriptBlock** parameter runs the `Update-Help` command and uses the **SourcePath** parameter to +specify the file share that contains the updated help files. The **Credential** parameter specifies +a user who can access the file share and run the remote `Update-Help` command. -Without the **Verbose** parameter, `Update-Help` does not display the results of the command. -The **Verbose** parameter is especially useful when you need to verify that you have updated help files for a particular module or a particular locale. +### Example 6: Get a list of updated help files + +The `Update-Help` cmdlet updates help for a specified module. The cmdlet uses the **Verbose** common +parameter to display the list of help files that were updated. You can use **Verbose** to view +output for all help files or help files for a specific module. + +Without the **Verbose** parameter, `Update-Help` doesn't display the results of the command. The +**Verbose** parameter output is useful to verify that the help files were updated or if the latest +version is installed. ```powershell -Update-Help -Module BestPractices, ServerManager -Verbose +Update-Help -Module Microsoft.PowerShell.Utility -Verbose ``` ### Example 7: Find modules that support Updatable Help -This command gets modules that support Updatable Help. +This example lists modules that support Updatable Help. The command uses the module's +**HelpInfoUri** property to identify modules that support Updatable Help. The **HelpInfoUri** +property contains an address that is redirected when the `Update-Help` cmdlet is run. -The command uses the **HelpInfoUri** property of modules to identify modules that support Updatable Help. -The value of the **HelpInfoUri** property contains the address of the Internet location where the module stores its Updatable Help information file. +```powershell +Get-Module -ListAvailable | Where-Object -Property HelpInfoUri +``` -This command uses the simplified syntax of the `Where-Object` cmdlet. -This syntax is introduced in Windows PowerShell 3.0. +```output + Directory: C:\program files\powershell\6\Modules -```powershell -Get-Module -ListAvailable | Where HelpInfoUri +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 6.1.0.0 CimCmdlets Core {Get-CimAssociatedInstance... } +Manifest 1.2.2.0 Microsoft.PowerShell.Archive Desk {Compress-Archive... } +Manifest 6.1.0.0 Microsoft.PowerShell.Diagnostics Core {Get-WinEvent, New-WinEvent} + + Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules + +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 2.0.1.0 Appx Core,Desk {Add-AppxPackage, ... } +Script 1.0.0.0 AssignedAccess Core,Desk {Clear-AssignedAccess, ... } +Manifest 1.0.0.0 BitLocker Core,Desk {Unlock-BitLocker, ... } ``` ### Example 8: Inventory updated help files -The "Get-UpdateHelpVersion.ps1" script creates an inventory of the Updatable Help files for each module and their version numbers. -Copy the script and paste it in a text file. +In this example, the script `Get-UpdateHelpVersion.ps1` creates an inventory of the Updatable Help +files for each module and their version numbers. -The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of modules. -For modules that support Updatable Help, the script looks for and parses the help information file (HelpInfo XML) to find the latest version number. +The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of +modules. For modules that support Updatable Help, the script looks for and parses the help +information file (*helpinfo.xml) to find the latest version number. The script uses the **PSCustomObject** class and a hash table to create a custom output object. -```powershell +``` # Get-UpdateHelpVersion.ps1 -Param - ( - [parameter(Mandatory=$False)] - [String[]] - $Module - ) -$HelpInfoNamespace = @{helpInfo="http://schemas.microsoft.com/powershell/help/2010/05"} +Param( + [parameter(Mandatory=$False)] + [String[]] + $Module +) +$HelpInfoNamespace = @{helpInfo='http://schemas.microsoft.com/powershell/help/2010/05'} if ($Module) { $Modules = Get-Module $Module -ListAvailable | where {$_.HelpInfoUri} } else { $Modules = Get-Module -ListAvailable | where {$_.HelpInfoUri} } @@ -207,7 +248,8 @@ foreach ($mModule in $Modules) if (Test-Path $mdir\*helpinfo.xml) { $mName=$mModule.Name - $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" + $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | + Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" foreach ($mNode in $mNodes) { $mCulture=$mNode.Node.UICultureName @@ -219,7 +261,7 @@ foreach ($mModule in $Modules) } ``` -```output +```Output ModuleName Culture Version ---------- ------- ------- ActiveDirectory en-US 3.0.0.0 @@ -227,18 +269,20 @@ ADCSAdministration en-US ADCSDeployment en-US 3.0.0.0 ADDSDeployment en-US 3.0.0.0 ADFS en-US 3.0.0.0 -... ``` ## PARAMETERS ### -Credential -Runs the command with credentials of a user who has permission to access the file system location specified by the **SourcePath** parameter. -This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is used in the command. +Specifies credentials of a user who has permission to access the file system location specified by +**SourcePath**. This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is +used in the command. -This parameter enables you to run `Update-Help` commands with the **SourcePath** parameter on remote computers. -By providing explicit credentials, you can run the command on a remote computer and access a file share on a third computer without encountering an "access denied" error or using CredSSP authentication to delegate credentials. +The **Credential** parameter enables you to run `Update-Help` commands with the **SourcePath** +parameter on remote computers. By providing explicit credentials, you can run the command on a +remote computer and access a file share on a third computer without encountering an access denied +error or using CredSSP authentication to delegate credentials. ```yaml Type: PSCredential @@ -254,13 +298,21 @@ Accept wildcard characters: False ### -Force -Overrides the once-per-day limitation, version checking, and the 1 GB per module limit. +Indicates that this cmdlet doesn't follow the once-per-day limitation, skips version checking, and +downloads files that exceed the 1 GB limit. -Without this parameter, `Update-Help` runs only once in each 24-hour period, downloads are limited to 1 GB of uncompressed content per module and help files are installed only when they are newer than the files on the computer. +Without this parameter, `Update-Help` runs only once in each 24-hour period. Downloads are limited +to 1 GB of uncompressed content per module and help files are only installed when they're newer than +the existing files on the computer. -The once-per-day limit protects the servers that host the help files and makes it practical for you to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of repeated connections or downloads. +The once-per-day limit protects the servers that host the help files and makes it practical for you +to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of +repeated connections or downloads. -To update help for a module in multiple UI cultures without the **Force** parameter, include all UI cultures in the same command, such as: `Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` +To update help for a module in multiple UI cultures without the **Force** parameter, include all UI +cultures in the same command, such as: + +`Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` ```yaml Type: SwitchParameter @@ -276,15 +328,17 @@ Accept wildcard characters: False ### -LiteralPath -Gets updated help files from the specified directory instead of downloading them from the Internet. -Use this parameter or the **SourcePath** parameter if you have used the `Save-Help` cmdlet to download help files to a directory. +Specifies the folder for updated help files instead of downloading them from the internet. Use this +parameter or **SourcePath** if you've used the `Save-Help` cmdlet to download help files to a +directory. -You can also pipe a directory object, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to `Update-Help`. +You can pipeline a directory object, such as from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -Unlike the value of the **SourcePath** parameter, the value of the **LiteralPath** parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Unlike the value of **SourcePath**, the value of **LiteralPath** is used exactly as it's typed. No +characters are interpreted as wildcard characters. If the path includes escape characters, enclose +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. ```yaml Type: String[] @@ -300,20 +354,22 @@ Accept wildcard characters: False ### -Module -Updates help for the specified modules. -Enter one or more module names or name patterns in a comma-separated list, or specify a file that lists one module name on each line. -Wildcard characters are permitted. -You can also pipe modules from the `Get-Module` cmdlet, to the `Update-Help` cmdlet. +Updates help for the specified modules. Enter one or more module names or name patterns in a +comma-separated list, or specify a file that lists one module name on each line. Wildcard characters +are permitted. You can pipeline modules from the `Get-Module` cmdlet to the `Update-Help` cmdlet. -The modules that you specify must be installed on the computer, but they do not need to be imported into the current session. -You can specify any module in the session or any module that is installed in a location listed in the **PSModulePath** environment variable. +The modules that you specify must be installed on the computer, but they don't have to be imported +into the current session. You can specify any module in the session or any module that is installed +in a location listed in the `$env:PSModulePath` environment variable. -A value of "*" (all) attempts to update help for all modules that are installed on the computer, including modules that do not support Updatable Help. -This value might generate errors as the command encounters modules that do not support Updatable Help. -Instead, run an `Update-Help` command without parameters. +A value of `*` (all) attempts to update help for all modules that are installed on the computer. +Modules that don't support Updatable Help are included. This value might generate errors when the +command encounters modules that don't support Updatable Help. Instead, run `Update-Help` without +parameters. -The **Module** parameter of the `Update-Help` cmdlet does not accept the full path to a module file or module manifest file. -To update help for a module that is not in a **PSModulePath** location, import the module into the current session before running the `Update-Help` command. +The **Module** parameter of the `Update-Help` cmdlet doesn't accept the full path of a module file +or module manifest file. To update help for a module that isn't in a `$env:PSModulePath` location, +import the module into the current session before you run the `Update-Help` command. ```yaml Type: String[] @@ -321,16 +377,16 @@ Parameter Sets: (All) Aliases: Name Required: False -Position: 1 -Default value: All modules in the current session +Position: 0 +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True ``` ### -Recurse -Searches recursively for help files in the specified directory. -This parameter is valid only when the **SourcePath** parameter is used in the command. +Performs a recursive search for help files in the specified directory. This parameter is valid only +when the command uses the **SourcePath** parameter. ```yaml Type: SwitchParameter @@ -346,16 +402,17 @@ Accept wildcard characters: False ### -SourcePath -Gets updated help files from the specified file system directory, instead of downloading them from the Internet. -Enter the path to a directory. -Do not specify a file name or file name extension. -You can also pipe a directory object, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to `Update-Help`. +Specifies a file system folder where `Update-Help` gets updated help files, instead of downloading +them from the internet. Enter the path of a folder. Don't specify a file name or file name +extension. You can pipeline a folder, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -By default, `Update-Help` downloads updated help files from the Internet. -Use this parameter when you have used the `Save-Help` cmdlet to download updated help files to a directory. +By default, `Update-Help` downloads updated help files from the internet. Use **SourcePath** when +you've used the `Save-Help` cmdlet to download updated help files to a directory. -Administrators can use the "Set the default source path for `Update-Help`" Group Policy setting under Computer Configuration to specify a default value for the **SourcePath** parameter. -This Group Policy setting prevents users from using `Update-Help` to download help files from the Internet. +To specify a default value for **SourcePath**, go to **Group Policy**, **Computer Configuration**, +and **Set the default source path for Update-Help**. This Group Policy setting prevents users from +using `Update-Help` to download help files from the internet. For more information, see [about_Group_Policy_Settings](./About/about_Group_Policy_Settings.md). ```yaml @@ -364,7 +421,7 @@ Parameter Sets: Path Aliases: Required: False -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -372,15 +429,17 @@ Accept wildcard characters: False ### -UICulture -Gets updated help files for the specified UI culture. -Enter one or more language codes, such as "es-ES", a variable that contains culture objects, or a command that gets culture objects, such as a `Get-Culture` or `Get-UICulture` command. -Wildcards are not permitted and you cannot submit a partial language code, such as "de". +Specifies UI culture values that `Update-Help` uses to get updated help files. Enter one or more +language codes, such as **es-ES**, a variable that contains culture objects, or a command that gets +culture objects, such as a `Get-Culture` or `Get-UICulture` command. Wildcard characters aren't +permitted and you can't submit a partial language code, such as **de**. -By default, `Update-Help` gets help files in the UI culture set for Windows or its fallback culture. -If you use the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture, not in any fallback culture. +By default, `Update-Help` gets help files in the UI culture set for the operating system. If you +specify the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture. -Commands that use the **UICulture** parameter succeed only when the module provides help files for the specified UI culture. -If the command fails because the specified UI culture is not supported, the error message includes a list of UI cultures that the module supports. +Commands that use the **UICulture** parameter succeed only when the module provides help files for +the specified UI culture. If the command fails because the specified UI culture isn't supported, an +error message is displayed. ```yaml Type: CultureInfo[] @@ -388,18 +447,19 @@ Parameter Sets: (All) Aliases: Required: False -Position: 3 -Default value: Current UI culture +Position: 2 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -UseDefaultCredentials -Runs the command, including the Internet download, with the credentials of the current user. -By default, the command runs without explicit credentials. +Indicates that `Update-Help` runs the command, including the internet download, by using the +credentials of the current user. By default, the command runs without explicit credentials. -This parameter is effective only when the web download uses **NTLM**, **Negotiate**, or **Kerberos-based** authentication. +This parameter is effective only when the web download uses NT LAN Manager (NTLM), negotiate, or +Kerberos-based authentication. ```yaml Type: SwitchParameter @@ -415,7 +475,9 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](./About/about_CommonParameters.md). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -425,42 +487,67 @@ You can pipe a directory path to `Update-Help`. ### System.Management.Automation.PSModuleInfo -You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. +You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. ## OUTPUTS ### None -`Update-Help` does not generate any output. +`Update-Help` doesn't generate any output. ## NOTES -- To update help for the Windows PowerShell Core modules (which contain the commands that are installed with Windows PowerShell) or any module in the $pshome\Modules directory, start Windows PowerShell with the "Run as administrator" option. - - Only members of the "Administrators" group on the computer can update help for the for the PowerShell Core modules (the commands that are installed with Windows PowerShell) and for modules in the `$pshome\Modules` directory. - If you do not have permission to update help files, you might be able to read the help topics online. - To open the online version of any cmdlet help topic, type `Get-Help \ -Online`. - -- Modules are the smallest unit of updatable help. You cannot update help for a particular cmdlet; only for all cmdlets in module. To find the module that contains a particular cmdlet, use the **ModuleName** property of the `Get-Command` cmdlet, for example, `(Get-Command \).ModuleName` -- Because help files are installed in the module directory, the `Update-Help` cmdlet can install updated help file only for modules that are installed on the computer. However, the `Save-Help` cmdlet can save help for modules that are not installed on the computer. -- If `Update-Help` cannot find updated help files for a module, or cannot find updated help in the specified language, it continues silently without displaying an error message. To see status and progress details, use the **Verbose** parameter. -- The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It does not work in earlier versions of Windows PowerShell. On computers that have both the Windows PowerShell 2.0 engine and Windows PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and update help files. The help files are accessible to both Windows PowerShell 2.0 and Windows PowerShell 3.0. -- The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. -- `Update-Help` supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. -- To update help for a module in a location that is not listed in the **PSModulePath** environment variable, import the module into the current session and then run an `Update-Help` command. Run the `Update-Help` command without parameters or use the **Module** parameter to specify the module name. The **Module** parameter of the `Update-Help` and `Save-Help` cmdlets does not accept the full path to a module file or module manifest file. -- Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules that you author, see "Supporting Updatable Help" in the MSDN Library at http://go.microsoft.com/fwlink/?LinkID=242129. -- The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment (Windows PE). +To update help for the PowerShell Core modules, that contain the commands that are installed with +PowerShell, or any module in the `$PSHOME\Modules` directory, start PowerShell with the option to +**Run as administrator**. + +Only members of the Administrators group on the computer can update help for the PowerShell Core +modules, the commands that are installed together with PowerShell, and for modules in the +`$PSHOME\Modules` folder. If you don't have permission to update help files, you can read the help +files online. For example, `Get-Help Update-Help -Online`. + +Modules are the smallest unit of updatable help. You can't update help for a particular cmdlet. To +find the module that contains a particular cmdlet, use the **ModuleName** property of the +`Get-Command` cmdlet, for example, `(Get-Command Update-Help).ModuleName`. + +Because help files are installed in the module directory, the `Update-Help` cmdlet can install +updated help file only for modules that are installed on the computer. However, the `Save-Help` +cmdlet can save help for modules that aren't installed on the computer. + +If `Update-Help` can't find updated help files for a module, or can't find updated help in the +specified language, it continues silently without displaying an error message. To see status and +progress details, use the **Verbose** parameter. + +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It doesn't work in earlier +versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows +PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and +update help files. The help files are available to both Windows PowerShell 2.0 and Windows +PowerShell 3.0. + +The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 +for HTTP and port 443 for HTTPS. + +`Update-Help` supports all modules and the PowerShell Core snap-ins. It doesn't support any other +snap-ins. + +To update help for a module in a location that isn't listed in the `$env:PSModulePath` environment +variable, import the module into the current session and then run an `Update-Help` command. Run +`Update-Help` without parameters or use the **Module** parameter to specify the module name. The +**Module** parameter of the `Update-Help` and `Save-Help` cmdlets doesn't accept the full path of a +module file or module manifest file. + +Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules +that you author, see [Supporting Updatable Help](/powershell/developer/module/supporting-updatable-help). + +The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment +(Windows PE). ## RELATED LINKS -[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Culture](../Microsoft.PowerShell.Utility/Get-Culture.md) [Get-Help](Get-Help.md) -[Get-Item](../Microsoft.PowerShell.Management/Get-Item.md) - [Get-Module](Get-Module.md) [Get-UICulture](../Microsoft.PowerShell.Utility/Get-UICulture.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/Update-Help.md b/reference/5.0/Microsoft.PowerShell.Core/Update-Help.md index b5f4ac1bdd46..aa63cb04a02b 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Update-Help.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Update-Help.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 5/16/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -17,42 +17,50 @@ Downloads and installs the newest help files on your computer. ### Path (Default) -```syntax -Update-Help [[-Module] ] [-FullyQualifiedModule ] [[-SourcePath] ] - [-Recurse] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] - [-WhatIf] [-Confirm] [] +``` +Update-Help [[-Module] ] [[-SourcePath] ] [[-UICulture] ] +[-FullyQualifiedModule ] [-Recurse] [-Credential ] +[-UseDefaultCredentials] [-Force] [-WhatIf] [-Confirm] [] ``` ### LiteralPath -```syntax -Update-Help [[-Module] ] [-FullyQualifiedModule ] [-LiteralPath ] - [-Recurse] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] - [-WhatIf] [-Confirm] [] +``` +Update-Help [[-Module] ] [[-UICulture] ] +[-FullyQualifiedModule ] [-LiteralPath ] [-Recurse] +[-Credential ] [-UseDefaultCredentials] [-Force] [-WhatIf] [-Confirm] +[] ``` ## DESCRIPTION -The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on your computer. -You can use the `Get-Help` cmdlet to view the new help files immediately. -You do not have to restart PowerShell to make the change effective. -This feature enables you to install help files for modules that do not include them and to update help files on your computer so that they never become obsolete. +The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on +your computer. You don't need to restart PowerShell to make the change effective. You can use the +`Get-Help` cmdlet to view the new help files immediately. + +`Update-Help` checks the version of the help files on your computer. If you don't have help files +for a module or if your help files are outdated, `Update-Help` downloads the newest help files. The +help files can be downloaded and installed from the internet or a file share. -`Update-Help` checks the version of the help files on your computer. -If you do not have help files for a module or do not have the newest help files for a module, `Update-Help` downloads the newest help files from the Internet or a file share and installs them on your computer in the correct module folder. +Without parameters, `Update-Help` updates the help files for modules in the session and for all +installed modules that support Updatable Help. Modules that are installed but not loaded in the +current session are included. PowerShell modules are stored in a location listed in the +`$env:PSModulePath` environment variable. +For more information, see [about_Updatable_Help](./About/about_Updatable_Help.md). -Without parameters, `Update-Help` updates the help for modules in the session and for all installed modules, in a location listed in the `$env:PSModulePath` environment variable, that support Updatable Help, even if the module is not in the current session. -You can also use the **Module** parameter to update help for a particular module and use the **UICulture** parameter to download help files in multiple languages and locales. +You can use the **Module** parameter to update help files for a particular module. Use the +**UICulture** parameter to download help files in multiple languages and locales. -You can use `Update-Help` even on computers that are not connected to the Internet. -Use the `Save-Help` cmdlet to download help files from the Internet and save them in a file system location, such as a shared folder or file system directory. -Then use the **SourcePath** parameter of `Update-Help` to get the updated help files from a file system location and install them on the computer. +You can use `Update-Help` on computers that aren't connected to the internet. Use the `Save-Help` +cmdlet to download help files from the internet and save them in a file system location, such as a +shared folder or file system directory. Then use the **SourcePath** parameter of `Update-Help` to +download the updated help files from a file system location and install them on the computer. -You can even automate the running of `Update-Help` by adding an `Update-Help` cmdlet to your PowerShell profile. -By default, `Update-Help` runs only one time per day on each computer. -To override the once-per-day limit, use the **Force** parameter. +You can automate help updates by adding the `Update-Help` cmdlet to your PowerShell profile. By +default, `Update-Help` runs only one time per day on each computer. To override the once-per-day +limit, use the **Force** parameter. -This cmdlet was introduced in Windows PowerShell 3.0. +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. > [!IMPORTANT] > `Update-Help` requires administrative privileges. @@ -63,6 +71,7 @@ This cmdlet was introduced in Windows PowerShell 3.0. > To download or update the help files for modules in the PowerShell > installation directory (`$PSHOME\Modules`), including the PowerShell > Core modules, start PowerShell by using the Run as administrator option. +> For example: `Start-Process powershell.exe -Verb RunAs`. > > You can also update help files by using the Update Windows PowerShell Help > menu item in the Help menu in Windows PowerShell Integrated Scripting @@ -75,108 +84,162 @@ This cmdlet was introduced in Windows PowerShell 3.0. ## EXAMPLES -### Example 1: Update help for all modules -``` -PS C:\> Update-Help +### Example 1: Update help files for all modules + +The `Update-Help` cmdlet updates help files for installed modules that support Updatable Help. The +user-interface (UI) culture language is set in the operating system. + +```powershell +Update-Help ``` -This command updates help for all installed modules that support Updatable Help in the language specified by the UI culture that is set for Windows. +### Example 2: Update help files for specified modules -To run this command, start Windows PowerShell by using the Run as administrator option (`Start-Process PowerShell -Verb RunAs`). +The `Update-Help` cmdlet updates help files only for module names that begin with +**Microsoft.PowerShell**. -### Example 2: Update help for specified modules -``` -PS C:\> Update-Help -Module ServerManager, Microsoft.PowerShell* +```powershell +Update-Help -Module Microsoft.PowerShell* ``` -This command updates help only for the ServerManager module and for modules that have names that begin with Microsoft.PowerShell. +### Example 3: Update help files for different languages + +The `Update-Help` cmdlet updates the Japanese (ja-JP) and English (en-US) help files for all +modules. -Because these modules are in the $pshome\Modules folder, to run this command, start Windows PowerShell by using the Run as administrator option. +If a module doesn't provide help files for a specified UI culture, an error message is displayed for +the module and UI culture. In this example, the error message indicates that the **ja-JP** help +files were not found for module **Microsoft.PowerShell.Utility**. -### Example 3: Update help in different languages +```powershell +Update-Help -UICulture ja-JP, en-US ``` -PS C:\> Update-Help -UICulture ja-JP, en-US -Update-Help : Failed to update Help for the module(s) 'ServerManager' with UI culture(s) {ja-JP} : -The specified culture is not supported: ja-JP. Specify a culture from the following list: {en-US}. + +```Output +Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Utility' with UI culture(s) {ja-JP} +No UI culture was found that matches the following pattern: ja-JP. ``` -This command updates the Japanese and English help files for all modules. +### Example 4: Update help files automatically -If a module currently does not provide help files for the specified UI culture, the error message lists the UI cultures that the module supports. -In this example, the error message indicates that the ServerManager module currently provides help files only in en-US. +This example creates a scheduled job that updates help for all modules every day at 3:00 AM. -### Example 4: Update help automatically +```powershell +$jobParams = @{ + Name = 'UpdateHelpJob' + Credential = 'Domain01\User01' + ScriptBlock = '{Update-Help}' + Trigger = (New-JobTrigger -Daily -At "3 AM") +} +Register-ScheduledJob @jobParams ``` -PS C:\> Register-ScheduledJob -Name UpdateHelpJob -Credential Domain01\User01 -ScriptBlock {Update-Help} -Trigger (New-JobTrigger -Daily -At "3 AM") + +```Output Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 UpdateHelpJob 1 Update-Help True ``` -This command creates a scheduled job that updates help for all modules on the computer every day at 3:00 in the morning. +The `Register-ScheduledJob` cmdlet creates a scheduled job that runs an `Update-Help` command. The +command uses the **Credential** parameter to run `Update-Help` by using the credentials of a member +of the Administrators group on the computer. The value of the **Trigger** parameter is a +`New-JobTrigger` command that creates a job trigger that starts the job every day at 3:00 AM. -The command uses the Register-ScheduledJob cmdlet to create a scheduled job that runs an **Update-Help** command. -The command uses the *Credential* parameter to run **Update-Help** by using the credentials of a member of the Administrators group on the computer. -The value of the *Trigger* parameter is a New-JobTrigger command that creates a job trigger that starts the job every day at 3:00 AM. +To run the `Register-ScheduledJob` command, start PowerShell by using the **Run as administrator** +option. PowerShell prompts you for the password of the user specified in the **Credential** +parameter. The credentials are stored with the scheduled job. You aren't prompted when the job runs. -To run the **Register-ScheduledJob** command, start Windows PowerShell by using the Run as administrator option. -When you run the command, Windows PowerShell prompts you for the password of the user specified in the value of the **Credential** parameter. -The credentials are stored with the scheduled job. -You are not prompted when the job runs. +You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` +cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. You can also view +and manage the scheduled job in Task Scheduler in the following path: -You can use the Get-ScheduledJob cmdlet to view the scheduled job, use the Set-ScheduledJob cmdlet to change it, and use the **Unregister-ScheduledJob** cmdlet to delete it. -You can also view and manage the scheduled job in Task Scheduler in the following path: Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs. +`Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs`. -### Example 5: Update help on multiple computers from a file share -``` -The first command uses **Save-Help** to download the newest help files for all modules that support Updatable Help. The command saves the downloaded help files in the \\Server01\Share\PSHelp file share.The command uses the *Credential* parameter of the **Save-Help** cmdlet to specify the credentials of a user who has permission to access the remote file share. By default, the command does not run with explicit credentials and attempts to access the file share might fail. -PS C:\> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +### Example 5: Update help files on multiple computers from a file share -The second command uses the Invoke-Command cmdlet to run **Update-Help** commands on many computers remotely.The **Invoke-Command** command gets the list of computers from the Servers.txt file. The **Update-Help** command installs the help files from the file share on all of the remote computers. The remote computer must be able to access the file share at the specified path.The **Update-Help** command uses *SourcePath* to get the updated help files from the file share, instead of the Internet, and the *Credential* parameter to run the command by using explicit credentials. By default, the command runs with network token privileges and attempts to access the file share from each remote computer (a "second hop") might fail. -PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Update-Help -SourcePath \\Server01\Share\Help -Credential Domain01\Admin01} +In this example, updated help files are downloaded from the internet and saved in a file share. User +credentials are needed that have permissions to access the file share and install updates. When a +file share is used, it's possible to update computers that are behind firewalls or aren't connected +to the internet. + +``` +PS> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock { + Update-Help -SourcePath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +} ``` -These commands download updated help files for system modules from the Internet and save them in file share. -Then the commands install the updated help files from the file share on multiple computers. -You can use a strategy such as the one shown here to update the help files on many computers, even those that are behind firewalls or are not connected to the Internet. +The `Save-Help` command downloads the newest help files for all modules that support Updatable Help. +The **DestinationPath** parameter saves the files in the `\\Server01\Share\PSHelp` file share. The +**Credential** parameter specifies a user who has permission to access the file share. -All of the commands in this example were run in a Windows PowerShell session that was started by using the Run as administrator option. +The `Invoke-Command` cmdlet runs remote `Update-Help` commands on multiple computers. The +**ComputerName** parameter gets a list of remote computers from the **Servers.txt** file. The +**ScriptBlock** parameter runs the `Update-Help` command and uses the **SourcePath** parameter to +specify the file share that contains the updated help files. The **Credential** parameter specifies +a user who can access the file share and run the remote `Update-Help` command. -### Example 6: Get a List of Updated Help Files -``` -PS C:\> Update-Help -Module BestPractices, ServerManager -Verbose -``` +### Example 6: Get a list of updated help files -This command updates help for two modules. -It uses the *Verbose* common parameter of **Update-Help** to get a list of the help files that the command updated. +The `Update-Help` cmdlet updates help for a specified module. The cmdlet uses the **Verbose** common +parameter to display the list of help files that were updated. You can use **Verbose** to view +output for all help files or help files for a specific module. -Without the *Verbose* parameter, **Update-Help** does not display the results of the command. -The *Verbose* parameter is especially useful when you want to verify that you have updated help files for a particular module or a particular locale. +Without the **Verbose** parameter, `Update-Help` doesn't display the results of the command. The +**Verbose** parameter output is useful to verify that the help files were updated or if the latest +version is installed. -### Example 7: Find modules that support Updatable Help +```powershell +Update-Help -Module Microsoft.PowerShell.Utility -Verbose ``` -PS C:\> Get-Module -ListAvailable | Where HelpInfoUri + +### Example 7: Find modules that support Updatable Help + +This example lists modules that support Updatable Help. The command uses the module's +**HelpInfoUri** property to identify modules that support Updatable Help. The **HelpInfoUri** +property contains an address that is redirected when the `Update-Help` cmdlet is run. + +```powershell +Get-Module -ListAvailable | Where-Object -Property HelpInfoUri ``` -This command gets modules that support Updatable Help. +```output + Directory: C:\program files\powershell\6\Modules -The command uses the **HelpInfoUri** property of modules to identify modules that support Updatable Help. -The value of the **HelpInfoUri** property contains the address of the Internet location where the module stores its Updatable Help information file. +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 6.1.0.0 CimCmdlets Core {Get-CimAssociatedInstance... } +Manifest 1.2.2.0 Microsoft.PowerShell.Archive Desk {Compress-Archive... } +Manifest 6.1.0.0 Microsoft.PowerShell.Diagnostics Core {Get-WinEvent, New-WinEvent} -This command uses the simplified syntax of the **Where-Object** cmdlet. -This syntax is introduced in Windows PowerShell 3.0. + Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules + +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 2.0.1.0 Appx Core,Desk {Add-AppxPackage, ... } +Script 1.0.0.0 AssignedAccess Core,Desk {Clear-AssignedAccess, ... } +Manifest 1.0.0.0 BitLocker Core,Desk {Unlock-BitLocker, ... } +``` ### Example 8: Inventory updated help files + +In this example, the script `Get-UpdateHelpVersion.ps1` creates an inventory of the Updatable Help +files for each module and their version numbers. + +The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of +modules. For modules that support Updatable Help, the script looks for and parses the help +information file (*helpinfo.xml) to find the latest version number. + +The script uses the **PSCustomObject** class and a hash table to create a custom output object. + ``` -PS C:\> -#Get-UpdateHelpVersion.ps1 -Param - ( - [parameter(Mandatory=$False)] - [String[]] - $Module - ) -$HelpInfoNamespace = @{helpInfo="http://schemas.microsoft.com/powershell/help/2010/05"} +# Get-UpdateHelpVersion.ps1 +Param( + [parameter(Mandatory=$False)] + [String[]] + $Module +) +$HelpInfoNamespace = @{helpInfo='http://schemas.microsoft.com/powershell/help/2010/05'} if ($Module) { $Modules = Get-Module $Module -ListAvailable | where {$_.HelpInfoUri} } else { $Modules = Get-Module -ListAvailable | where {$_.HelpInfoUri} } @@ -188,7 +251,8 @@ foreach ($mModule in $Modules) if (Test-Path $mdir\*helpinfo.xml) { $mName=$mModule.Name - $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" + $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | + Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" foreach ($mNode in $mNodes) { $mCulture=$mNode.Node.UICultureName @@ -198,6 +262,9 @@ foreach ($mModule in $Modules) } } } +``` + +```Output ModuleName Culture Version ---------- ------- ------- ActiveDirectory en-US 3.0.0.0 @@ -207,37 +274,18 @@ ADDSDeployment en-US ADFS en-US 3.0.0.0 ``` -The Get-UpdateHelpVersion.ps1 script creates an inventory of the Updatable Help files for each module and their version numbers. -Copy the script and paste it in a text file. - -The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of modules. -For modules that support Updatable Help, the script looks for and parses the help information file (HelpInfo XML) to find the latest version number. - -The script uses the **PSCustomObject** class and a hash table to create a custom output object. - ## PARAMETERS -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Credential -Specifies credentials of a user who has permission to access the file system location specified by *SourcePath*. -This parameter is valid only when the *SourcePath* or *LiteralPath* parameter is used in the command. -This parameter enables you to run **Update-Help** commands with the *SourcePath* parameter on remote computers. -By providing explicit credentials, you can run the command on a remote computer and access a file share on a third computer without encountering an access denied error or using CredSSP authentication to delegate credentials. +Specifies credentials of a user who has permission to access the file system location specified by +**SourcePath**. This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is +used in the command. + +The **Credential** parameter enables you to run `Update-Help` commands with the **SourcePath** +parameter on remote computers. By providing explicit credentials, you can run the command on a +remote computer and access a file share on a third computer without encountering an access denied +error or using CredSSP authentication to delegate credentials. ```yaml Type: PSCredential @@ -252,13 +300,22 @@ Accept wildcard characters: False ``` ### -Force -Indicates that this cmdlet does not follow the once-per-day limitation, skips version checking, and downloads files that exceed the 1 GB limit. -Without this parameter, **Update-Help** runs only once in each 24-hour period, downloads are limited to 1 GB of uncompressed content per module and help files are installed only when they are newer than the files on the computer. +Indicates that this cmdlet doesn't follow the once-per-day limitation, skips version checking, and +downloads files that exceed the 1 GB limit. -The once-per-day limit protects the servers that host the help files and makes it practical for you to add an **Update-Help** command to your Windows PowerShell profile without incurring the resource cost of repeated connections or downloads. +Without this parameter, `Update-Help` runs only once in each 24-hour period. Downloads are limited +to 1 GB of uncompressed content per module and help files are only installed when they're newer than +the existing files on the computer. -To update help for a module in multiple UI cultures without the *Force* parameter, include all UI cultures in the same command, such as: `Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` +The once-per-day limit protects the servers that host the help files and makes it practical for you +to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of +repeated connections or downloads. + +To update help for a module in multiple UI cultures without the **Force** parameter, include all UI +cultures in the same command, such as: + +`Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` ```yaml Type: SwitchParameter @@ -273,12 +330,24 @@ Accept wildcard characters: False ``` ### -FullyQualifiedModule + Specifies modules with names that are specified in the form of **ModuleSpecification** objects. -These are described in the Remarks section of [ModuleSpecification Constructor (Hashtable)](https://msdn.microsoft.com/library/jj136290) in the MSDN library. -For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format @{ModuleName = "modulename"; ModuleVersion = "version_number"} or @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. +These modules are described in the Remarks section of +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor?view=powershellsdk-1.1.0#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). + +For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in the +format: + +`@{ModuleName = "modulename"; ModuleVersion = "version_number"}` + +or + +`@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}.` + **ModuleName** and **ModuleVersion** are required, but **Guid** is optional. -You cannot specify the *FullyQualifiedModule* parameter in the same command as a *Module* parameter. +You can't specify the **FullyQualifiedModule** parameter in the same command as a **Module** +parameter. ```yaml Type: ModuleSpecification[] @@ -293,15 +362,18 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies the folder for updated help files instead of downloading them from the Internet. -Use this parameter or *SourcePath* if you have used the **Save-Help** cmdlet to download help files to a directory. -You can also pipe a directory object, such as one from the Get-Item or Get-ChildItem cmdlets, to **Update-Help**. +Specifies the folder for updated help files instead of downloading them from the internet. Use this +parameter or **SourcePath** if you've used the `Save-Help` cmdlet to download help files to a +directory. + +You can pipeline a directory object, such as from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -Unlike the value of *SourcePath*, the value of *LiteralPath* is used exactly as it is typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Unlike the value of **SourcePath**, the value of **LiteralPath** is used exactly as it's typed. No +characters are interpreted as wildcard characters. If the path includes escape characters, enclose +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. ```yaml Type: String[] @@ -316,21 +388,23 @@ Accept wildcard characters: False ``` ### -Module -Specifies modules for which this cmdlet updates help. -Enter one or more module names or name patterns in a comma-separated list, or specify a file that lists one module name on each line. -Wildcard characters are permitted. -You can also pipe modules from the Get-Module cmdlet, to the **Update-Help** cmdlet. -The modules that you specify must be installed on the computer, but they do not have to be imported into the current session. -You can specify any module in the session or any module that is installed in a location listed in the **PSModulePath** environment variable. +Updates help for the specified modules. Enter one or more module names or name patterns in a +comma-separated list, or specify a file that lists one module name on each line. Wildcard characters +are permitted. You can pipeline modules from the `Get-Module` cmdlet to the `Update-Help` cmdlet. -A value of * (all) attempts to update help for all modules that are installed on the computer. -This includes modules that do not support Updatable Help. -This value might generate errors when the command encounters modules that do not support Updatable Help. -Instead, run **Update-Help** without parameters. +The modules that you specify must be installed on the computer, but they don't have to be imported +into the current session. You can specify any module in the session or any module that is installed +in a location listed in the `$env:PSModulePath` environment variable. -The *Module* parameter of the **Update-Help** cmdlet does not accept the full path of a module file or module manifest file. -To update help for a module that is not in a PSModulePath location, import the module into the current session before you run the **Update-Help** command. +A value of `*` (all) attempts to update help for all modules that are installed on the computer. +Modules that don't support Updatable Help are included. This value might generate errors when the +command encounters modules that don't support Updatable Help. Instead, run `Update-Help` without +parameters. + +The **Module** parameter of the `Update-Help` cmdlet doesn't accept the full path of a module file +or module manifest file. To update help for a module that isn't in a `$env:PSModulePath` location, +import the module into the current session before you run the `Update-Help` command. ```yaml Type: String[] @@ -341,12 +415,13 @@ Required: False Position: 0 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Recurse -Searches recursively for help files in the specified directory. -This parameter is valid only when *SourcePath* is used in the command. + +Performs a recursive search for help files in the specified directory. This parameter is valid only +when the command uses the **SourcePath** parameter. ```yaml Type: SwitchParameter @@ -361,17 +436,19 @@ Accept wildcard characters: False ``` ### -SourcePath -Specifies a file system folder from which this cmdlet gets updated help files, instead of downloading them from the Internet. -Enter the path of a folder. -Do not specify a file name or file name extension. -You can also pipe a folder, such as one from the Get-Item or Get-ChildItem cmdlets, to **Update-Help**. -By default, **Update-Help** downloads updated help files from the Internet. -Use this parameter when you have used the **Save-Help** cmdlet to download updated help files to a directory. +Specifies a file system folder where `Update-Help` gets updated help files, instead of downloading +them from the internet. Enter the path of a folder. Don't specify a file name or file name +extension. You can pipeline a folder, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -Administrators can use the Set the default source path for Update-Help Group Policy setting under Computer Configuration to specify a default value for *SourcePath*. -This Group Policy setting prevents users from using **Update-Help** to download help files from the Internet. -For more information, see about_Group_Policy_Settings (http://go.microsoft.com/fwlink/?LinkId=251696). +By default, `Update-Help` downloads updated help files from the internet. Use **SourcePath** when +you've used the `Save-Help` cmdlet to download updated help files to a directory. + +To specify a default value for **SourcePath**, go to **Group Policy**, **Computer Configuration**, +and **Set the default source path for Update-Help**. This Group Policy setting prevents users from +using `Update-Help` to download help files from the internet. +For more information, see [about_Group_Policy_Settings](./About/about_Group_Policy_Settings.md). ```yaml Type: String[] @@ -386,15 +463,18 @@ Accept wildcard characters: False ``` ### -UICulture -Specifies UI culture values for which this cmdlet gets updated help files. -Enter one or more language codes, such as es-ES, a variable that contains culture objects, or a command that gets culture objects, such as a Get-Culture or Get-UICulture command. -Wildcard characters are not permitted and you cannot submit a partial language code, such as "de". -By default, **Update-Help** gets help files in the UI culture set for Windows or its fallback culture. -If you specify the *UICulture* parameter, **Update-Help** looks for help only for the specified UI culture, not in any fallback culture. +Specifies UI culture values that `Update-Help` uses to get updated help files. Enter one or more +language codes, such as **es-ES**, a variable that contains culture objects, or a command that gets +culture objects, such as a `Get-Culture` or `Get-UICulture` command. Wildcard characters aren't +permitted and you can't submit a partial language code, such as **de**. + +By default, `Update-Help` gets help files in the UI culture set for the operating system. If you +specify the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture. -Commands that use the *UICulture* parameter succeed only when the module provides help files for the specified UI culture. -If the command fails because the specified UI culture is not supported, the error message includes a list of UI cultures that the module supports. +Commands that use the **UICulture** parameter succeed only when the module provides help files for +the specified UI culture. If the command fails because the specified UI culture isn't supported, an +error message is displayed. ```yaml Type: CultureInfo[] @@ -409,10 +489,12 @@ Accept wildcard characters: False ``` ### -UseDefaultCredentials -Indicates that this cmdlet runs the command, including the Internet download, by using the credentials of the current user. -By default, the command runs without explicit credentials. -This parameter is effective only when the Web download uses NTLM, negotiate, or Kerberos-based authentication. +Indicates that `Update-Help` runs the command, including the internet download, by using the +credentials of the current user. By default, the command runs without explicit credentials. + +This parameter is effective only when the web download uses NT LAN Manager (NTLM), negotiate, or +Kerberos-based authentication. ```yaml Type: SwitchParameter @@ -426,9 +508,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -443,44 +541,84 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.IO.DirectoryInfo -You can pipe a directory path to this cmdlet. + +You can pipe a directory path to `Update-Help`. ### System.Management.Automation.PSModuleInfo -You can pipe a module object from the Get-Module cmdlet to this cmdlet. + +You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. ## OUTPUTS ### None -This cmdlet does not generate any output. + +`Update-Help` doesn't generate any output. ## NOTES -* To update help for the Windows PowerShell Core modules, which contain the commands that are installed with Windows PowerShell, or any module in the $pshome\Modules folder, start Windows PowerShell by using the Run as administrator option. - - Only members of the Administrators group on the computer can update help for the for the Windows PowerShell Core modules, the commands that are installed together with Windows PowerShell, and for modules in the $pshome\Modules folder. -If you do not have permission to update help files, you might be able to read the help topics online. -To open the online version of any cmdlet help topic, type `Get-Help \ -Online`. - -* Modules are the smallest unit of updatable help. You cannot update help for a particular cmdlet. To find the module that contains a particular cmdlet, use the **ModuleName** property of the Get-Command cmdlet, for example, `(Get-Command \).ModuleName` -* Because help files are installed in the module directory, the **Update-Help** cmdlet can install updated help file only for modules that are installed on the computer. However, the **Save-Help** cmdlet can save help for modules that are not installed on the computer. -* If **Update-Help** cannot find updated help files for a module, or cannot find updated help in the specified language, it continues silently without displaying an error message. To see status and progress details, use the *Verbose* parameter. -* The **Update-Help** cmdlet was introduced in Windows PowerShell 3.0. It does not work in earlier versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows PowerShell 3.0, use the **Update-Help** cmdlet in a Windows PowerShell 3.0 session to download and update help files. The help files are available to both Windows PowerShell 2.0 and Windows PowerShell 3.0. -* The **Update-Help** and **Save-Help** cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. -* **Update-Help** supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. -* To update help for a module in a location that is not listed in the **PSModulePath** environment variable, import the module into the current session and then run an **Update-Help** command. Run **Update-Help** without parameters or use the *Module* parameter to specify the module name. The *Module* parameter of the **Update-Help** and **Save-Help** cmdlets does not accept the full path of a module file or module manifest file. -* Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules that you author, see Supporting Updatable Help (http://go.microsoft.com/fwlink/?LinkID=242129) in the MSDN Library. -* The **Update-Help** and **Save-Help** cmdlets are not supported on Windows Preinstallation Environment (Windows PE). + +To update help for the PowerShell Core modules, that contain the commands that are installed with +PowerShell, or any module in the `$PSHOME\Modules` directory, start PowerShell with the option to +**Run as administrator**. + +Only members of the Administrators group on the computer can update help for the PowerShell Core +modules, the commands that are installed together with PowerShell, and for modules in the +`$PSHOME\Modules` folder. If you don't have permission to update help files, you can read the help +files online. For example, `Get-Help Update-Help -Online`. + +Modules are the smallest unit of updatable help. You can't update help for a particular cmdlet. To +find the module that contains a particular cmdlet, use the **ModuleName** property of the +`Get-Command` cmdlet, for example, `(Get-Command Update-Help).ModuleName`. + +Because help files are installed in the module directory, the `Update-Help` cmdlet can install +updated help file only for modules that are installed on the computer. However, the `Save-Help` +cmdlet can save help for modules that aren't installed on the computer. + +If `Update-Help` can't find updated help files for a module, or can't find updated help in the +specified language, it continues silently without displaying an error message. To see status and +progress details, use the **Verbose** parameter. + +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It doesn't work in earlier +versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows +PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and +update help files. The help files are available to both Windows PowerShell 2.0 and Windows +PowerShell 3.0. + +The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 +for HTTP and port 443 for HTTPS. + +`Update-Help` supports all modules and the PowerShell Core snap-ins. It doesn't support any other +snap-ins. + +To update help for a module in a location that isn't listed in the `$env:PSModulePath` environment +variable, import the module into the current session and then run an `Update-Help` command. Run +`Update-Help` without parameters or use the **Module** parameter to specify the module name. The +**Module** parameter of the `Update-Help` and `Save-Help` cmdlets doesn't accept the full path of a +module file or module manifest file. + +Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules +that you author, see [Supporting Updatable Help](/powershell/developer/module/supporting-updatable-help). + +The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment +(Windows PE). ## RELATED LINKS -[Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007)](http://go.microsoft.com/fwlink/?LinkID=270007) +[Get-Culture](../Microsoft.PowerShell.Utility/Get-Culture.md) [Get-Help](Get-Help.md) [Get-Module](Get-Module.md) +[Get-UICulture](../Microsoft.PowerShell.Utility/Get-UICulture.md) + +[Start-Job](Start-Job.md) + [Save-Help](Save-Help.md) \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/Update-Help.md b/reference/5.1/Microsoft.PowerShell.Core/Update-Help.md index 856f7f8f3c5d..186d80391afb 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Update-Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Update-Help.md @@ -3,7 +3,7 @@ external help file: System.Management.Automation.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Core -ms.date: 06/09/2017 +ms.date: 5/16/2019 online version: http://go.microsoft.com/fwlink/?LinkID=821524 schema: 2.0.0 title: Update-Help @@ -17,41 +17,50 @@ Downloads and installs the newest help files on your computer. ## SYNTAX ### Path (Default) + ``` -Update-Help [[-Module] ] [-FullyQualifiedModule ] [[-SourcePath] ] - [-Recurse] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] - [-WhatIf] [-Confirm] [] +Update-Help [[-Module] ] [-FullyQualifiedModule ] +[[-SourcePath] ] [-Recurse] [[-UICulture] ] [-Credential ] +[-UseDefaultCredentials] [-Force] [-WhatIf] [-Confirm] [] ``` ### LiteralPath + ``` -Update-Help [[-Module] ] [-FullyQualifiedModule ] [-LiteralPath ] - [-Recurse] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] - [-WhatIf] [-Confirm] [] +Update-Help [[-Module] ] [-FullyQualifiedModule ] +[-LiteralPath ] [-Recurse] [[-UICulture] ] [-Credential ] +[-UseDefaultCredentials] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on your computer. -You can use the `Get-Help` cmdlet to view the new help files immediately. -You do not have to restart PowerShell to make the change effective. -This feature enables you to install help files for modules that do not include them and to update help files on your computer so that they never become obsolete. +The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on +your computer. You don't need to restart PowerShell to make the change effective. You can use the +`Get-Help` cmdlet to view the new help files immediately. -`Update-Help` checks the version of the help files on your computer. -If you do not have help files for a module or do not have the newest help files for a module, `Update-Help` downloads the newest help files from the Internet or a file share and installs them on your computer in the correct module folder. +`Update-Help` checks the version of the help files on your computer. If you don't have help files +for a module or if your help files are outdated, `Update-Help` downloads the newest help files. The +help files can be downloaded and installed from the internet or a file share. -Without parameters, `Update-Help` updates the help for modules in the session and for all installed modules, in a location listed in the `$env:PSModulePath` environment variable, that support Updatable Help, even if the module is not in the current session. -You can also use the **Module** parameter to update help for a particular module and use the **UICulture** parameter to download help files in multiple languages and locales. +Without parameters, `Update-Help` updates the help files for modules in the session and for all +installed modules that support Updatable Help. Modules that are installed but not loaded in the +current session are included. PowerShell modules are stored in a location listed in the +`$env:PSModulePath` environment variable. +For more information, see [about_Updatable_Help](./About/about_Updatable_Help.md). -You can use `Update-Help` even on computers that are not connected to the Internet. -Use the `Save-Help` cmdlet to download help files from the Internet and save them in a file system location, such as a shared folder or file system directory. -Then use the **SourcePath** parameter of `Update-Help` to get the updated help files from a file system location and install them on the computer. +You can use the **Module** parameter to update help files for a particular module. Use the +**UICulture** parameter to download help files in multiple languages and locales. -You can even automate the running of `Update-Help` by adding an `Update-Help` cmdlet to your PowerShell profile. -By default, `Update-Help` runs only one time per day on each computer. -To override the once-per-day limit, use the **Force** parameter. +You can use `Update-Help` on computers that aren't connected to the internet. Use the `Save-Help` +cmdlet to download help files from the internet and save them in a file system location, such as a +shared folder or file system directory. Then use the **SourcePath** parameter of `Update-Help` to +download the updated help files from a file system location and install them on the computer. -This cmdlet was introduced in Windows PowerShell 3.0. +You can automate help updates by adding the `Update-Help` cmdlet to your PowerShell profile. By +default, `Update-Help` runs only one time per day on each computer. To override the once-per-day +limit, use the **Force** parameter. + +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. > [!IMPORTANT] > `Update-Help` requires administrative privileges. @@ -62,6 +71,7 @@ This cmdlet was introduced in Windows PowerShell 3.0. > To download or update the help files for modules in the PowerShell > installation directory (`$PSHOME\Modules`), including the PowerShell > Core modules, start PowerShell by using the Run as administrator option. +> For example: `Start-Process powershell.exe -Verb RunAs`. > > You can also update help files by using the Update Windows PowerShell Help > menu item in the Help menu in Windows PowerShell Integrated Scripting @@ -74,108 +84,162 @@ This cmdlet was introduced in Windows PowerShell 3.0. ## EXAMPLES -### Example 1: Update help for all modules -``` -PS C:\> Update-Help +### Example 1: Update help files for all modules + +The `Update-Help` cmdlet updates help files for installed modules that support Updatable Help. The +user-interface (UI) culture language is set in the operating system. + +```powershell +Update-Help ``` -This command updates help for all installed modules that support Updatable Help in the language specified by the UI culture that is set for Windows. +### Example 2: Update help files for specified modules -To run this command, start Windows PowerShell by using the Run as administrator option (`Start-Process PowerShell -Verb RunAs`). +The `Update-Help` cmdlet updates help files only for module names that begin with +**Microsoft.PowerShell**. -### Example 2: Update help for specified modules -``` -PS C:\> Update-Help -Module ServerManager, Microsoft.PowerShell* +```powershell +Update-Help -Module Microsoft.PowerShell* ``` -This command updates help only for the ServerManager module and for modules that have names that begin with Microsoft.PowerShell. +### Example 3: Update help files for different languages + +The `Update-Help` cmdlet updates the Japanese (ja-JP) and English (en-US) help files for all +modules. -Because these modules are in the $pshome\Modules folder, to run this command, start Windows PowerShell by using the Run as administrator option. +If a module doesn't provide help files for a specified UI culture, an error message is displayed for +the module and UI culture. In this example, the error message indicates that the **ja-JP** help +files were not found for module **Microsoft.PowerShell.Utility**. -### Example 3: Update help in different languages +```powershell +Update-Help -UICulture ja-JP, en-US ``` -PS C:\> Update-Help -UICulture ja-JP, en-US -Update-Help : Failed to update Help for the module(s) 'ServerManager' with UI culture(s) {ja-JP} : -The specified culture is not supported: ja-JP. Specify a culture from the following list: {en-US}. + +```Output +Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Utility' with UI culture(s) {ja-JP} +No UI culture was found that matches the following pattern: ja-JP. ``` -This command updates the Japanese and English help files for all modules. +### Example 4: Update help files automatically -If a module currently does not provide help files for the specified UI culture, the error message lists the UI cultures that the module supports. -In this example, the error message indicates that the ServerManager module currently provides help files only in en-US. +This example creates a scheduled job that updates help for all modules every day at 3:00 AM. -### Example 4: Update help automatically +```powershell +$jobParams = @{ + Name = 'UpdateHelpJob' + Credential = 'Domain01\User01' + ScriptBlock = '{Update-Help}' + Trigger = (New-JobTrigger -Daily -At "3 AM") +} +Register-ScheduledJob @jobParams ``` -PS C:\> Register-ScheduledJob -Name UpdateHelpJob -Credential Domain01\User01 -ScriptBlock {Update-Help} -Trigger (New-JobTrigger -Daily -At "3 AM") + +```Output Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 UpdateHelpJob 1 Update-Help True ``` -This command creates a scheduled job that updates help for all modules on the computer every day at 3:00 in the morning. +The `Register-ScheduledJob` cmdlet creates a scheduled job that runs an `Update-Help` command. The +command uses the **Credential** parameter to run `Update-Help` by using the credentials of a member +of the Administrators group on the computer. The value of the **Trigger** parameter is a +`New-JobTrigger` command that creates a job trigger that starts the job every day at 3:00 AM. -The command uses the Register-ScheduledJob cmdlet to create a scheduled job that runs an **Update-Help** command. -The command uses the *Credential* parameter to run **Update-Help** by using the credentials of a member of the Administrators group on the computer. -The value of the *Trigger* parameter is a New-JobTrigger command that creates a job trigger that starts the job every day at 3:00 AM. +To run the `Register-ScheduledJob` command, start PowerShell by using the **Run as administrator** +option. PowerShell prompts you for the password of the user specified in the **Credential** +parameter. The credentials are stored with the scheduled job. You aren't prompted when the job runs. -To run the **Register-ScheduledJob** command, start Windows PowerShell by using the Run as administrator option. -When you run the command, Windows PowerShell prompts you for the password of the user specified in the value of the **Credential** parameter. -The credentials are stored with the scheduled job. -You are not prompted when the job runs. +You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` +cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. You can also view +and manage the scheduled job in Task Scheduler in the following path: -You can use the Get-ScheduledJob cmdlet to view the scheduled job, use the Set-ScheduledJob cmdlet to change it, and use the **Unregister-ScheduledJob** cmdlet to delete it. -You can also view and manage the scheduled job in Task Scheduler in the following path: Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs. +`Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs`. -### Example 5: Update help on multiple computers from a file share -``` -The first command uses **Save-Help** to download the newest help files for all modules that support Updatable Help. The command saves the downloaded help files in the \\Server01\Share\PSHelp file share.The command uses the *Credential* parameter of the **Save-Help** cmdlet to specify the credentials of a user who has permission to access the remote file share. By default, the command does not run with explicit credentials and attempts to access the file share might fail. -PS C:\> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +### Example 5: Update help files on multiple computers from a file share -The second command uses the Invoke-Command cmdlet to run **Update-Help** commands on many computers remotely.The **Invoke-Command** command gets the list of computers from the Servers.txt file. The **Update-Help** command installs the help files from the file share on all of the remote computers. The remote computer must be able to access the file share at the specified path.The **Update-Help** command uses *SourcePath* to get the updated help files from the file share, instead of the Internet, and the *Credential* parameter to run the command by using explicit credentials. By default, the command runs with network token privileges and attempts to access the file share from each remote computer (a "second hop") might fail. -PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Update-Help -SourcePath \\Server01\Share\Help -Credential Domain01\Admin01} +In this example, updated help files are downloaded from the internet and saved in a file share. User +credentials are needed that have permissions to access the file share and install updates. When a +file share is used, it's possible to update computers that are behind firewalls or aren't connected +to the internet. + +``` +PS> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock { + Update-Help -SourcePath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +} ``` -These commands download updated help files for system modules from the Internet and save them in file share. -Then the commands install the updated help files from the file share on multiple computers. -You can use a strategy such as the one shown here to update the help files on many computers, even those that are behind firewalls or are not connected to the Internet. +The `Save-Help` command downloads the newest help files for all modules that support Updatable Help. +The **DestinationPath** parameter saves the files in the `\\Server01\Share\PSHelp` file share. The +**Credential** parameter specifies a user who has permission to access the file share. -All of the commands in this example were run in a Windows PowerShell session that was started by using the Run as administrator option. +The `Invoke-Command` cmdlet runs remote `Update-Help` commands on multiple computers. The +**ComputerName** parameter gets a list of remote computers from the **Servers.txt** file. The +**ScriptBlock** parameter runs the `Update-Help` command and uses the **SourcePath** parameter to +specify the file share that contains the updated help files. The **Credential** parameter specifies +a user who can access the file share and run the remote `Update-Help` command. -### Example 6: Get a List of Updated Help Files -``` -PS C:\> Update-Help -Module BestPractices, ServerManager -Verbose -``` +### Example 6: Get a list of updated help files -This command updates help for two modules. -It uses the *Verbose* common parameter of **Update-Help** to get a list of the help files that the command updated. +The `Update-Help` cmdlet updates help for a specified module. The cmdlet uses the **Verbose** common +parameter to display the list of help files that were updated. You can use **Verbose** to view +output for all help files or help files for a specific module. -Without the *Verbose* parameter, **Update-Help** does not display the results of the command. -The *Verbose* parameter is especially useful when you want to verify that you have updated help files for a particular module or a particular locale. +Without the **Verbose** parameter, `Update-Help` doesn't display the results of the command. The +**Verbose** parameter output is useful to verify that the help files were updated or if the latest +version is installed. -### Example 7: Find modules that support Updatable Help +```powershell +Update-Help -Module Microsoft.PowerShell.Utility -Verbose ``` -PS C:\> Get-Module -ListAvailable | Where HelpInfoUri + +### Example 7: Find modules that support Updatable Help + +This example lists modules that support Updatable Help. The command uses the module's +**HelpInfoUri** property to identify modules that support Updatable Help. The **HelpInfoUri** +property contains an address that is redirected when the `Update-Help` cmdlet is run. + +```powershell +Get-Module -ListAvailable | Where-Object -Property HelpInfoUri ``` -This command gets modules that support Updatable Help. +```output + Directory: C:\program files\powershell\6\Modules -The command uses the **HelpInfoUri** property of modules to identify modules that support Updatable Help. -The value of the **HelpInfoUri** property contains the address of the Internet location where the module stores its Updatable Help information file. +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 6.1.0.0 CimCmdlets Core {Get-CimAssociatedInstance... } +Manifest 1.2.2.0 Microsoft.PowerShell.Archive Desk {Compress-Archive... } +Manifest 6.1.0.0 Microsoft.PowerShell.Diagnostics Core {Get-WinEvent, New-WinEvent} -This command uses the simplified syntax of the **Where-Object** cmdlet. -This syntax is introduced in Windows PowerShell 3.0. + Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules + +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 2.0.1.0 Appx Core,Desk {Add-AppxPackage, ... } +Script 1.0.0.0 AssignedAccess Core,Desk {Clear-AssignedAccess, ... } +Manifest 1.0.0.0 BitLocker Core,Desk {Unlock-BitLocker, ... } +``` ### Example 8: Inventory updated help files + +In this example, the script `Get-UpdateHelpVersion.ps1` creates an inventory of the Updatable Help +files for each module and their version numbers. + +The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of +modules. For modules that support Updatable Help, the script looks for and parses the help +information file (*helpinfo.xml) to find the latest version number. + +The script uses the **PSCustomObject** class and a hash table to create a custom output object. + ``` -PS C:\> -#Get-UpdateHelpVersion.ps1 -Param - ( - [parameter(Mandatory=$False)] - [String[]] - $Module - ) -$HelpInfoNamespace = @{helpInfo="http://schemas.microsoft.com/powershell/help/2010/05"} +# Get-UpdateHelpVersion.ps1 +Param( + [parameter(Mandatory=$False)] + [String[]] + $Module +) +$HelpInfoNamespace = @{helpInfo='http://schemas.microsoft.com/powershell/help/2010/05'} if ($Module) { $Modules = Get-Module $Module -ListAvailable | where {$_.HelpInfoUri} } else { $Modules = Get-Module -ListAvailable | where {$_.HelpInfoUri} } @@ -187,7 +251,8 @@ foreach ($mModule in $Modules) if (Test-Path $mdir\*helpinfo.xml) { $mName=$mModule.Name - $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" + $mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | + Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture" foreach ($mNode in $mNodes) { $mCulture=$mNode.Node.UICultureName @@ -197,6 +262,9 @@ foreach ($mModule in $Modules) } } } +``` + +```Output ModuleName Culture Version ---------- ------- ------- ActiveDirectory en-US 3.0.0.0 @@ -206,22 +274,18 @@ ADDSDeployment en-US ADFS en-US 3.0.0.0 ``` -The Get-UpdateHelpVersion.ps1 script creates an inventory of the Updatable Help files for each module and their version numbers. -Copy the script and paste it in a text file. - -The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of modules. -For modules that support Updatable Help, the script looks for and parses the help information file (HelpInfo XML) to find the latest version number. - -The script uses the **PSCustomObject** class and a hash table to create a custom output object. - ## PARAMETERS ### -Credential -Specifies credentials of a user who has permission to access the file system location specified by *SourcePath*. -This parameter is valid only when the *SourcePath* or *LiteralPath* parameter is used in the command. -This parameter enables you to run **Update-Help** commands with the *SourcePath* parameter on remote computers. -By providing explicit credentials, you can run the command on a remote computer and access a file share on a third computer without encountering an access denied error or using CredSSP authentication to delegate credentials. +Specifies credentials of a user who has permission to access the file system location specified by +**SourcePath**. This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is +used in the command. + +The **Credential** parameter enables you to run `Update-Help` commands with the **SourcePath** +parameter on remote computers. By providing explicit credentials, you can run the command on a +remote computer and access a file share on a third computer without encountering an access denied +error or using CredSSP authentication to delegate credentials. ```yaml Type: PSCredential @@ -236,13 +300,22 @@ Accept wildcard characters: False ``` ### -Force -Indicates that this cmdlet does not follow the once-per-day limitation, skips version checking, and downloads files that exceed the 1 GB limit. -Without this parameter, **Update-Help** runs only once in each 24-hour period, downloads are limited to 1 GB of uncompressed content per module and help files are installed only when they are newer than the files on the computer. +Indicates that this cmdlet doesn't follow the once-per-day limitation, skips version checking, and +downloads files that exceed the 1 GB limit. + +Without this parameter, `Update-Help` runs only once in each 24-hour period. Downloads are limited +to 1 GB of uncompressed content per module and help files are only installed when they're newer than +the existing files on the computer. + +The once-per-day limit protects the servers that host the help files and makes it practical for you +to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of +repeated connections or downloads. -The once-per-day limit protects the servers that host the help files and makes it practical for you to add an **Update-Help** command to your Windows PowerShell profile without incurring the resource cost of repeated connections or downloads. +To update help for a module in multiple UI cultures without the **Force** parameter, include all UI +cultures in the same command, such as: -To update help for a module in multiple UI cultures without the *Force* parameter, include all UI cultures in the same command, such as: `Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` +`Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` ```yaml Type: SwitchParameter @@ -257,12 +330,24 @@ Accept wildcard characters: False ``` ### -FullyQualifiedModule + Specifies modules with names that are specified in the form of **ModuleSpecification** objects. -These are described in the Remarks section of [ModuleSpecification Constructor (Hashtable)](https://msdn.microsoft.com/library/jj136290) in the MSDN library. -For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format @{ModuleName = "modulename"; ModuleVersion = "version_number"} or @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. +These modules are described in the Remarks section of +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor?view=powershellsdk-1.1.0#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). + +For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in the +format: + +`@{ModuleName = "modulename"; ModuleVersion = "version_number"}` + +or + +`@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}.` + **ModuleName** and **ModuleVersion** are required, but **Guid** is optional. -You cannot specify the *FullyQualifiedModule* parameter in the same command as a *Module* parameter. +You can't specify the **FullyQualifiedModule** parameter in the same command as a **Module** +parameter. ```yaml Type: ModuleSpecification[] @@ -277,15 +362,18 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies the folder for updated help files instead of downloading them from the Internet. -Use this parameter or *SourcePath* if you have used the **Save-Help** cmdlet to download help files to a directory. -You can also pipe a directory object, such as one from the Get-Item or Get-ChildItem cmdlets, to **Update-Help**. +Specifies the folder for updated help files instead of downloading them from the internet. Use this +parameter or **SourcePath** if you've used the `Save-Help` cmdlet to download help files to a +directory. + +You can pipeline a directory object, such as from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -Unlike the value of *SourcePath*, the value of *LiteralPath* is used exactly as it is typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Unlike the value of **SourcePath**, the value of **LiteralPath** is used exactly as it's typed. No +characters are interpreted as wildcard characters. If the path includes escape characters, enclose +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. ```yaml Type: String[] @@ -300,21 +388,23 @@ Accept wildcard characters: False ``` ### -Module -Specifies modules for which this cmdlet updates help. -Enter one or more module names or name patterns in a comma-separated list, or specify a file that lists one module name on each line. -Wildcard characters are permitted. -You can also pipe modules from the Get-Module cmdlet, to the **Update-Help** cmdlet. -The modules that you specify must be installed on the computer, but they do not have to be imported into the current session. -You can specify any module in the session or any module that is installed in a location listed in the **PSModulePath** environment variable. +Updates help for the specified modules. Enter one or more module names or name patterns in a +comma-separated list, or specify a file that lists one module name on each line. Wildcard characters +are permitted. You can pipeline modules from the `Get-Module` cmdlet to the `Update-Help` cmdlet. -A value of * (all) attempts to update help for all modules that are installed on the computer. -This includes modules that do not support Updatable Help. -This value might generate errors when the command encounters modules that do not support Updatable Help. -Instead, run **Update-Help** without parameters. +The modules that you specify must be installed on the computer, but they don't have to be imported +into the current session. You can specify any module in the session or any module that is installed +in a location listed in the `$env:PSModulePath` environment variable. -The *Module* parameter of the **Update-Help** cmdlet does not accept the full path of a module file or module manifest file. -To update help for a module that is not in a PSModulePath location, import the module into the current session before you run the **Update-Help** command. +A value of `*` (all) attempts to update help for all modules that are installed on the computer. +Modules that don't support Updatable Help are included. This value might generate errors when the +command encounters modules that don't support Updatable Help. Instead, run `Update-Help` without +parameters. + +The **Module** parameter of the `Update-Help` cmdlet doesn't accept the full path of a module file +or module manifest file. To update help for a module that isn't in a `$env:PSModulePath` location, +import the module into the current session before you run the `Update-Help` command. ```yaml Type: String[] @@ -325,12 +415,13 @@ Required: False Position: 0 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Recurse -Searches recursively for help files in the specified directory. -This parameter is valid only when *SourcePath* is used in the command. + +Performs a recursive search for help files in the specified directory. This parameter is valid only +when the command uses the **SourcePath** parameter. ```yaml Type: SwitchParameter @@ -345,17 +436,19 @@ Accept wildcard characters: False ``` ### -SourcePath -Specifies a file system folder from which this cmdlet gets updated help files, instead of downloading them from the Internet. -Enter the path of a folder. -Do not specify a file name or file name extension. -You can also pipe a folder, such as one from the Get-Item or Get-ChildItem cmdlets, to **Update-Help**. -By default, **Update-Help** downloads updated help files from the Internet. -Use this parameter when you have used the **Save-Help** cmdlet to download updated help files to a directory. +Specifies a file system folder where `Update-Help` gets updated help files, instead of downloading +them from the internet. Enter the path of a folder. Don't specify a file name or file name +extension. You can pipeline a folder, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. + +By default, `Update-Help` downloads updated help files from the internet. Use **SourcePath** when +you've used the `Save-Help` cmdlet to download updated help files to a directory. -Administrators can use the Set the default source path for Update-Help Group Policy setting under Computer Configuration to specify a default value for *SourcePath*. -This Group Policy setting prevents users from using **Update-Help** to download help files from the Internet. -For more information, see about_Group_Policy_Settings (http://go.microsoft.com/fwlink/?LinkId=251696). +To specify a default value for **SourcePath**, go to **Group Policy**, **Computer Configuration**, +and **Set the default source path for Update-Help**. This Group Policy setting prevents users from +using `Update-Help` to download help files from the internet. +For more information, see [about_Group_Policy_Settings](./About/about_Group_Policy_Settings.md). ```yaml Type: String[] @@ -370,15 +463,18 @@ Accept wildcard characters: False ``` ### -UICulture -Specifies UI culture values for which this cmdlet gets updated help files. -Enter one or more language codes, such as es-ES, a variable that contains culture objects, or a command that gets culture objects, such as a Get-Culture or Get-UICulture command. -Wildcard characters are not permitted and you cannot submit a partial language code, such as "de". -By default, **Update-Help** gets help files in the UI culture set for Windows or its fallback culture. -If you specify the *UICulture* parameter, **Update-Help** looks for help only for the specified UI culture, not in any fallback culture. +Specifies UI culture values that `Update-Help` uses to get updated help files. Enter one or more +language codes, such as **es-ES**, a variable that contains culture objects, or a command that gets +culture objects, such as a `Get-Culture` or `Get-UICulture` command. Wildcard characters aren't +permitted and you can't submit a partial language code, such as **de**. -Commands that use the *UICulture* parameter succeed only when the module provides help files for the specified UI culture. -If the command fails because the specified UI culture is not supported, the error message includes a list of UI cultures that the module supports. +By default, `Update-Help` gets help files in the UI culture set for the operating system. If you +specify the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture. + +Commands that use the **UICulture** parameter succeed only when the module provides help files for +the specified UI culture. If the command fails because the specified UI culture isn't supported, an +error message is displayed. ```yaml Type: CultureInfo[] @@ -393,10 +489,12 @@ Accept wildcard characters: False ``` ### -UseDefaultCredentials -Indicates that this cmdlet runs the command, including the Internet download, by using the credentials of the current user. -By default, the command runs without explicit credentials. -This parameter is effective only when the Web download uses NTLM, negotiate, or Kerberos-based authentication. +Indicates that `Update-Help` runs the command, including the internet download, by using the +credentials of the current user. By default, the command runs without explicit credentials. + +This parameter is effective only when the web download uses NT LAN Manager (NTLM), negotiate, or +Kerberos-based authentication. ```yaml Type: SwitchParameter @@ -411,6 +509,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -426,8 +525,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -442,44 +541,84 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.IO.DirectoryInfo -You can pipe a directory path to this cmdlet. + +You can pipe a directory path to `Update-Help`. ### System.Management.Automation.PSModuleInfo -You can pipe a module object from the Get-Module cmdlet to this cmdlet. + +You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. ## OUTPUTS ### None -This cmdlet does not generate any output. + +`Update-Help` doesn't generate any output. ## NOTES -* To update help for the Windows PowerShell Core modules, which contain the commands that are installed with Windows PowerShell, or any module in the $pshome\Modules folder, start Windows PowerShell by using the Run as administrator option. - - Only members of the Administrators group on the computer can update help for the for the Windows PowerShell Core modules, the commands that are installed together with Windows PowerShell, and for modules in the $pshome\Modules folder. -If you do not have permission to update help files, you might be able to read the help topics online. -To open the online version of any cmdlet help topic, type `Get-Help \ -Online`. - -* Modules are the smallest unit of updatable help. You cannot update help for a particular cmdlet. To find the module that contains a particular cmdlet, use the **ModuleName** property of the Get-Command cmdlet, for example, `(Get-Command \).ModuleName` -* Because help files are installed in the module directory, the **Update-Help** cmdlet can install updated help file only for modules that are installed on the computer. However, the **Save-Help** cmdlet can save help for modules that are not installed on the computer. -* If **Update-Help** cannot find updated help files for a module, or cannot find updated help in the specified language, it continues silently without displaying an error message. To see status and progress details, use the *Verbose* parameter. -* The **Update-Help** cmdlet was introduced in Windows PowerShell 3.0. It does not work in earlier versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows PowerShell 3.0, use the **Update-Help** cmdlet in a Windows PowerShell 3.0 session to download and update help files. The help files are available to both Windows PowerShell 2.0 and Windows PowerShell 3.0. -* The **Update-Help** and **Save-Help** cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. -* **Update-Help** supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. -* To update help for a module in a location that is not listed in the **PSModulePath** environment variable, import the module into the current session and then run an **Update-Help** command. Run **Update-Help** without parameters or use the *Module* parameter to specify the module name. The *Module* parameter of the **Update-Help** and **Save-Help** cmdlets does not accept the full path of a module file or module manifest file. -* Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules that you author, see Supporting Updatable Help (http://go.microsoft.com/fwlink/?LinkID=242129) in the MSDN Library. -* The **Update-Help** and **Save-Help** cmdlets are not supported on Windows Preinstallation Environment (Windows PE). + +To update help for the PowerShell Core modules, that contain the commands that are installed with +PowerShell, or any module in the `$PSHOME\Modules` directory, start PowerShell with the option to +**Run as administrator**. + +Only members of the Administrators group on the computer can update help for the PowerShell Core +modules, the commands that are installed together with PowerShell, and for modules in the +`$PSHOME\Modules` folder. If you don't have permission to update help files, you can read the help +files online. For example, `Get-Help Update-Help -Online`. + +Modules are the smallest unit of updatable help. You can't update help for a particular cmdlet. To +find the module that contains a particular cmdlet, use the **ModuleName** property of the +`Get-Command` cmdlet, for example, `(Get-Command Update-Help).ModuleName`. + +Because help files are installed in the module directory, the `Update-Help` cmdlet can install +updated help file only for modules that are installed on the computer. However, the `Save-Help` +cmdlet can save help for modules that aren't installed on the computer. + +If `Update-Help` can't find updated help files for a module, or can't find updated help in the +specified language, it continues silently without displaying an error message. To see status and +progress details, use the **Verbose** parameter. + +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It doesn't work in earlier +versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows +PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and +update help files. The help files are available to both Windows PowerShell 2.0 and Windows +PowerShell 3.0. + +The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 +for HTTP and port 443 for HTTPS. + +`Update-Help` supports all modules and the PowerShell Core snap-ins. It doesn't support any other +snap-ins. + +To update help for a module in a location that isn't listed in the `$env:PSModulePath` environment +variable, import the module into the current session and then run an `Update-Help` command. Run +`Update-Help` without parameters or use the **Module** parameter to specify the module name. The +**Module** parameter of the `Update-Help` and `Save-Help` cmdlets doesn't accept the full path of a +module file or module manifest file. + +Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules +that you author, see [Supporting Updatable Help](/powershell/developer/module/supporting-updatable-help). + +The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment +(Windows PE). ## RELATED LINKS -[Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007)](http://go.microsoft.com/fwlink/?LinkID=270007) +[Get-Culture](../Microsoft.PowerShell.Utility/Get-Culture.md) [Get-Help](Get-Help.md) [Get-Module](Get-Module.md) +[Get-UICulture](../Microsoft.PowerShell.Utility/Get-UICulture.md) + +[Start-Job](Start-Job.md) + [Save-Help](Save-Help.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Update-Help.md b/reference/6/Microsoft.PowerShell.Core/Update-Help.md index 3f019b4f9a0e..79c73ad273ae 100644 --- a/reference/6/Microsoft.PowerShell.Core/Update-Help.md +++ b/reference/6/Microsoft.PowerShell.Core/Update-Help.md @@ -3,11 +3,12 @@ external help file: System.Management.Automation.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Core -ms.date: 01/10/2019 +ms.date: 5/16/2019 online version: http://go.microsoft.com/fwlink/?LinkID=821524 schema: 2.0.0 title: Update-Help --- + # Update-Help ## SYNOPSIS @@ -18,54 +19,54 @@ Downloads and installs the newest help files on your computer. ### Path (Default) ``` -Update-Help [[-Module] ] [[-SourcePath] ] [[-UICulture] ] - [-FullyQualifiedModule ] [-Recurse] [-Credential ] - [-UseDefaultCredentials] [-Force] [-Scope ] [-WhatIf] [-Confirm] [] +Update-Help [[-Module] ] [-FullyQualifiedModule ] +[[-SourcePath] ] [-Recurse] [[-UICulture] ] [-Credential ] +[-UseDefaultCredentials] [-Force] [-Scope ] [-WhatIf] [-Confirm] +[] ``` ### LiteralPath ``` -Update-Help [[-Module] ] [[-UICulture] ] - [-FullyQualifiedModule ] [-LiteralPath ] [-Recurse] - [-Credential ] [-UseDefaultCredentials] [-Force] [-Scope ] - [-WhatIf] [-Confirm] [] +Update-Help [[-Module] ] [-FullyQualifiedModule ] +[-LiteralPath ] [-Recurse] [[-UICulture] ] [-Credential ] +[-UseDefaultCredentials] [-Force] [-Scope ] [-WhatIf] [-Confirm] +[] ``` ## DESCRIPTION -The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them -on your computer. You can use the `Get-Help` cmdlet to view the new help files immediately. You do -not have to restart PowerShell to make the change effective. This feature enables you to install -help files for modules that do not include them and to update help files on your computer so that -they never become obsolete. +The `Update-Help` cmdlet downloads the newest help files for PowerShell modules and installs them on +your computer. You don't need to restart PowerShell to make the change effective. You can use the +`Get-Help` cmdlet to view the new help files immediately. + +`Update-Help` checks the version of the help files on your computer. If you don't have help files +for a module or if your help files are outdated, `Update-Help` downloads the newest help files. The +help files can be downloaded and installed from the internet or a file share. -`Update-Help` checks the version of the help files on your computer. If you do not have help files -for a module or do not have the newest help files for a module, `Update-Help` downloads the newest -help files from the Internet or a file share and installs them on your computer in the correct -module folder. +Without parameters, `Update-Help` updates the help files for modules in the session and for all +installed modules that support Updatable Help. Modules that are installed but not loaded in the +current session are included. PowerShell modules are stored in a location listed in the +`$env:PSModulePath` environment variable. +For more information, see [about_Updatable_Help](./About/about_Updatable_Help.md). -Without parameters, `Update-Help` updates the help for modules in the session and for all installed -modules, in a location listed in the `$env:PSModulePath` environment variable, that support -Updatable Help, even if the module is not in the current session. You can also use the **Module** -parameter to update help for a particular module and use the **UICulture** parameter to download -help files in multiple languages and locales. +You can use the **Module** parameter to update help files for a particular module. Use the +**UICulture** parameter to download help files in multiple languages and locales. -You can use `Update-Help` even on computers that are not connected to the Internet. Use the -`Save-Help` cmdlet to download help files from the Internet and save them in a file system -location, such as a shared folder or file system directory. Then use the **SourcePath** parameter -of `Update-Help` to get the updated help files from a file system location and install them on the -computer. +You can use `Update-Help` on computers that aren't connected to the internet. Use the `Save-Help` +cmdlet to download help files from the internet and save them in a file system location, such as a +shared folder or file system directory. Then use the **SourcePath** parameter of `Update-Help` to +download the updated help files from a file system location and install them on the computer. -You can even automate the running of `Update-Help` by adding an `Update-Help` cmdlet to your -PowerShell profile. By default, `Update-Help` runs only one time per day on each computer. To -override the once-per-day limit, use the **Force** parameter. +You can automate help updates by adding the `Update-Help` cmdlet to your PowerShell profile. By +default, `Update-Help` runs only one time per day on each computer. To override the once-per-day +limit, use the **Force** parameter. -This cmdlet was introduced in Windows PowerShell 3.0. +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. > [!IMPORTANT] > `Update-Help` requires administrative privileges in PowerShell 6.0 and below. -> PowerShell 6.1 and up set the default `-Scope` to **CurrentUser**. +> PowerShell 6.1 and above set the default `-Scope` to **CurrentUser**. > Prior to PowerShell 6.1, the `-Scope` parameter was not available. > > You must be a member of the Administrators group on the computer @@ -73,153 +74,123 @@ This cmdlet was introduced in Windows PowerShell 3.0. > > To download or update the help files for modules in the PowerShell > installation directory (`$PSHOME\Modules`), including the PowerShell -> Core modules, start PowerShell by using the Run as administrator option. +> Core modules, start PowerShell by using the **Run as administrator** option. +> For example: `Start-Process pwsh.exe -Verb RunAs`. ## EXAMPLES -### Example 1: Update help for all modules +### Example 1: Update help files for all modules -This command updates help for all installed modules that support Updatable Help in the language -specified by the UI culture that is set for Windows. +The `Update-Help` cmdlet updates help files for installed modules that support Updatable Help. The +user-interface (UI) culture language is set in the operating system. ```powershell -PS> Update-Help -PS> Update-Help -Scope CurrentUser +Update-Help ``` -To run this command, start PowerShell by using the Run as administrator option (`Start-Process -pwsh.exe -Verb RunAs`). - -### Example 2: Update help for specified modules +### Example 2: Update help files for specified modules -This command updates help only for the ServerManager module and for modules that have names that -begin with Microsoft.PowerShell. +The `Update-Help` cmdlet updates help files only for module names that begin with +**Microsoft.PowerShell**. ```powershell -Update-Help -Module ServerManager, Microsoft.PowerShell* +Update-Help -Module Microsoft.PowerShell* ``` -Because these modules are in the $pshome\Modules folder, to run this command, start PowerShell by -using the Run as administrator option. +### Example 3: Update help files for different languages -### Example 3: Update help in different languages +The `Update-Help` cmdlet updates the Japanese (ja-JP) and English (en-US) help files for all +modules. -This command updates the Japanese and English help files for all modules. +If a module doesn't provide help files for a specified UI culture, an error message is displayed for +the module and UI culture. In this example, the error message indicates that the **ja-JP** help +files were not found for module **Microsoft.PowerShell.Utility**. ```powershell Update-Help -UICulture ja-JP, en-US ``` ```Output -Update-Help : Failed to update Help for the module(s) 'ServerManager' with UI culture(s) {ja-JP} : -The specified culture is not supported: ja-JP. Specify a culture from the following list: {en-US}. +Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Utility' with UI culture(s) {ja-JP} +No UI culture was found that matches the following pattern: ja-JP. ``` -If a module currently does not provide help files for the specified UI culture, the error message -lists the UI cultures that the module supports. In this example, the error message indicates that -the ServerManager module currently provides help files only in en-US. +### Example 4: Update help files on multiple computers from a file share -### Example 4: Update help automatically +In this example, updated help files are downloaded from the internet and saved in a file share. User +credentials are needed that have permissions to access the file share and install updates. When a +file share is used, it's possible to update computers that are behind firewalls or aren't connected +to the internet. -This command creates a scheduled job that updates help for all modules on the computer every day at -3:00 in the morning. - -```powershell -$jobParams = @{ - Name = 'UpdateHelpJob' - Credential = 'Domain01\User01' - ScriptBlock = '{Update-Help}' - Trigger = (New-JobTrigger -Daily -At "3 AM") -} -Register-ScheduledJob @jobParams ``` - -```Output -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 UpdateHelpJob 1 Update-Help True +PS> Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock { + Update-Help -SourcePath \\Server01\Share\PSHelp -Credential Domain01\Admin01 +} ``` -The command uses the `Register-ScheduledJob` cmdlet to create a scheduled job that runs an -`Update-Help` command. The command uses the **Credential** parameter to run `Update-Help` by using -the credentials of a member of the Administrators group on the computer. The value of the -**Trigger** parameter is a `New-JobTrigger` command that creates a job trigger that starts the job -every day at 3:00 AM. +The `Save-Help` command downloads the newest help files for all modules that support Updatable Help. +The **DestinationPath** parameter saves the files in the `\\Server01\Share\PSHelp` file share. The +**Credential** parameter specifies a user who has permission to access the file share. -To run the `Register-ScheduledJob` command, start PowerShell by using the Run as administrator -option. When you run the command, PowerShell prompts you for the password of the user specified in -the value of the **Credential** parameter. The credentials are stored with the scheduled job. You -are not prompted when the job runs. +The `Invoke-Command` cmdlet runs remote `Update-Help` commands on multiple computers. The +**ComputerName** parameter gets a list of remote computers from the **Servers.txt** file. The +**ScriptBlock** parameter runs the `Update-Help` command and uses the **SourcePath** parameter to +specify the file share that contains the updated help files. The **Credential** parameter specifies +a user who can access the file share and run the remote `Update-Help` command. -You can use the `Get-ScheduledJob` cmdlet to view the scheduled job, use the `Set-ScheduledJob` -cmdlet to change it, and use the `Unregister-ScheduledJob` cmdlet to delete it. You can also view -and manage the scheduled job in Task Scheduler in the following path: -`Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs` +### Example 5: Get a list of updated help files -### Example 5: Update help on multiple computers from a file share +The `Update-Help` cmdlet updates help for a specified module. The cmdlet uses the **Verbose** common +parameter to display the list of help files that were updated. You can use **Verbose** to view +output for all help files or help files for a specific module. -These commands download updated help files for system modules from the Internet and save them in -file share. Then the commands install the updated help files from the file share on multiple -computers. You can use a strategy such as the one shown here to update the help files on many -computers, even those that are behind firewalls or are not connected to the Internet. - -All of the commands in this example were run in a PowerShell session that was started by using the -Run as administrator option. +Without the **Verbose** parameter, `Update-Help` doesn't display the results of the command. The +**Verbose** parameter output is useful to verify that the help files were updated or if the latest +version is installed. ```powershell -Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01 -Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock { - Update-Help -SourcePath \\Server01\Share\Help -Credential Domain01\Admin01 -} +Update-Help -Module Microsoft.PowerShell.Utility -Verbose ``` -The first command uses `Save-Help` to download the newest help files for all modules that support -Updatable Help. The command saves the downloaded help files in the \\Server01\Share\PSHelp file -share. The command uses the **Credential** parameter of the `Save-Help` cmdlet to specify the -credentials of a user who has permission to access the remote file share. By default, the command -does not run with explicit credentials and attempts to access the file share might fail. - -The second command uses the Invoke-Command cmdlet to run `Update-Help` commands on many computers -remotely. The `Invoke-Command` command gets the list of computers from the Servers.txt file. The -`Update-Help` command installs the help files from the file share on all of the remote computers. -The remote computer must be able to access the file share at the specified path.The `Update-Help` -command uses **SourcePath** to get the updated help files from the file share, instead of the -Internet, and the **Credential** parameter to run the command by using explicit credentials. By -default, the command runs with network token privileges and attempts to access the file share from -each remote computer (a "second hop") might fail. - -### Example 6: Get a List of Updated Help Files +### Example 6: Find modules that support Updatable Help -This command updates help for two modules. It uses the **Verbose** common parameter of -`Update-Help` to get a list of the help files that the command updated. +This example lists modules that support Updatable Help. The command uses the module's +**HelpInfoUri** property to identify modules that support Updatable Help. The **HelpInfoUri** +property contains an address that is redirected when the `Update-Help` cmdlet is run. ```powershell -Update-Help -Module BestPractices, ServerManager -Verbose +Get-Module -ListAvailable | Where-Object -Property HelpInfoUri ``` -Without the **Verbose** parameter, `Update-Help` does not display the results of the command. The -**Verbose** parameter is especially useful when you want to verify that you have updated help files -for a particular module or a particular locale. +```output + Directory: C:\program files\powershell\6\Modules -### Example 7: Find modules that support Updatable Help +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 6.1.0.0 CimCmdlets Core {Get-CimAssociatedInstance... } +Manifest 1.2.2.0 Microsoft.PowerShell.Archive Desk {Compress-Archive... } +Manifest 6.1.0.0 Microsoft.PowerShell.Diagnostics Core {Get-WinEvent, New-WinEvent} -This command gets modules that support Updatable Help. + Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules -```powershell -Get-Module -ListAvailable | Where HelpInfoUri +ModuleType Version Name PSEdition ExportedCommands +---------- ------- ---- --------- ---------------- +Manifest 2.0.1.0 Appx Core,Desk {Add-AppxPackage, ... } +Script 1.0.0.0 AssignedAccess Core,Desk {Clear-AssignedAccess, ... } +Manifest 1.0.0.0 BitLocker Core,Desk {Unlock-BitLocker, ... } ``` -The command uses the **HelpInfoUri** property of modules to identify modules that support Updatable -Help. The value of the **HelpInfoUri** property contains the address of the Internet location where -the module stores its Updatable Help information file. +### Example 7: Inventory updated help files -This command uses the simplified syntax of the `Where-Object` cmdlet. This syntax is introduced in -Windows PowerShell 3.0. +In this example, the script `Get-UpdateHelpVersion.ps1` creates an inventory of the Updatable Help +files for each module and their version numbers. -### Example 8: Inventory updated help files +The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of +modules. For modules that support Updatable Help, the script looks for and parses the help +information file (*helpinfo.xml) to find the latest version number. -The example `Get-UpdateHelpVersion.ps1` script creates an inventory of the Updatable Help files for -each module and their version numbers. Copy the script and paste it in a text file. +The script uses the **PSCustomObject** class and a hash table to create a custom output object. ``` # Get-UpdateHelpVersion.ps1 @@ -263,24 +234,18 @@ ADDSDeployment en-US ADFS en-US 3.0.0.0 ``` -The script identifies modules that support Updatable Help by using the **HelpInfoUri** property of -modules. For modules that support Updatable Help, the script looks for and parses the help -information file (HelpInfo XML) to find the latest version number. - -The script uses the **PSCustomObject** class and a hash table to create a custom output object. - ## PARAMETERS ### -Credential Specifies credentials of a user who has permission to access the file system location specified by -**SourcePath**. This parameter is valid only when the **SourcePath** or **LiteralPath** parameter -is used in the command. +**SourcePath**. This parameter is valid only when the **SourcePath** or **LiteralPath** parameter is +used in the command. -This parameter enables you to run `Update-Help` commands with the **SourcePath** parameter on -remote computers. By providing explicit credentials, you can run the command on a remote computer -and access a file share on a third computer without encountering an access denied error or using -CredSSP authentication to delegate credentials. +The **Credential** parameter enables you to run `Update-Help` commands with the **SourcePath** +parameter on remote computers. By providing explicit credentials, you can run the command on a +remote computer and access a file share on a third computer without encountering an access denied +error or using CredSSP authentication to delegate credentials. ```yaml Type: PSCredential @@ -296,19 +261,20 @@ Accept wildcard characters: False ### -Force -Indicates that this cmdlet does not follow the once-per-day limitation, skips version checking, and +Indicates that this cmdlet doesn't follow the once-per-day limitation, skips version checking, and downloads files that exceed the 1 GB limit. -Without this parameter, `Update-Help` runs only once in each 24-hour period, downloads are limited -to 1 GB of uncompressed content per module and help files are installed only when they are newer -than the files on the computer. +Without this parameter, `Update-Help` runs only once in each 24-hour period. Downloads are limited +to 1 GB of uncompressed content per module and help files are only installed when they're newer than +the existing files on the computer. The once-per-day limit protects the servers that host the help files and makes it practical for you to add an `Update-Help` command to your PowerShell profile without incurring the resource cost of repeated connections or downloads. To update help for a module in multiple UI cultures without the **Force** parameter, include all UI -cultures in the same command, such as: +cultures in the same command, such as: + `Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR` ```yaml @@ -326,14 +292,21 @@ Accept wildcard characters: False ### -FullyQualifiedModule Specifies modules with names that are specified in the form of **ModuleSpecification** objects. -These are described in the Remarks section of +These modules are described in the Remarks section of [ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor?view=powershellsdk-1.1.0#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). -For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format -`@{ModuleName = "modulename"; ModuleVersion = "version_number"}` or + +For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in the +format: + +`@{ModuleName = "modulename"; ModuleVersion = "version_number"}` + +or + `@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}.` + **ModuleName** and **ModuleVersion** are required, but **Guid** is optional. -You cannot specify the **FullyQualifiedModule** parameter in the same command as a **Module** +You can't specify the **FullyQualifiedModule** parameter in the same command as a **Module** parameter. ```yaml @@ -350,17 +323,17 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the folder for updated help files instead of downloading them from the Internet. Use this -parameter or **SourcePath** if you have used the `Save-Help` cmdlet to download help files to a +Specifies the folder for updated help files instead of downloading them from the internet. Use this +parameter or **SourcePath** if you've used the `Save-Help` cmdlet to download help files to a directory. -You can also pipe a directory object, such as one from the Get-Item or Get-ChildItem cmdlets, to +You can pipeline a directory object, such as from the `Get-Item` or `Get-ChildItem` cmdlets, to `Update-Help`. -Unlike the value of *SourcePath*, the value of **LiteralPath** is used exactly as it is typed. No +Unlike the value of **SourcePath**, the value of **LiteralPath** is used exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes escape characters, enclose -it in single quotation marks. Single quotation marks tell PowerShell not to interpret any -characters as escape sequences. +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. ```yaml Type: String[] @@ -376,23 +349,22 @@ Accept wildcard characters: False ### -Module -Specifies modules for which this cmdlet updates help. Enter one or more module names or name -patterns in a comma-separated list, or specify a file that lists one module name on each line. -Wildcard characters are permitted. You can also pipe modules from the Get-Module cmdlet, to the -`Update-Help` cmdlet. +Updates help for the specified modules. Enter one or more module names or name patterns in a +comma-separated list, or specify a file that lists one module name on each line. Wildcard characters +are permitted. You can pipeline modules from the `Get-Module` cmdlet to the `Update-Help` cmdlet. -The modules that you specify must be installed on the computer, but they do not have to be imported +The modules that you specify must be installed on the computer, but they don't have to be imported into the current session. You can specify any module in the session or any module that is installed -in a location listed in the **PSModulePath** environment variable. +in a location listed in the `$env:PSModulePath` environment variable. -A value of * (all) attempts to update help for all modules that are installed on the computer. This -includes modules that do not support Updatable Help. This value might generate errors when the -command encounters modules that do not support Updatable Help. Instead, run `Update-Help` without +A value of `*` (all) attempts to update help for all modules that are installed on the computer. +Modules that don't support Updatable Help are included. This value might generate errors when the +command encounters modules that don't support Updatable Help. Instead, run `Update-Help` without parameters. -The **Module** parameter of the `Update-Help` cmdlet does not accept the full path of a module file -or module manifest file. To update help for a module that is not in a PSModulePath location, import -the module into the current session before you run the `Update-Help` command. +The **Module** parameter of the `Update-Help` cmdlet doesn't accept the full path of a module file +or module manifest file. To update help for a module that isn't in a `$env:PSModulePath` location, +import the module into the current session before you run the `Update-Help` command. ```yaml Type: String[] @@ -403,12 +375,13 @@ Required: False Position: 0 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Recurse Searches recursively for help files in the specified directory. This parameter is +### -Recurse -valid only when **SourcePath** is used in the command. +Performs a recursive search for help files in the specified directory. This parameter is valid only +when the command uses the **SourcePath** parameter. ```yaml Type: SwitchParameter @@ -424,21 +397,19 @@ Accept wildcard characters: False ### -Scope -Specifies the system scope where help is to be updated. Note that updating help at the **AllUsers** -scope requires administrative privileges on Windows systems. +Specifies the system scope where help is updated. Updates at the **AllUsers** scope require +administrative privileges on Windows systems. The `-Scope` parameter was introduced in PowerShell +Core version 6.1. -**CurrentUser** is the default scope for help from PowerShell 6.1 onwards, but **AllUsers** may be -specified to install or update help for all users. Note that on Unix systems `sudo` privileges are -required to update help for all users. For example: `sudo pwsh -c Update-Help` +**CurrentUser** is the default scope for help files in PowerShell 6.1 and above. **AllUsers** can be +specified to install or update help for all users. On Unix systems `sudo` privileges are required to +update help for all users. For example: `sudo pwsh -c Update-Help` The acceptable values are: - CurrentUser - AllUsers - -The `-Scope` parameter was introduced in PowerShell Core version 6.1. - ```yaml Type: UpdateHelpScope Parameter Sets: (All) @@ -453,18 +424,18 @@ Accept wildcard characters: False ### -SourcePath -Specifies a file system folder from which this cmdlet gets updated help files, instead of -downloading them from the Internet. Enter the path of a folder. Do not specify a file name or file -name extension. You can also pipe a folder, such as one from the Get-Item or Get-ChildItem cmdlets, -to `Update-Help`. +Specifies a file system folder where `Update-Help` gets updated help files, instead of downloading +them from the internet. Enter the path of a folder. Don't specify a file name or file name +extension. You can pipeline a folder, such as one from the `Get-Item` or `Get-ChildItem` cmdlets, to +`Update-Help`. -By default, `Update-Help` downloads updated help files from the Internet. Use this parameter when -you have used the `Save-Help` cmdlet to download updated help files to a directory. +By default, `Update-Help` downloads updated help files from the internet. Use **SourcePath** when +you've used the `Save-Help` cmdlet to download updated help files to a directory. -Administrators can use the Set the default source path for Update-Help Group Policy setting under -Computer Configuration to specify a default value for *SourcePath*. This Group Policy setting -prevents users from using `Update-Help` to download help files from the Internet. For more -information, see [about_Group_Policy_Settings](about/about_Group_Policy_Settings.md). +To specify a default value for **SourcePath**, go to **Group Policy**, **Computer Configuration**, +and **Set the default source path for Update-Help**. This Group Policy setting prevents users from +using `Update-Help` to download help files from the internet. +For more information, see [about_Group_Policy_Settings](./About/about_Group_Policy_Settings.md). ```yaml Type: String[] @@ -480,18 +451,17 @@ Accept wildcard characters: False ### -UICulture -Specifies UI culture values for which this cmdlet gets updated help files. Enter one or more -language codes, such as es-ES, a variable that contains culture objects, or a command that gets -culture objects, such as a Get-Culture or Get-UICulture command. Wildcard characters are not -permitted and you cannot submit a partial language code, such as "de". +Specifies UI culture values that `Update-Help` uses to get updated help files. Enter one or more +language codes, such as **es-ES**, a variable that contains culture objects, or a command that gets +culture objects, such as a `Get-Culture` or `Get-UICulture` command. Wildcard characters aren't +permitted and you can't submit a partial language code, such as **de**. -By default, `Update-Help` gets help files in the UI culture set for Windows or its fallback -culture. If you specify the **UICulture** parameter, `Update-Help` looks for help only for the -specified UI culture, not in any fallback culture. +By default, `Update-Help` gets help files in the UI culture set for the operating system. If you +specify the **UICulture** parameter, `Update-Help` looks for help only for the specified UI culture. Commands that use the **UICulture** parameter succeed only when the module provides help files for -the specified UI culture. If the command fails because the specified UI culture is not supported, -the error message includes a list of UI cultures that the module supports. +the specified UI culture. If the command fails because the specified UI culture isn't supported, an +error message is displayed. ```yaml Type: CultureInfo[] @@ -507,11 +477,11 @@ Accept wildcard characters: False ### -UseDefaultCredentials -Indicates that this cmdlet runs the command, including the Internet download, by using the +Indicates that `Update-Help` runs the command, including the internet download, by using the credentials of the current user. By default, the command runs without explicit credentials. -This parameter is effective only when the Web download uses NTLM, negotiate, or Kerberos-based -authentication. +This parameter is effective only when the web download uses NT LAN Manager (NTLM), negotiate, or +Kerberos-based authentication. ```yaml Type: SwitchParameter @@ -543,7 +513,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -561,79 +531,81 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.IO.DirectoryInfo -You can pipe a directory path to this cmdlet. +You can pipe a directory path to `Update-Help`. ### System.Management.Automation.PSModuleInfo -You can pipe a module object from the Get-Module cmdlet to this cmdlet. +You can pipe a module object from the `Get-Module` cmdlet to `Update-Help`. ## OUTPUTS ### None -This cmdlet does not generate any output. +`Update-Help` doesn't generate any output. ## NOTES -* To update help for the PowerShell Core modules, which contain the commands that are installed - with PowerShell, or any module in the $pshome\Modules folder, start PowerShell by using the Run as - administrator option. +To update help for the PowerShell Core modules, that contain the commands that are installed with +PowerShell, or any module in the `$PSHOME\Modules` directory, start PowerShell with the option to +**Run as administrator**. - Only members of the Administrators group on the computer can update help for the for the - PowerShell Core modules, the commands that are installed together with PowerShell, and for - modules in the `$pshome\Modules` folder. If you do not have permission to update help files, you - might be able to read the help topics online. To open the online version of any cmdlet help - topic, type `Get-Help -Online`. +Only members of the Administrators group on the computer can update help for the PowerShell Core +modules, the commands that are installed together with PowerShell, and for modules in the +`$PSHOME\Modules` folder. If you don't have permission to update help files, you can read the help +files online. For example, `Get-Help Update-Help -Online`. -* Modules are the smallest unit of updatable help. You cannot update help for a particular cmdlet. - To find the module that contains a particular cmdlet, use the **ModuleName** property of the - Get-Command cmdlet, for example, `(Get-Command \).ModuleName` +Modules are the smallest unit of updatable help. You can't update help for a particular cmdlet. To +find the module that contains a particular cmdlet, use the **ModuleName** property of the +`Get-Command` cmdlet, for example, `(Get-Command Update-Help).ModuleName`. -* Because help files are installed in the module directory, the `Update-Help` cmdlet can install - updated help file only for modules that are installed on the computer. However, the `Save-Help` - cmdlet can save help for modules that are not installed on the computer. +Because help files are installed in the module directory, the `Update-Help` cmdlet can install +updated help file only for modules that are installed on the computer. However, the `Save-Help` +cmdlet can save help for modules that aren't installed on the computer. -* If `Update-Help` cannot find updated help files for a module, or cannot find updated help in the - specified language, it continues silently without displaying an error message. To see status and - progress details, use the **Verbose** parameter. +If `Update-Help` can't find updated help files for a module, or can't find updated help in the +specified language, it continues silently without displaying an error message. To see status and +progress details, use the **Verbose** parameter. -* The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It does not work in earlier - versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows - PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and - update help files. The help files are available to both Windows PowerShell 2.0 and Windows - PowerShell 3.0. +The `Update-Help` cmdlet was introduced in Windows PowerShell 3.0. It doesn't work in earlier +versions of Windows PowerShell. On computers that have both Windows PowerShell 2.0 and Windows +PowerShell 3.0, use the `Update-Help` cmdlet in a Windows PowerShell 3.0 session to download and +update help files. The help files are available to both Windows PowerShell 2.0 and Windows +PowerShell 3.0. -* The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 - for HTTP and port 443 for HTTPS. +The `Update-Help` and `Save-Help` cmdlets use the following ports to download help files: Port 80 +for HTTP and port 443 for HTTPS. -* `Update-Help` supports all modules and the Windows PowerShell Core snap-ins. It does not support - any other snap-ins. +`Update-Help` supports all modules and the PowerShell Core snap-ins. It doesn't support any other +snap-ins. -* To update help for a module in a location that is not listed in the **PSModulePath** environment - variable, import the module into the current session and then run an `Update-Help` command. Run - `Update-Help` without parameters or use the **Module** parameter to specify the module name. The - **Module** parameter of the `Update-Help` and `Save-Help` cmdlets does not accept the full path - of a module file or module manifest file. +To update help for a module in a location that isn't listed in the `$env:PSModulePath` environment +variable, import the module into the current session and then run an `Update-Help` command. Run +`Update-Help` without parameters or use the **Module** parameter to specify the module name. The +**Module** parameter of the `Update-Help` and `Save-Help` cmdlets doesn't accept the full path of a +module file or module manifest file. -* Any module can support Updatable Help. For instructions for supporting Updatable Help in the - modules that you author, see [Supporting Updatable Help](/powershell/developer/module/supporting-updatable-help). +Any module can support Updatable Help. For instructions for supporting Updatable Help in the modules +that you author, see [Supporting Updatable Help](/powershell/developer/module/supporting-updatable-help). -* The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation - Environment (Windows PE). +The `Update-Help` and `Save-Help` cmdlets are not supported on Windows Preinstallation Environment +(Windows PE). ## RELATED LINKS +[Get-Culture](../Microsoft.PowerShell.Utility/Get-Culture.md) + [Get-Help](Get-Help.md) [Get-Module](Get-Module.md) +[Get-UICulture](../Microsoft.PowerShell.Utility/Get-UICulture.md) + [Start-Job](Start-Job.md) [Save-Help](Save-Help.md) \ No newline at end of file