about_Updatable_Help

Статья
05/09/2024

Краткое описание

Описывает обновляемую справочную систему в PowerShell.

Подробное описание

PowerShell предоставляет несколько различных способов доступа к самым актуальным разделам справки по командлетам и основным понятиям PowerShell.

Обновляемая справочная система, представленная в PowerShell 3.0, предназначена для обеспечения того, чтобы на локальном компьютере всегда были самые новые разделы справки, чтобы их можно было прочитать в командной строке. Это позволяет легко скачивать и устанавливать файлы справки, а также обновлять их всякий раз, когда становятся доступными новые файлы справки.

Чтобы предоставить обновленную справку для нескольких компьютеров в организации и компьютеров, у которых нет доступа к Интернету, обновляемая справка позволяет скачивать файлы справки в каталог файловой системы или общую папку, а затем устанавливать файлы справки из общей папки.

В PowerShell 4.0 свойство HelpInfoUri сохраняется в Windows PowerShell удаленного взаимодействия, что позволяет Save-Help работать с модулями, установленными на удаленном компьютере, но не обязательно установленными на локальном компьютере. Вы можете сохранить объект PSModuleInfo на диск или съемный носитель (например, USB-накопитель), запустив Export-Clixml на компьютере без доступа к Интернету, импортировав объект PSModuleInfo на компьютере с доступом к Интернету, а затем запустив Save-Help на объекте PSModuleInfo . Сохраненную справку можно скопировать на удаленный отключенный компьютер с помощью съемного носителя, а затем установить, запустив Update-Help. Эти улучшения функциональных Save-Help возможностей позволяют устанавливать справку на компьютерах без какого-либо сетевого доступа. Пример использования новых Save-Help функций см. в разделе Обновление справки из общей папки этой статьи.

Обновляемая справка также поддерживает доступ по сети к новейшим разделам справки и базовой справке для командлетов, даже если на компьютере нет файлов справки.

PowerShell не содержит файлы справки. С помощью обновляемой справки можно установить файлы справки для всех команд, включенных по умолчанию в PowerShell, и для всех модулей Windows.

Обновляемые командлеты справки

Update-Help: скачивает новейшие файлы справки из Интернета или общей папки и устанавливает их на локальный компьютер.
Save-Help: скачивает новейшие файлы справки из Интернета и сохраняет их в каталоге файловой системы или в общей папке. Чтобы установить файлы справки на компьютерах, используйте .Update-Help
Get-Help: в командной строке отображаются разделы справки. Получает справку из файлов справки на компьютере. Отображает автоматически созданную справку для командлетов и функций, у которых нет файлов справки. Открывает разделы справки в Интернете по командлетам, функциям, сценариям и рабочим процессам в браузере по умолчанию.

Автоматически созданная справка: справка без файлов справки

Если у вас нет файла справки для командлета, функции или рабочего процесса на компьютере, Get-Help командлет отображает автоматически созданную справку и предлагает скачать файлы справки или прочитать их в Интернете.

Автоматически создаваемая справка включает синтаксис и псевдонимы, а также замечания, объясняющие, как использовать обновляемые командлеты справки и получить доступ к разделам справки в Интернете.

Например, следующая команда получает базовую справку по командлету Get-Culture . В выходных данных отображается Get-Help отображение, если на компьютере нет файлов справки.

Get-Help Get-Culture

NAME
    Get-Culture

SYNTAX
    Get-Culture [<CommonParameters>]

ALIASES
    None

REMARKS
    To get the latest Help content including descriptions and examples
    type: Update-Help.

Файлы справки для модулей

Самая маленькая единица обновляемой справки — это справка по модулю. Справка по модулю содержит справку по всем командлетам, функциям, рабочим процессам, поставщикам, скриптам и понятиям в модуле. Вы можете обновить справку для всех модулей, установленных на компьютере, даже если они не импортированы в текущий сеанс.

