Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes #10553 - Fix incorrect cmdlet example #10555

Merged
merged 1 commit into from
Oct 20, 2023
Merged

Fixes #10553 - Fix incorrect cmdlet example #10555

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 83 additions & 72 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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**
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -203,24 +202,24 @@ 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.

`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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -281,59 +283,59 @@ 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
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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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]
Expand All @@ -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]

<!-- link references -->
[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
Loading