about_Updatable_Help

  • Статья

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

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

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

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

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

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

В 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 командлет отображает автоматически созданную справку и предложит скачать файлы справки или прочитать их в Интернете.

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

Например, следующая команда получает базовую справку для командлета 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, необходимо быть членом группы Администратор istrator на компьютере.

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

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

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

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

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

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

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

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

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

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

Update-Help

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

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

Update-Help -Module ServerManager

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

Если значение параметра модуля равно (все), 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-HelpSave-Help и командлеты загружают справку по языку и языку пользовательского интерфейса, заданному для Windows на локальном компьютере. Если файлы справки для указанных модулей недоступны в локальном языке и региональных параметрах пользовательского интерфейса, Update-Help и Save-Help используйте резервные правила языка Windows, чтобы найти лучший поддерживаемый язык.

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

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

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

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

Примечание.

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

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

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

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

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

Get-Help Get-Job -Online

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

Параметр Online не работает с разделами About. Дополнительные сведения о темах PowerShell, включая разделы справки по языку PowerShell, см. в разделе "Разделы о PowerShell".

Как свести к минимуму или предотвратить скачивание в Интернете

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

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

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

Примечание.

В разделе "Конфигурация компьютера и конфигурация пользователя" отображается исходный путь по умолчанию для параметра групповой политики update-Help. Однако только параметр политики в разделе "Конфигурация компьютера" действует. Параметр политики в разделе "Конфигурация пользователя" игнорируется.

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

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

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

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

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

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

Как поддерживать обновляемую справку

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

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

Замечания

Save-Help Командлеты Update-Help не поддерживаются в среде предустановки Windows (Windows PE).

См. также