Вы можете обновить справку для всего модуля, но не можете обновить справку для отдельных командлетов.

Чтобы найти модуль, содержащий определенный командлет, используйте следующий формат команды:

(Get-Command <cmdlet-name>).ModuleName

Например, чтобы найти модуль, содержащий командлет, введите Set-ExecutionPolicy :

(Get-Command Set-ExecutionPolicy).ModuleName

Чтобы обновить справку для определенного модуля, введите:

Update-Help -Module <ModuleName>

Например, чтобы обновить справку для модуля, содержащего командлет Set-ExecutionPolicy, введите:

Update-Help -Module Microsoft.PowerShell.Security

Разрешения для обновляемой справки

Чтобы обновить справку по модулям в каталоге $pshome/Modules, необходимо быть членом группы Администраторы на компьютере.

Если вы не входите в группу "Администраторы", вы не сможете обновить справку по этим модулям. Но если у вас есть доступ к Интернету, вы можете просмотреть справку в Интернете.

Обновление справки для модулей в каталоге $HOME/Documents/PowerShell/Modules или модулей в других подкаталогах $HOME каталога не требует специальных разрешений.

Командлеты Update-Help и Save-Help имеют параметр UseDefaultCredentials , предоставляющий явные учетные данные текущего пользователя. Этот параметр предназначен для доступа к защищенным расположениям в Интернете.

Командлеты Update-Help и Save-Help также имеют параметр Credential , который позволяет выполнить команду на удаленном компьютере и получить доступ к общей папке на третьем компьютере. Параметр Credential действителен только при использовании параметров SourcePath или LiteralPath для Update-Help , а также параметров DestinationPath или LiteralPath в Save-Help.

Установка и обновление файлов справки

Чтобы скачать и установить файлы справки в первый раз или обновить файлы справки на компьютере, используйте Update-Help командлет .

Командлет Update-Help выполняет всю тяжелую работу, включая следующие задачи.

Определяет, какие модули поддерживают обновляемую справку.
Находит расположение в Интернете, где каждый модуль хранит свои обновляемые файлы справки.
Сравнивает файлы справки для каждого модуля на компьютере с новейшими файлами справки, доступными для каждого модуля.
Скачивает новые файлы из Интернета.
Распаковывает пакет файлов справки.
Проверяет, являются ли файлы допустимыми файлами справки.
Устанавливает файлы справки в подкаталог для определенного языка каталога модуля.

Чтобы получить доступ к новым разделам справки Get-Help , используйте командлет . Вам не нужно перезапускать PowerShell.

Чтобы установить или обновить справку для всех модулей на компьютере, поддерживающем обновляемую справку, введите:

Update-Help

Чтобы обновить справку для определенных модулей, добавьте параметр Module для Update-Help. В имени модуля разрешены подстановочные знаки.

Например, чтобы обновить справку для модуля ServerManager, введите:

Update-Help -Module ServerManager

Без параметров Update-Help обновляет справку для всех модулей в сеансе и для всех установленных модулей, поддерживающих обновляемую справку. Для включения модулей необходимо установить в каталоги, перечисленные в значении переменной среды PSModulePath. Это также модули, возвращаемые командой Get-Module -ListAvailable .

Если параметр Module имеет значение (all), Update-Help пытается * обновить справку для всех установленных модулей, включая модули, которые не поддерживают обновляемую справку. Эта команда обычно вызывает множество ошибок, так как командлет сталкивается с модулями, которые не поддерживают обновляемую справку.

Для поддержки компьютеров, которые не подключены к Интернету, а также для управления или упрощения обновления справки на предприятии, используйте Save-Help командлет . Командлет Save-Help скачивает файлы справки из Интернета и сохраняет их в указанном каталоге файловой системы.

