diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index c787084f4431..de8739772852 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,7 +1,7 @@ --- description: Describes the updatable help system in PowerShell. Locale: en-US -ms.date: 08/04/2020 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_updatable_help?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Updatable Help @@ -22,31 +22,30 @@ can read them at the command line. It makes it easy to download and install help files and to update them whenever newer help files become available. To provide updated help for multiple computers in an enterprise and for -computers that do not have access to the internet, Updatable Help lets you +computers that don't have access to the internet, Updatable Help lets you download help files to a filesystem directory or file share, and then install the help files from the file share. In PowerShell 4.0, the **HelpInfoUri** property is preserved over Windows PowerShell remoting, which allows `Save-Help` to work for modules that are -installed on a remote computer, but are not necessarily installed on the local +installed on a remote computer, but aren't necessarily installed on the local computer. You can save a **PSModuleInfo** object to disk or removable media -(such as a USB drive) by running `Export-Clixml` on a computer that does not +(such as a USB drive) by running `Export-Clixml` on a computer that doesn't have internet access, importing the **PSModuleInfo** object on a computer that does have internet access, and then running `Save-Help` on the **PSModuleInfo** object. The saved help can be copied to the remote, disconnected computer by using removable media, and then installed by running `Update-Help`. These improvements in `Save-Help` functionality let you install help on computers that are without any kind of network access. For an example of how to use the -new `Save-Help` functionality, see -[How to update help from a file share](#how-to-update-help-from-a-file-share) +new `Save-Help` functionality, see [How to update help from a file share][03] in this topic. Updatable Help also supports online access to the newest help topics and basic help for cmdlets, even when there are no help files on the computer. -PowerShell 3.0 does not come with Help files. You can use the Updatable Help -feature to install the help files for all of the commands that are included by -default in PowerShell and for all Windows modules. +PowerShell doesn't come with Help files. You can use the Updatable Help feature +to install the help files for all the commands that are included by default +in PowerShell and for all Windows modules. ## Updatable help cmdlets @@ -59,20 +58,20 @@ default in PowerShell and for all Windows modules. - `Get-Help`: Displays help topics at the command line. Gets help from the help files on the computer. Displays auto-generated help for cmdlets and functions - that do not have help files. Opens online help topics for cmdlets, functions, + that don't have help files. Opens online help topics for cmdlets, functions, scripts, and workflows in your default internet browser. ## Update help in the PowerShell ISE -You can also update help by using the **Update PowerShell Help** item in the -Help menu in PowerShell Integrated Scripting Environment (ISE). +You can also update help using the **Update PowerShell Help** item in the Help +menu in PowerShell Integrated Scripting Environment (ISE). The **Update PowerShell Help** item runs an `Update-Help` command without parameters. ## Auto-generated help: help without help files -If you do not have the help file for a cmdlet, function, or workflow on the +If you don't have the help file for a cmdlet, function, or workflow on the computer, the `Get-Help` cmdlet displays auto-generated help and prompts you to download the help files or read them online. @@ -105,11 +104,11 @@ REMARKS ## Help files for modules The smallest unit of Updatable Help is help for a module. Module help includes -help for all of the cmdlets, functions, workflows, providers, scripts, and +help for all the cmdlets, functions, workflows, providers, scripts, and concepts in a module. You can update help for all modules that are installed on -the computer, even if they are not imported into the current session. +the computer, even if they're not imported into the current session. -You can update help for the entire module, but you cannot update help for +You can update help for the entire module, but you can't update help for individual cmdlets. To find the module that contains a particular cmdlet, use the following command @@ -144,11 +143,11 @@ Update-Help -Module Microsoft.PowerShell.Security To update help for the modules in the directory `$pshome/Modules`, you must be member of the Administrators group on the computer. -If you are not a member of the Administrators group, you cannot update help for +If you aren't a member of the Administrators group, you can't update help for these modules; but if you have internet access, you can view help online. Updating help for modules in the directory `$HOME/Documents/PowerShell/Modules` -or modules in other subdirectories of the `$HOME` directory does not require +or modules in other subdirectories of the `$HOME` directory doesn't require special permissions. The `Update-Help` and `Save-Help` cmdlets have a **UseDefaultCredentials** @@ -166,7 +165,7 @@ the SourcePath or **LiteralPath** parameters of `Update-Help` and the To download and install help files for the first time, or to update the help files on your computer, use the `Update-Help` cmdlet. -The `Update-Help` cmdlet does all of the hard work for you, including the +The `Update-Help` cmdlet does all the hard work for you, including the following tasks. - Determines which modules support Updatable Help. @@ -180,7 +179,7 @@ following tasks. - Installs the help files in the language-specific subdirectory of the module directory. -To access the new help topics, use the `Get-Help` cmdlet. You do not need to +To access the new help topics, use the `Get-Help` cmdlet. You don't need to restart PowerShell. To install or update help for all modules on the computer that supports @@ -203,16 +202,16 @@ Without parameters, `Update-Help` updates help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the PSModulePath environment variable. These are also modules that are returned by -a "Get-Help -ListAvailable" command. +a `Get-Module -ListAvailable` command. If the value of the **Module** parameter is `*` (all), `Update-Help` attempts -to update help for all installed modules, including modules that do not support +to update help for all installed modules, including modules that don't support Updatable Help. This command typically generates many errors as the cmdlet -encounters modules that do not support Updatable Help. +encounters modules that don't support Updatable Help. ## How to update help from a file share -To support computers that are not connected to the internet, or to control or +To support computers that aren't connected to the internet, or to control or streamline help updating in an enterprise, use the `Save-Help` cmdlet. The `Save-Help` cmdlet downloads help files from the internet and saves them in a filesystem directory that you specify. @@ -220,7 +219,7 @@ filesystem directory that you specify. `Save-Help` compares the help files in the specified directory to the newest help files that are available for each module. If the directory has no help files or newer help files are available for the module, the `Save-Help` cmdlet -downloads the new files from the internet. However, it does not unwrap or +downloads the new files from the internet. However, it doesn't unwrap or install the help files. To install or update the help files on a computer from help files that were @@ -243,24 +242,27 @@ Update-Help -SourcePath \\Server\Share ``` The following examples show the use of `Save-Help` to save help for modules -that are not installed on the local computer. In this example, the -administrator runs `Save-Help` to save the help for the DhcpServer module from -an internet-connected client computer, without installing the DhcpServer module -or DHCP Server role on the local computer. +that aren't installed on the local computer. In this example, the administrator +runs `Save-Help` to save the help for the DhcpServer module from an +internet-connected client computer, without installing the DhcpServer module or +DHCP Server role on the local computer. Option 1: Run `Invoke-Command` to get the **PSModuleInfo** object for the remote module, save it in a variable, `$m`, and then run `Save-Help` on the **PSModuleInfo** object by specifying the variable `$m` as the module name. ```powershell -$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock -{ Get-Module -Name DhcpServer -ListAvailable } +$invokeCommandSplat = @{ + ComputerName = 'RemoteServer' + ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable } +} +$m = Invoke-Command @invokeCommandSplat Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 2: Open a PSSession targeted at the computer that is running the DHCP +Option 2: Open a PSSession targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -269,9 +271,9 @@ $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 3: Open a CIM session, targeted at the computer that is running the DHCP +Option 3: Open a CIM session, targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -281,14 +283,14 @@ Save-Help -Module $m -DestinationPath C:\SavedHelp ``` In the following example, the administrator installs help for the DHCP Server -module on a computer that does not have network access. +module on a computer that doesn't have network access. First, run `Export-Clixml` to export the **PSModuleInfo** object to a shared folder or to removable media. ```powershell $m = Get-Module -Name DhcpServer -ListAvailable -Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m ``` Next, transport the removable media to a computer that has internet access, and @@ -296,44 +298,44 @@ then import the **PSModuleInfo** object with `Import-Clixml`. Run `Save-Help` to save the Help for the imported DhcpServer module **PSModuleInfo** object. ```powershell -$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath E:\UsbFlashDrive\SavedHelp +$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml +Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp ``` -Finally, transport the removable media back to the computer that does not have +Finally, transport the removable media back to the computer that doesn't have network access, and then install the help by running `Update-Help`. ```powershell -Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp ``` Without parameters, `Save-Help` downloads help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the -`$env:PSModulePath` environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules that are -returned by running a `Get-Help -ListAvailable` command. +`$env:PSModulePath` environment variable, on either the local computer or on a +remote computer for which you want to save help. These are also modules that +are returned by running a `Get-Help -ListAvailable` command. ## How to update help files in different languages By default, the `Update-Help` and `Save-Help` cmdlets download help in the UI -culture and language that is set for Windows on the local computer. If help -files for the specified modules are not available in the local UI culture, +culture and language that's set for Windows on the local computer. If help +files for the specified modules aren't available in the local UI culture, `Update-Help` and `Save-Help` use the Windows language fallback rules to find the best supported language. However, you can use the **UICulture** parameters of the `Update-Help` and `Save-Help` cmdlets to download and install help files in any UI cultures in -which they are available. +which they're available. For example, to save the newest help files for all modules on the session in -Japanese (Ja-jp) and French (fr-FR), type: +Japanese (ja-Jp) and French (fr-FR), type: ```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr ``` -If help files for the modules are not available in the languages that you +If help files for the modules aren't available in the languages that you specified, the `Update-Help` and `Save-Help` cmdlets return an error message that lists the languages in which help for each module is available so you can choose the alternative that best meets your needs. @@ -343,8 +345,8 @@ choose the alternative that best meets your needs. ## How to use online help -If you cannot or choose not to update the help files on your local computer, -you can still get the newest help files online. +If you can't or choose not to update the help files on your local computer, you +can still get the newest help files online. To open the online help topic for any cmdlet or function, use the **Online** parameter of the `Get-Help` cmdlet. @@ -359,13 +361,13 @@ Get-Help Get-Job -Online To get online help for a script, use the **Online** parameter and the full path to the script. -The **Online** parameter does not work with About topics. To see the about +The **Online** parameter doesn't work with About topics. To see the about topics for PowerShell, including help topics about the PowerShell language, see -[PowerShell About Topics](about.md). +[PowerShell About Topics][05]. ## How to minimize or prevent internet downloads -To minimize internet downloads and provide Updatable Help to users who are not +To minimize internet downloads and provide Updatable Help to users who aren't connected to the internet, use the `Save-Help` cmdlet. Download help from the internet and save it to a network share. Then, create a Group Policy setting or scheduled job that runs an `Update-Help` command on all computers. Set the @@ -379,7 +381,7 @@ Policy setting. This Group Policy setting implicitly adds the **SourcePath** parameter, with the filesystem location that you specify, to every `Update-Help` command on every affected computer. Users can use the **SourcePath** parameter explicitly -to specify a different filesystem location, but they cannot exclude the +to specify a different filesystem location, but they can't exclude the **SourcePath** parameter and download help from the internet. > [!NOTE] @@ -389,47 +391,56 @@ to specify a different filesystem location, but they cannot exclude the > policy setting under **User Configuration** is ignored. For more information, see -[about_Group_Policy_Settings](about_Group_Policy_Settings.md). +[about_Group_Policy_Settings][04]. ## How to update help for non-standard modules -To update or save help for a module that is not returned by the +To update or save help for a module that's not returned by the **ListAvailable** parameter of the `Get-Module` cmdlet, import the module into the current session before running an `Update-Help` or `Save-Help` command. On a remote computer, before running the `Save-Help` command, import the module -into the current Session, or `Invoke-Command` script block, that is connected -to the remote computer. +into the current Session, or `Invoke-Command` script block, that's connected to +the remote computer. When the module is in the current session, run the `Update-Help` or `Save-Help` cmdlets without parameters, or use the **Module** parameter to specify the module name. The **Module** parameters of the `Update-Help` and `Save-Help` cmdlets accept -only a module name. They do not accept the path to a module file. +only a module name. They don't accept the path to a module file. -Use this technique to update or save help for any module that is not returned -by the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module -that is installed in a location that is not listed in the `$env:PSModulePath` -environment variable, or a module that is not well-formed (the module directory -does not contain at least one file whose basename is the same as the directory +Use this technique to update or save help for any module that's not returned by +the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module +that's installed in a location that's not listed in the `$env:PSModulePath` +environment variable, or a module that's not well-formed (the module directory +doesn't contain at least one file whose basename is the same as the directory name). ## How to support updatable help If you author a module, you can support online help and Updatable Help for your -modules. For more information, see -[Supporting Updatable Help](/powershell/scripting/developer/help/supporting-updatable-help) -and [Supporting Online Help](/powershell/scripting/developer/module/supporting-online-help). +modules. For more information, see [Supporting Updatable Help][01] and +[Supporting Online Help][02]. Updatable help not available for PowerShell snap-ins or comment-based help. ## Remarks -The `Update-Help` and `Save-Help` cmdlets are not supported on Windows +The `Update-Help` and `Save-Help` cmdlets aren't supported on Windows Preinstallation Environment (Windows PE). ## See also -- [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) -- [Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) -- [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) +- [Get-Help][06] +- [Save-Help][07] +- [Update-Help][08] + + +[01]: /powershell/scripting/developer/help/supporting-updatable-help +[02]: /powershell/scripting/developer/module/supporting-online-help +[03]: #how-to-update-help-from-a-file-share +[04]: about_Group_Policy_Settings.md +[05]: about.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 8b915d24bc3f..e6b7e3d620a4 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,7 +1,7 @@ --- description: Describes the updatable help system in PowerShell. Locale: en-US -ms.date: 08/04/2020 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_updatable_help?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Updatable Help @@ -22,31 +22,30 @@ can read them at the command line. It makes it easy to download and install help files and to update them whenever newer help files become available. To provide updated help for multiple computers in an enterprise and for -computers that do not have access to the internet, Updatable Help lets you +computers that don't have access to the internet, Updatable Help lets you download help files to a filesystem directory or file share, and then install the help files from the file share. In PowerShell 4.0, the **HelpInfoUri** property is preserved over Windows PowerShell remoting, which allows `Save-Help` to work for modules that are -installed on a remote computer, but are not necessarily installed on the local +installed on a remote computer, but aren't necessarily installed on the local computer. You can save a **PSModuleInfo** object to disk or removable media -(such as a USB drive) by running `Export-Clixml` on a computer that does not +(such as a USB drive) by running `Export-Clixml` on a computer that doesn't have internet access, importing the **PSModuleInfo** object on a computer that does have internet access, and then running `Save-Help` on the **PSModuleInfo** object. The saved help can be copied to the remote, disconnected computer by using removable media, and then installed by running `Update-Help`. These improvements in `Save-Help` functionality let you install help on computers that are without any kind of network access. For an example of how to use the -new `Save-Help` functionality, see -[How to update help from a file share](#how-to-update-help-from-a-file-share) +new `Save-Help` functionality, see [How to update help from a file share][03] in this topic. Updatable Help also supports online access to the newest help topics and basic help for cmdlets, even when there are no help files on the computer. -PowerShell 3.0 does not come with Help files. You can use the Updatable Help -feature to install the help files for all of the commands that are included by -default in PowerShell and for all Windows modules. +PowerShell doesn't come with Help files. You can use the Updatable Help feature +to install the help files for all the commands that are included by default +in PowerShell and for all Windows modules. ## Updatable help cmdlets @@ -59,12 +58,12 @@ default in PowerShell and for all Windows modules. - `Get-Help`: Displays help topics at the command line. Gets help from the help files on the computer. Displays auto-generated help for cmdlets and functions - that do not have help files. Opens online help topics for cmdlets, functions, + that don't have help files. Opens online help topics for cmdlets, functions, scripts, and workflows in your default internet browser. ## Auto-generated help: help without help files -If you do not have the help file for a cmdlet, function, or workflow on the +If you don't have the help file for a cmdlet, function, or workflow on the computer, the `Get-Help` cmdlet displays auto-generated help and prompts you to download the help files or read them online. @@ -97,11 +96,11 @@ REMARKS ## Help files for modules The smallest unit of Updatable Help is help for a module. Module help includes -help for all of the cmdlets, functions, workflows, providers, scripts, and +help for all the cmdlets, functions, workflows, providers, scripts, and concepts in a module. You can update help for all modules that are installed on -the computer, even if they are not imported into the current session. +the computer, even if they're not imported into the current session. -You can update help for the entire module, but you cannot update help for +You can update help for the entire module, but you can't update help for individual cmdlets. To find the module that contains a particular cmdlet, use the following command @@ -136,11 +135,11 @@ Update-Help -Module Microsoft.PowerShell.Security To update help for the modules in the directory `$pshome/Modules`, you must be member of the Administrators group on the computer. -If you are not a member of the Administrators group, you cannot update help for +If you aren't a member of the Administrators group, you can't update help for these modules; but if you have internet access, you can view help online. Updating help for modules in the directory `$HOME/Documents/PowerShell/Modules` -or modules in other subdirectories of the `$HOME` directory does not require +or modules in other subdirectories of the `$HOME` directory doesn't require special permissions. The `Update-Help` and `Save-Help` cmdlets have a **UseDefaultCredentials** @@ -158,7 +157,7 @@ the SourcePath or **LiteralPath** parameters of `Update-Help` and the To download and install help files for the first time, or to update the help files on your computer, use the `Update-Help` cmdlet. -The `Update-Help` cmdlet does all of the hard work for you, including the +The `Update-Help` cmdlet does all the hard work for you, including the following tasks. - Determines which modules support Updatable Help. @@ -172,7 +171,7 @@ following tasks. - Installs the help files in the language-specific subdirectory of the module directory. -To access the new help topics, use the `Get-Help` cmdlet. You do not need to +To access the new help topics, use the `Get-Help` cmdlet. You don't need to restart PowerShell. To install or update help for all modules on the computer that supports @@ -195,16 +194,16 @@ Without parameters, `Update-Help` updates help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the PSModulePath environment variable. These are also modules that are returned by -a "Get-Help -ListAvailable" command. +a `Get-Module -ListAvailable` command. If the value of the **Module** parameter is `*` (all), `Update-Help` attempts -to update help for all installed modules, including modules that do not support +to update help for all installed modules, including modules that don't support Updatable Help. This command typically generates many errors as the cmdlet -encounters modules that do not support Updatable Help. +encounters modules that don't support Updatable Help. ## How to update help from a file share -To support computers that are not connected to the internet, or to control or +To support computers that aren't connected to the internet, or to control or streamline help updating in an enterprise, use the `Save-Help` cmdlet. The `Save-Help` cmdlet downloads help files from the internet and saves them in a filesystem directory that you specify. @@ -212,7 +211,7 @@ filesystem directory that you specify. `Save-Help` compares the help files in the specified directory to the newest help files that are available for each module. If the directory has no help files or newer help files are available for the module, the `Save-Help` cmdlet -downloads the new files from the internet. However, it does not unwrap or +downloads the new files from the internet. However, it doesn't unwrap or install the help files. To install or update the help files on a computer from help files that were @@ -235,24 +234,27 @@ Update-Help -SourcePath \\Server\Share ``` The following examples show the use of `Save-Help` to save help for modules -that are not installed on the local computer. In this example, the -administrator runs `Save-Help` to save the help for the DhcpServer module from -an internet-connected client computer, without installing the DhcpServer module -or DHCP Server role on the local computer. +that aren't installed on the local computer. In this example, the administrator +runs `Save-Help` to save the help for the DhcpServer module from an +internet-connected client computer, without installing the DhcpServer module or +DHCP Server role on the local computer. Option 1: Run `Invoke-Command` to get the **PSModuleInfo** object for the remote module, save it in a variable, `$m`, and then run `Save-Help` on the **PSModuleInfo** object by specifying the variable `$m` as the module name. ```powershell -$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock -{ Get-Module -Name DhcpServer -ListAvailable } +$invokeCommandSplat = @{ + ComputerName = 'RemoteServer' + ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable } +} +$m = Invoke-Command @invokeCommandSplat Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 2: Open a PSSession targeted at the computer that is running the DHCP +Option 2: Open a PSSession targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -261,9 +263,9 @@ $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 3: Open a CIM session, targeted at the computer that is running the DHCP +Option 3: Open a CIM session, targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -273,14 +275,14 @@ Save-Help -Module $m -DestinationPath C:\SavedHelp ``` In the following example, the administrator installs help for the DHCP Server -module on a computer that does not have network access. +module on a computer that doesn't have network access. First, run `Export-Clixml` to export the **PSModuleInfo** object to a shared folder or to removable media. ```powershell $m = Get-Module -Name DhcpServer -ListAvailable -Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m ``` Next, transport the removable media to a computer that has internet access, and @@ -288,57 +290,55 @@ then import the **PSModuleInfo** object with `Import-Clixml`. Run `Save-Help` to save the Help for the imported DhcpServer module **PSModuleInfo** object. ```powershell -$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath E:\UsbFlashDrive\SavedHelp +$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml +Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp ``` -Finally, transport the removable media back to the computer that does not have +Finally, transport the removable media back to the computer that doesn't have network access, and then install the help by running `Update-Help`. ```powershell -Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp ``` Without parameters, `Save-Help` downloads help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the -`$env:PSModulePath` environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules that are -returned by running a `Get-Help -ListAvailable` command. +`$env:PSModulePath` environment variable, on either the local computer or on a +remote computer for which you want to save help. These are also modules that +are returned by running a `Get-Help -ListAvailable` command. ## How to update help files in different languages By default, the `Update-Help` and `Save-Help` cmdlets download help in the UI -culture and language that is set for Windows on the local computer. If help -files for the specified modules are not available in the local UI culture, +culture and language that's set for Windows on the local computer. If help +files for the specified modules aren't available in the local UI culture, `Update-Help` and `Save-Help` use the Windows language fallback rules to find the best supported language. However, you can use the **UICulture** parameters of the `Update-Help` and `Save-Help` cmdlets to download and install help files in any UI cultures in -which they are available. +which they're available. For example, to save the newest help files for all modules on the session in -Japanese (Ja-jp) and French (fr-FR), type: +Japanese (ja-Jp) and French (fr-FR), type: ```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr ``` -If help files for the modules are not available in the languages that you +If help files for the modules aren't available in the languages that you specified, the `Update-Help` and `Save-Help` cmdlets return an error message that lists the languages in which help for each module is available so you can choose the alternative that best meets your needs. > [!NOTE] -> Currently, Updateable Help content is only published in English (en-US). On -> some non-Windows systems you must use the **UICulture** parameter to -> explicitly request the `en-US` content. +> Currently, Updateable Help content is only published in English (en-US). ## How to use online help -If you cannot or choose not to update the help files on your local computer, -you can still get the newest help files online. +If you can't or choose not to update the help files on your local computer, you +can still get the newest help files online. To open the online help topic for any cmdlet or function, use the **Online** parameter of the `Get-Help` cmdlet. @@ -353,13 +353,13 @@ Get-Help Get-Job -Online To get online help for a script, use the **Online** parameter and the full path to the script. -The **Online** parameter does not work with About topics. To see the about +The **Online** parameter doesn't work with About topics. To see the about topics for PowerShell, including help topics about the PowerShell language, see -[PowerShell About Topics](about.md). +[PowerShell About Topics][05]. ## How to minimize or prevent internet downloads -To minimize internet downloads and provide Updatable Help to users who are not +To minimize internet downloads and provide Updatable Help to users who aren't connected to the internet, use the `Save-Help` cmdlet. Download help from the internet and save it to a network share. Then, create a Group Policy setting or scheduled job that runs an `Update-Help` command on all computers. Set the @@ -373,7 +373,7 @@ Policy setting. This Group Policy setting implicitly adds the **SourcePath** parameter, with the filesystem location that you specify, to every `Update-Help` command on every affected computer. Users can use the **SourcePath** parameter explicitly -to specify a different filesystem location, but they cannot exclude the +to specify a different filesystem location, but they can't exclude the **SourcePath** parameter and download help from the internet. > [!NOTE] @@ -383,47 +383,56 @@ to specify a different filesystem location, but they cannot exclude the > policy setting under **User Configuration** is ignored. For more information, see -[about_Group_Policy_Settings](about_Group_Policy_Settings.md). +[about_Group_Policy_Settings][04]. ## How to update help for non-standard modules -To update or save help for a module that is not returned by the +To update or save help for a module that's not returned by the **ListAvailable** parameter of the `Get-Module` cmdlet, import the module into the current session before running an `Update-Help` or `Save-Help` command. On a remote computer, before running the `Save-Help` command, import the module -into the current Session, or `Invoke-Command` script block, that is connected -to the remote computer. +into the current Session, or `Invoke-Command` script block, that's connected to +the remote computer. When the module is in the current session, run the `Update-Help` or `Save-Help` cmdlets without parameters, or use the **Module** parameter to specify the module name. The **Module** parameters of the `Update-Help` and `Save-Help` cmdlets accept -only a module name. They do not accept the path to a module file. +only a module name. They don't accept the path to a module file. -Use this technique to update or save help for any module that is not returned -by the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module -that is installed in a location that is not listed in the `$env:PSModulePath` -environment variable, or a module that is not well-formed (the module directory -does not contain at least one file whose basename is the same as the directory +Use this technique to update or save help for any module that's not returned by +the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module +that's installed in a location that's not listed in the `$env:PSModulePath` +environment variable, or a module that's not well-formed (the module directory +doesn't contain at least one file whose basename is the same as the directory name). ## How to support updatable help If you author a module, you can support online help and Updatable Help for your -modules. For more information, see -[Supporting Updatable Help](/powershell/scripting/developer/help/supporting-updatable-help) -and [Supporting Online Help](/powershell/scripting/developer/module/supporting-online-help). +modules. For more information, see [Supporting Updatable Help][01] and +[Supporting Online Help][02]. Updatable help not available for PowerShell snap-ins or comment-based help. ## Remarks -The `Update-Help` and `Save-Help` cmdlets are not supported on Windows +The `Update-Help` and `Save-Help` cmdlets aren't supported on Windows Preinstallation Environment (Windows PE). ## See also -- [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) -- [Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) -- [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) +- [Get-Help][06] +- [Save-Help][07] +- [Update-Help][08] + + +[01]: /powershell/scripting/developer/help/supporting-updatable-help +[02]: /powershell/scripting/developer/module/supporting-online-help +[03]: #how-to-update-help-from-a-file-share +[04]: about_Group_Policy_Settings.md +[05]: about.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 2946d0f0d984..5cccd645d0a0 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,7 +1,7 @@ --- description: Describes the updatable help system in PowerShell. Locale: en-US -ms.date: 08/04/2020 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_updatable_help?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Updatable Help @@ -22,31 +22,30 @@ can read them at the command line. It makes it easy to download and install help files and to update them whenever newer help files become available. To provide updated help for multiple computers in an enterprise and for -computers that do not have access to the internet, Updatable Help lets you +computers that don't have access to the internet, Updatable Help lets you download help files to a filesystem directory or file share, and then install the help files from the file share. In PowerShell 4.0, the **HelpInfoUri** property is preserved over Windows PowerShell remoting, which allows `Save-Help` to work for modules that are -installed on a remote computer, but are not necessarily installed on the local +installed on a remote computer, but aren't necessarily installed on the local computer. You can save a **PSModuleInfo** object to disk or removable media -(such as a USB drive) by running `Export-Clixml` on a computer that does not +(such as a USB drive) by running `Export-Clixml` on a computer that doesn't have internet access, importing the **PSModuleInfo** object on a computer that does have internet access, and then running `Save-Help` on the **PSModuleInfo** object. The saved help can be copied to the remote, disconnected computer by using removable media, and then installed by running `Update-Help`. These improvements in `Save-Help` functionality let you install help on computers that are without any kind of network access. For an example of how to use the -new `Save-Help` functionality, see -[How to update help from a file share](#how-to-update-help-from-a-file-share) +new `Save-Help` functionality, see [How to update help from a file share][03] in this topic. Updatable Help also supports online access to the newest help topics and basic help for cmdlets, even when there are no help files on the computer. -PowerShell 3.0 does not come with Help files. You can use the Updatable Help -feature to install the help files for all of the commands that are included by -default in PowerShell and for all Windows modules. +PowerShell doesn't come with Help files. You can use the Updatable Help feature +to install the help files for all the commands that are included by default +in PowerShell and for all Windows modules. ## Updatable help cmdlets @@ -59,12 +58,12 @@ default in PowerShell and for all Windows modules. - `Get-Help`: Displays help topics at the command line. Gets help from the help files on the computer. Displays auto-generated help for cmdlets and functions - that do not have help files. Opens online help topics for cmdlets, functions, + that don't have help files. Opens online help topics for cmdlets, functions, scripts, and workflows in your default internet browser. ## Auto-generated help: help without help files -If you do not have the help file for a cmdlet, function, or workflow on the +If you don't have the help file for a cmdlet, function, or workflow on the computer, the `Get-Help` cmdlet displays auto-generated help and prompts you to download the help files or read them online. @@ -97,11 +96,11 @@ REMARKS ## Help files for modules The smallest unit of Updatable Help is help for a module. Module help includes -help for all of the cmdlets, functions, workflows, providers, scripts, and +help for all the cmdlets, functions, workflows, providers, scripts, and concepts in a module. You can update help for all modules that are installed on -the computer, even if they are not imported into the current session. +the computer, even if they're not imported into the current session. -You can update help for the entire module, but you cannot update help for +You can update help for the entire module, but you can't update help for individual cmdlets. To find the module that contains a particular cmdlet, use the following command @@ -136,11 +135,11 @@ Update-Help -Module Microsoft.PowerShell.Security To update help for the modules in the directory `$pshome/Modules`, you must be member of the Administrators group on the computer. -If you are not a member of the Administrators group, you cannot update help for +If you aren't a member of the Administrators group, you can't update help for these modules; but if you have internet access, you can view help online. Updating help for modules in the directory `$HOME/Documents/PowerShell/Modules` -or modules in other subdirectories of the `$HOME` directory does not require +or modules in other subdirectories of the `$HOME` directory doesn't require special permissions. The `Update-Help` and `Save-Help` cmdlets have a **UseDefaultCredentials** @@ -158,7 +157,7 @@ the SourcePath or **LiteralPath** parameters of `Update-Help` and the To download and install help files for the first time, or to update the help files on your computer, use the `Update-Help` cmdlet. -The `Update-Help` cmdlet does all of the hard work for you, including the +The `Update-Help` cmdlet does all the hard work for you, including the following tasks. - Determines which modules support Updatable Help. @@ -172,7 +171,7 @@ following tasks. - Installs the help files in the language-specific subdirectory of the module directory. -To access the new help topics, use the `Get-Help` cmdlet. You do not need to +To access the new help topics, use the `Get-Help` cmdlet. You don't need to restart PowerShell. To install or update help for all modules on the computer that supports @@ -195,16 +194,16 @@ Without parameters, `Update-Help` updates help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the PSModulePath environment variable. These are also modules that are returned by -a "Get-Help -ListAvailable" command. +a `Get-Module -ListAvailable` command. If the value of the **Module** parameter is `*` (all), `Update-Help` attempts -to update help for all installed modules, including modules that do not support +to update help for all installed modules, including modules that don't support Updatable Help. This command typically generates many errors as the cmdlet -encounters modules that do not support Updatable Help. +encounters modules that don't support Updatable Help. ## How to update help from a file share -To support computers that are not connected to the internet, or to control or +To support computers that aren't connected to the internet, or to control or streamline help updating in an enterprise, use the `Save-Help` cmdlet. The `Save-Help` cmdlet downloads help files from the internet and saves them in a filesystem directory that you specify. @@ -212,7 +211,7 @@ filesystem directory that you specify. `Save-Help` compares the help files in the specified directory to the newest help files that are available for each module. If the directory has no help files or newer help files are available for the module, the `Save-Help` cmdlet -downloads the new files from the internet. However, it does not unwrap or +downloads the new files from the internet. However, it doesn't unwrap or install the help files. To install or update the help files on a computer from help files that were @@ -235,24 +234,27 @@ Update-Help -SourcePath \\Server\Share ``` The following examples show the use of `Save-Help` to save help for modules -that are not installed on the local computer. In this example, the -administrator runs `Save-Help` to save the help for the DhcpServer module from -an internet-connected client computer, without installing the DhcpServer module -or DHCP Server role on the local computer. +that aren't installed on the local computer. In this example, the administrator +runs `Save-Help` to save the help for the DhcpServer module from an +internet-connected client computer, without installing the DhcpServer module or +DHCP Server role on the local computer. Option 1: Run `Invoke-Command` to get the **PSModuleInfo** object for the remote module, save it in a variable, `$m`, and then run `Save-Help` on the **PSModuleInfo** object by specifying the variable `$m` as the module name. ```powershell -$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock -{ Get-Module -Name DhcpServer -ListAvailable } +$invokeCommandSplat = @{ + ComputerName = 'RemoteServer' + ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable } +} +$m = Invoke-Command @invokeCommandSplat Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 2: Open a PSSession targeted at the computer that is running the DHCP +Option 2: Open a PSSession targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -261,9 +263,9 @@ $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 3: Open a CIM session, targeted at the computer that is running the DHCP +Option 3: Open a CIM session, targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -273,14 +275,14 @@ Save-Help -Module $m -DestinationPath C:\SavedHelp ``` In the following example, the administrator installs help for the DHCP Server -module on a computer that does not have network access. +module on a computer that doesn't have network access. First, run `Export-Clixml` to export the **PSModuleInfo** object to a shared folder or to removable media. ```powershell $m = Get-Module -Name DhcpServer -ListAvailable -Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m ``` Next, transport the removable media to a computer that has internet access, and @@ -288,57 +290,55 @@ then import the **PSModuleInfo** object with `Import-Clixml`. Run `Save-Help` to save the Help for the imported DhcpServer module **PSModuleInfo** object. ```powershell -$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath E:\UsbFlashDrive\SavedHelp +$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml +Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp ``` -Finally, transport the removable media back to the computer that does not have +Finally, transport the removable media back to the computer that doesn't have network access, and then install the help by running `Update-Help`. ```powershell -Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp ``` Without parameters, `Save-Help` downloads help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the -`$env:PSModulePath` environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules that are -returned by running a `Get-Help -ListAvailable` command. +`$env:PSModulePath` environment variable, on either the local computer or on a +remote computer for which you want to save help. These are also modules that +are returned by running a `Get-Help -ListAvailable` command. ## How to update help files in different languages By default, the `Update-Help` and `Save-Help` cmdlets download help in the UI -culture and language that is set for Windows on the local computer. If help -files for the specified modules are not available in the local UI culture, +culture and language that's set for Windows on the local computer. If help +files for the specified modules aren't available in the local UI culture, `Update-Help` and `Save-Help` use the Windows language fallback rules to find the best supported language. However, you can use the **UICulture** parameters of the `Update-Help` and `Save-Help` cmdlets to download and install help files in any UI cultures in -which they are available. +which they're available. For example, to save the newest help files for all modules on the session in -Japanese (Ja-jp) and French (fr-FR), type: +Japanese (ja-Jp) and French (fr-FR), type: ```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr ``` -If help files for the modules are not available in the languages that you +If help files for the modules aren't available in the languages that you specified, the `Update-Help` and `Save-Help` cmdlets return an error message that lists the languages in which help for each module is available so you can choose the alternative that best meets your needs. > [!NOTE] -> Currently, Updateable Help content is only published in English (en-US). On -> some non-Windows systems you must use the **UICulture** parameter to -> explicitly request the `en-US` content. +> Currently, Updateable Help content is only published in English (en-US). ## How to use online help -If you cannot or choose not to update the help files on your local computer, -you can still get the newest help files online. +If you can't or choose not to update the help files on your local computer, you +can still get the newest help files online. To open the online help topic for any cmdlet or function, use the **Online** parameter of the `Get-Help` cmdlet. @@ -353,13 +353,13 @@ Get-Help Get-Job -Online To get online help for a script, use the **Online** parameter and the full path to the script. -The **Online** parameter does not work with About topics. To see the about +The **Online** parameter doesn't work with About topics. To see the about topics for PowerShell, including help topics about the PowerShell language, see -[PowerShell About Topics](about.md). +[PowerShell About Topics][05]. ## How to minimize or prevent internet downloads -To minimize internet downloads and provide Updatable Help to users who are not +To minimize internet downloads and provide Updatable Help to users who aren't connected to the internet, use the `Save-Help` cmdlet. Download help from the internet and save it to a network share. Then, create a Group Policy setting or scheduled job that runs an `Update-Help` command on all computers. Set the @@ -373,7 +373,7 @@ Policy setting. This Group Policy setting implicitly adds the **SourcePath** parameter, with the filesystem location that you specify, to every `Update-Help` command on every affected computer. Users can use the **SourcePath** parameter explicitly -to specify a different filesystem location, but they cannot exclude the +to specify a different filesystem location, but they can't exclude the **SourcePath** parameter and download help from the internet. > [!NOTE] @@ -383,47 +383,56 @@ to specify a different filesystem location, but they cannot exclude the > policy setting under **User Configuration** is ignored. For more information, see -[about_Group_Policy_Settings](about_Group_Policy_Settings.md). +[about_Group_Policy_Settings][04]. ## How to update help for non-standard modules -To update or save help for a module that is not returned by the +To update or save help for a module that's not returned by the **ListAvailable** parameter of the `Get-Module` cmdlet, import the module into the current session before running an `Update-Help` or `Save-Help` command. On a remote computer, before running the `Save-Help` command, import the module -into the current Session, or `Invoke-Command` script block, that is connected -to the remote computer. +into the current Session, or `Invoke-Command` script block, that's connected to +the remote computer. When the module is in the current session, run the `Update-Help` or `Save-Help` cmdlets without parameters, or use the **Module** parameter to specify the module name. The **Module** parameters of the `Update-Help` and `Save-Help` cmdlets accept -only a module name. They do not accept the path to a module file. +only a module name. They don't accept the path to a module file. -Use this technique to update or save help for any module that is not returned -by the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module -that is installed in a location that is not listed in the `$env:PSModulePath` -environment variable, or a module that is not well-formed (the module directory -does not contain at least one file whose basename is the same as the directory +Use this technique to update or save help for any module that's not returned by +the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module +that's installed in a location that's not listed in the `$env:PSModulePath` +environment variable, or a module that's not well-formed (the module directory +doesn't contain at least one file whose basename is the same as the directory name). ## How to support updatable help If you author a module, you can support online help and Updatable Help for your -modules. For more information, see -[Supporting Updatable Help](/powershell/scripting/developer/help/supporting-updatable-help) -and [Supporting Online Help](/powershell/scripting/developer/module/supporting-online-help). +modules. For more information, see [Supporting Updatable Help][01] and +[Supporting Online Help][02]. Updatable help not available for PowerShell snap-ins or comment-based help. ## Remarks -The `Update-Help` and `Save-Help` cmdlets are not supported on Windows +The `Update-Help` and `Save-Help` cmdlets aren't supported on Windows Preinstallation Environment (Windows PE). ## See also -- [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) -- [Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) -- [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) +- [Get-Help][06] +- [Save-Help][07] +- [Update-Help][08] + + +[01]: /powershell/scripting/developer/help/supporting-updatable-help +[02]: /powershell/scripting/developer/module/supporting-online-help +[03]: #how-to-update-help-from-a-file-share +[04]: about_Group_Policy_Settings.md +[05]: about.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 5cf7315d1fb8..0dad1c14a15c 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,7 +1,7 @@ --- description: Describes the updatable help system in PowerShell. Locale: en-US -ms.date: 08/04/2020 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_updatable_help?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Updatable Help @@ -22,31 +22,30 @@ can read them at the command line. It makes it easy to download and install help files and to update them whenever newer help files become available. To provide updated help for multiple computers in an enterprise and for -computers that do not have access to the internet, Updatable Help lets you +computers that don't have access to the internet, Updatable Help lets you download help files to a filesystem directory or file share, and then install the help files from the file share. In PowerShell 4.0, the **HelpInfoUri** property is preserved over Windows PowerShell remoting, which allows `Save-Help` to work for modules that are -installed on a remote computer, but are not necessarily installed on the local +installed on a remote computer, but aren't necessarily installed on the local computer. You can save a **PSModuleInfo** object to disk or removable media -(such as a USB drive) by running `Export-Clixml` on a computer that does not +(such as a USB drive) by running `Export-Clixml` on a computer that doesn't have internet access, importing the **PSModuleInfo** object on a computer that does have internet access, and then running `Save-Help` on the **PSModuleInfo** object. The saved help can be copied to the remote, disconnected computer by using removable media, and then installed by running `Update-Help`. These improvements in `Save-Help` functionality let you install help on computers that are without any kind of network access. For an example of how to use the -new `Save-Help` functionality, see -[How to update help from a file share](#how-to-update-help-from-a-file-share) +new `Save-Help` functionality, see [How to update help from a file share][03] in this topic. Updatable Help also supports online access to the newest help topics and basic help for cmdlets, even when there are no help files on the computer. -PowerShell 3.0 does not come with Help files. You can use the Updatable Help -feature to install the help files for all of the commands that are included by -default in PowerShell and for all Windows modules. +PowerShell doesn't come with Help files. You can use the Updatable Help feature +to install the help files for all the commands that are included by default +in PowerShell and for all Windows modules. ## Updatable help cmdlets @@ -59,12 +58,12 @@ default in PowerShell and for all Windows modules. - `Get-Help`: Displays help topics at the command line. Gets help from the help files on the computer. Displays auto-generated help for cmdlets and functions - that do not have help files. Opens online help topics for cmdlets, functions, + that don't have help files. Opens online help topics for cmdlets, functions, scripts, and workflows in your default internet browser. ## Auto-generated help: help without help files -If you do not have the help file for a cmdlet, function, or workflow on the +If you don't have the help file for a cmdlet, function, or workflow on the computer, the `Get-Help` cmdlet displays auto-generated help and prompts you to download the help files or read them online. @@ -97,11 +96,11 @@ REMARKS ## Help files for modules The smallest unit of Updatable Help is help for a module. Module help includes -help for all of the cmdlets, functions, workflows, providers, scripts, and +help for all the cmdlets, functions, workflows, providers, scripts, and concepts in a module. You can update help for all modules that are installed on -the computer, even if they are not imported into the current session. +the computer, even if they're not imported into the current session. -You can update help for the entire module, but you cannot update help for +You can update help for the entire module, but you can't update help for individual cmdlets. To find the module that contains a particular cmdlet, use the following command @@ -136,11 +135,11 @@ Update-Help -Module Microsoft.PowerShell.Security To update help for the modules in the directory `$pshome/Modules`, you must be member of the Administrators group on the computer. -If you are not a member of the Administrators group, you cannot update help for +If you aren't a member of the Administrators group, you can't update help for these modules; but if you have internet access, you can view help online. Updating help for modules in the directory `$HOME/Documents/PowerShell/Modules` -or modules in other subdirectories of the `$HOME` directory does not require +or modules in other subdirectories of the `$HOME` directory doesn't require special permissions. The `Update-Help` and `Save-Help` cmdlets have a **UseDefaultCredentials** @@ -158,7 +157,7 @@ the SourcePath or **LiteralPath** parameters of `Update-Help` and the To download and install help files for the first time, or to update the help files on your computer, use the `Update-Help` cmdlet. -The `Update-Help` cmdlet does all of the hard work for you, including the +The `Update-Help` cmdlet does all the hard work for you, including the following tasks. - Determines which modules support Updatable Help. @@ -172,7 +171,7 @@ following tasks. - Installs the help files in the language-specific subdirectory of the module directory. -To access the new help topics, use the `Get-Help` cmdlet. You do not need to +To access the new help topics, use the `Get-Help` cmdlet. You don't need to restart PowerShell. To install or update help for all modules on the computer that supports @@ -195,16 +194,16 @@ Without parameters, `Update-Help` updates help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the PSModulePath environment variable. These are also modules that are returned by -a "Get-Help -ListAvailable" command. +a `Get-Module -ListAvailable` command. If the value of the **Module** parameter is `*` (all), `Update-Help` attempts -to update help for all installed modules, including modules that do not support +to update help for all installed modules, including modules that don't support Updatable Help. This command typically generates many errors as the cmdlet -encounters modules that do not support Updatable Help. +encounters modules that don't support Updatable Help. ## How to update help from a file share -To support computers that are not connected to the internet, or to control or +To support computers that aren't connected to the internet, or to control or streamline help updating in an enterprise, use the `Save-Help` cmdlet. The `Save-Help` cmdlet downloads help files from the internet and saves them in a filesystem directory that you specify. @@ -212,7 +211,7 @@ filesystem directory that you specify. `Save-Help` compares the help files in the specified directory to the newest help files that are available for each module. If the directory has no help files or newer help files are available for the module, the `Save-Help` cmdlet -downloads the new files from the internet. However, it does not unwrap or +downloads the new files from the internet. However, it doesn't unwrap or install the help files. To install or update the help files on a computer from help files that were @@ -235,24 +234,27 @@ Update-Help -SourcePath \\Server\Share ``` The following examples show the use of `Save-Help` to save help for modules -that are not installed on the local computer. In this example, the -administrator runs `Save-Help` to save the help for the DhcpServer module from -an internet-connected client computer, without installing the DhcpServer module -or DHCP Server role on the local computer. +that aren't installed on the local computer. In this example, the administrator +runs `Save-Help` to save the help for the DhcpServer module from an +internet-connected client computer, without installing the DhcpServer module or +DHCP Server role on the local computer. Option 1: Run `Invoke-Command` to get the **PSModuleInfo** object for the remote module, save it in a variable, `$m`, and then run `Save-Help` on the **PSModuleInfo** object by specifying the variable `$m` as the module name. ```powershell -$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock -{ Get-Module -Name DhcpServer -ListAvailable } +$invokeCommandSplat = @{ + ComputerName = 'RemoteServer' + ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable } +} +$m = Invoke-Command @invokeCommandSplat Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 2: Open a PSSession targeted at the computer that is running the DHCP +Option 2: Open a PSSession targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -261,9 +263,9 @@ $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp ``` -Option 3: Open a CIM session, targeted at the computer that is running the DHCP +Option 3: Open a CIM session, targeted at the computer that's running the DHCP Server module, to get the **PSModuleInfo** object for the module, save it in a -variable `$m`, and then run `Save-Help` on the object that is saved in the `$m` +variable `$m`, and then run `Save-Help` on the object that's saved in the `$m` variable. ```powershell @@ -273,14 +275,14 @@ Save-Help -Module $m -DestinationPath C:\SavedHelp ``` In the following example, the administrator installs help for the DHCP Server -module on a computer that does not have network access. +module on a computer that doesn't have network access. First, run `Export-Clixml` to export the **PSModuleInfo** object to a shared folder or to removable media. ```powershell $m = Get-Module -Name DhcpServer -ListAvailable -Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m ``` Next, transport the removable media to a computer that has internet access, and @@ -288,57 +290,55 @@ then import the **PSModuleInfo** object with `Import-Clixml`. Run `Save-Help` to save the Help for the imported DhcpServer module **PSModuleInfo** object. ```powershell -$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath E:\UsbFlashDrive\SavedHelp +$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml +Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp ``` -Finally, transport the removable media back to the computer that does not have +Finally, transport the removable media back to the computer that doesn't have network access, and then install the help by running `Update-Help`. ```powershell -Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp ``` Without parameters, `Save-Help` downloads help for all modules in the session and for all installed modules that support Updatable Help. To be included, modules must be installed in directories that are listed in the value of the -`$env:PSModulePath` environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules that are -returned by running a `Get-Help -ListAvailable` command. +`$env:PSModulePath` environment variable, on either the local computer or on a +remote computer for which you want to save help. These are also modules that +are returned by running a `Get-Help -ListAvailable` command. ## How to update help files in different languages By default, the `Update-Help` and `Save-Help` cmdlets download help in the UI -culture and language that is set for Windows on the local computer. If help -files for the specified modules are not available in the local UI culture, +culture and language that's set for Windows on the local computer. If help +files for the specified modules aren't available in the local UI culture, `Update-Help` and `Save-Help` use the Windows language fallback rules to find the best supported language. However, you can use the **UICulture** parameters of the `Update-Help` and `Save-Help` cmdlets to download and install help files in any UI cultures in -which they are available. +which they're available. For example, to save the newest help files for all modules on the session in -Japanese (Ja-jp) and French (fr-FR), type: +Japanese (ja-Jp) and French (fr-FR), type: ```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr ``` -If help files for the modules are not available in the languages that you +If help files for the modules aren't available in the languages that you specified, the `Update-Help` and `Save-Help` cmdlets return an error message that lists the languages in which help for each module is available so you can choose the alternative that best meets your needs. > [!NOTE] -> Currently, Updateable Help content is only published in English (en-US). On -> some non-Windows systems you must use the **UICulture** parameter to -> explicitly request the `en-US` content. +> Currently, Updateable Help content is only published in English (en-US). ## How to use online help -If you cannot or choose not to update the help files on your local computer, -you can still get the newest help files online. +If you can't or choose not to update the help files on your local computer, you +can still get the newest help files online. To open the online help topic for any cmdlet or function, use the **Online** parameter of the `Get-Help` cmdlet. @@ -353,13 +353,13 @@ Get-Help Get-Job -Online To get online help for a script, use the **Online** parameter and the full path to the script. -The **Online** parameter does not work with About topics. To see the about +The **Online** parameter doesn't work with About topics. To see the about topics for PowerShell, including help topics about the PowerShell language, see -[PowerShell About Topics](about.md). +[PowerShell About Topics][05]. ## How to minimize or prevent internet downloads -To minimize internet downloads and provide Updatable Help to users who are not +To minimize internet downloads and provide Updatable Help to users who aren't connected to the internet, use the `Save-Help` cmdlet. Download help from the internet and save it to a network share. Then, create a Group Policy setting or scheduled job that runs an `Update-Help` command on all computers. Set the @@ -373,7 +373,7 @@ Policy setting. This Group Policy setting implicitly adds the **SourcePath** parameter, with the filesystem location that you specify, to every `Update-Help` command on every affected computer. Users can use the **SourcePath** parameter explicitly -to specify a different filesystem location, but they cannot exclude the +to specify a different filesystem location, but they can't exclude the **SourcePath** parameter and download help from the internet. > [!NOTE] @@ -383,47 +383,56 @@ to specify a different filesystem location, but they cannot exclude the > policy setting under **User Configuration** is ignored. For more information, see -[about_Group_Policy_Settings](about_Group_Policy_Settings.md). +[about_Group_Policy_Settings][04]. ## How to update help for non-standard modules -To update or save help for a module that is not returned by the +To update or save help for a module that's not returned by the **ListAvailable** parameter of the `Get-Module` cmdlet, import the module into the current session before running an `Update-Help` or `Save-Help` command. On a remote computer, before running the `Save-Help` command, import the module -into the current Session, or `Invoke-Command` script block, that is connected -to the remote computer. +into the current Session, or `Invoke-Command` script block, that's connected to +the remote computer. When the module is in the current session, run the `Update-Help` or `Save-Help` cmdlets without parameters, or use the **Module** parameter to specify the module name. The **Module** parameters of the `Update-Help` and `Save-Help` cmdlets accept -only a module name. They do not accept the path to a module file. +only a module name. They don't accept the path to a module file. -Use this technique to update or save help for any module that is not returned -by the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module -that is installed in a location that is not listed in the `$env:PSModulePath` -environment variable, or a module that is not well-formed (the module directory -does not contain at least one file whose basename is the same as the directory +Use this technique to update or save help for any module that's not returned by +the **ListAvailable** parameter of the `Get-Module` cmdlet, such as a module +that's installed in a location that's not listed in the `$env:PSModulePath` +environment variable, or a module that's not well-formed (the module directory +doesn't contain at least one file whose basename is the same as the directory name). ## How to support updatable help If you author a module, you can support online help and Updatable Help for your -modules. For more information, see -[Supporting Updatable Help](/powershell/scripting/developer/help/supporting-updatable-help) -and [Supporting Online Help](/powershell/scripting/developer/module/supporting-online-help). +modules. For more information, see [Supporting Updatable Help][01] and +[Supporting Online Help][02]. Updatable help not available for PowerShell snap-ins or comment-based help. ## Remarks -The `Update-Help` and `Save-Help` cmdlets are not supported on Windows +The `Update-Help` and `Save-Help` cmdlets aren't supported on Windows Preinstallation Environment (Windows PE). ## See also -- [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) -- [Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) -- [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) +- [Get-Help][06] +- [Save-Help][07] +- [Update-Help][08] + + +[01]: /powershell/scripting/developer/help/supporting-updatable-help +[02]: /powershell/scripting/developer/module/supporting-online-help +[03]: #how-to-update-help-from-a-file-share +[04]: about_Group_Policy_Settings.md +[05]: about.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help