Save-Help Сравнивает файлы справки в указанном каталоге с новейшими файлами справки, доступными для каждого модуля. Если в каталоге нет файлов справки или для модуля доступны новые файлы справки Save-Help , командлет скачивает новые файлы из Интернета. Однако файлы справки не распаковываются и не устанавливаются.

Чтобы установить или обновить файлы справки на компьютере из файлов справки, сохраненных в каталоге файловой системы, используйте параметр SourcePath командлета Update-Help . Командлет Update-Help определяет новейшие файлы справки, распаковывает и проверяет их, а также устанавливает их в подкаталоги для конкретного языка каталогов модулей.

Например, чтобы сохранить справку по всем установленным модулям в каталоге, введите \\Server\Share :

Save-Help -DestinationPath \\Server\Share

Затем, чтобы обновить справку из каталога, введите \\Server\Share :

Update-Help -SourcePath \\Server\Share

В следующих примерах показано использование для сохранения справки Save-Help для модулей, которые не установлены на локальном компьютере. В этом примере администратор запускает Save-Help , чтобы сохранить справку для модуля DhcpServer с клиентского компьютера, подключенного к Интернету, без установки модуля DhcpServer или роли DHCP-сервера на локальном компьютере.

Вариант 1. Выполните команду Invoke-Command , чтобы получить объект PSModuleInfo для удаленного модуля, сохраните его в переменной $m, а затем выполните в Save-Helpобъекте PSModuleInfo , указав переменную $m в качестве имени модуля.

$invokeCommandSplat = @{
    ComputerName = 'RemoteServer'
    ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp

Вариант 2. Откройте PSSession, предназначенный для компьютера, на котором выполняется модуль DHCP-сервера, чтобы получить объект PSModuleInfo для модуля, сохранить его в переменной $m, а затем выполнить на Save-Help объекте, сохраненном в переменной $m .

$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

Вариант 3. Откройте сеанс CIM, предназначенный для компьютера, на котором выполняется модуль DHCP-сервера, чтобы получить объект PSModuleInfo для модуля, сохранить его в переменной $m, а затем выполнить на Save-Help объекте, сохраненном в переменной $m .

$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

В следующем примере администратор устанавливает справку для модуля DHCP-сервера на компьютере, который не имеет доступа к сети.

Сначала выполните команду Export-Clixml , чтобы экспортировать объект PSModuleInfo в общую папку или на съемный носитель.

$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m

Затем переведите съемный носитель на компьютер с доступом к Интернету, а затем импортируйте объект PSModuleInfo с Import-Clixmlпомощью . Запустите Save-Help , чтобы сохранить справку для объекта PSModuleInfo импортированного модуля DhcpServer.

$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp

Наконец, переведите съемный носитель обратно на компьютер, который не имеет доступа к сети, а затем установите справку, запустив Update-Help.

Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp

Без параметров Save-Help скачивает справку для всех модулей в сеансе и для всех установленных модулей, поддерживающих обновляемую справку. Для включения модули должны быть установлены в каталогах, перечисленных в значении переменной $env:PSModulePath среды, на локальном компьютере или на удаленном компьютере, для которого требуется сохранить справку. Это также модули, возвращаемые при выполнении Get-Help -ListAvailable команды .

Обновление файлов справки на разных языках

По умолчанию Update-Help командлеты и Save-Help загружают справку по языку и региональным параметрам пользовательского интерфейса, заданным для Windows на локальном компьютере. Если файлы справки для указанных модулей недоступны в локальном языке и региональных параметрах пользовательского интерфейса, Update-Help и Save-Help используйте резервные правила языков Windows, чтобы найти наиболее подходящий поддерживаемый язык.

Однако вы можете использовать параметры Update-HelpUICulture командлетов и Save-Help для скачивания и установки файлов справки в любых языках пользовательского интерфейса, в которых они доступны.

Например, чтобы сохранить последние файлы справки для всех модулей в сеансе на японском (ja-Jp) и французском языках (fr-FR), введите:

Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr

Если файлы справки для модулей недоступны на указанных вами языках, Update-Help командлеты и Save-Help возвращают сообщение об ошибке со списком языков, на которых доступна справка по каждому модулю, чтобы вы могли выбрать вариант, который лучше всего соответствует вашим потребностям.

Примечание

В настоящее время содержимое обновляемой справки публикуется только на английском языке (en-US).

Использование справки в Интернете

Если вы не можете или не хотите обновлять файлы справки на локальном компьютере, вы по-прежнему можете получить последние файлы справки в Интернете.

Чтобы открыть раздел справки в Интернете для любого командлета или функции, используйте параметр Online командлета Get-Help .

Например, следующая команда открывает раздел справки в Интернете для командлета Get-Job в браузере по умолчанию:

Get-Help Get-Job -Online

Чтобы получить справку по скрипту в Интернете, используйте параметр Online и полный путь к скрипту.

Параметр Online не работает с разделами о программе. Дополнительные сведения о powerShell, в том числе справочные статьи о языке PowerShell, см. в статье PowerShell About Topics.

Сведения о том, как свести к минимуму или предотвратить скачивание из Интернета

Чтобы свести к минимуму скачиваемые данные из Интернета и предоставить обновляемую справку пользователям, которые не подключены к Интернету Save-Help , используйте командлет . Скачайте справку из Интернета и сохраните ее в сетевой папке. Затем создайте параметр групповая политика или запланированное задание, которое выполняет Update-Help команду на всех компьютерах. Задайте для параметра SourcePath командлета Update-Help значение сетевой общей папки.

Чтобы запретить пользователям с доступом к Интернету скачивать обновляемую справку из Интернета, используйте параметр Задать исходный путь по умолчанию для групповая политика Update-Help.

Этот параметр групповая политика неявно добавляет параметр SourcePath с указанным расположением файловой системы в каждую Update-Help команду на каждом затронутом компьютере. Пользователи могут явно использовать параметр SourcePath , чтобы указать другое расположение файловой системы, но они не могут исключить параметр SourcePath и скачать справку из Интернета.

Примечание

Параметр групповой политики Set the default source path for Update-Help (Задать исходный путь по умолчанию для Update-Help ) отображается в разделе Конфигурация компьютера и Конфигурация пользователя. Однако действует только параметр политики в разделе Конфигурация компьютера . Параметр политики в разделе Конфигурация пользователя игнорируется.

Дополнительные сведения см. в статье О параметрах групповой политики.

Обновление справки для нестандартных модулей

Чтобы обновить или сохранить справку для модуля, который не возвращается параметром ListAvailable командлета Get-Module , импортируйте модуль в текущий сеанс перед выполнением Update-Help команды или Save-Help . На удаленном компьютере перед выполнением Save-Help команды импортируйте модуль в текущий сеанс или Invoke-Command блок скрипта, подключенный к удаленному компьютеру.

Когда модуль находится в текущем сеансе, выполните Update-Help командлеты или Save-Help без параметров или используйте параметр Module , чтобы указать имя модуля.

Параметры Update-Helpмодуля командлетов и Save-Help принимают только имя модуля. Они не принимают путь к файлу модуля.

Используйте этот метод для обновления или сохранения справки для любого модуля, который не возвращается параметром ListAvailable командлета, например для модуля, установленного Get-Module в расположении, которое не указано в $env:PSModulePath переменной среды, или модуля, который не имеет правильного формата (каталог модуля не содержит по крайней мере один файл, базовое имя которого совпадает с именем каталога).

Поддержка обновляемой справки

Если вы создаете модуль, вы можете поддерживать справку в Интернете и обновляемую справку для своих модулей. Дополнительные сведения см. в разделах Поддержка обновляемой справки и Поддержка справки в Интернете.

Обновляемая справка недоступна для оснастки PowerShell или справки на основе комментариев.

Поделиться через