about_Updatable_Help

Статья
06/21/2023

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

Описывает обновляемую справочную систему в 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 3.0 не содержит файлы справки. С помощью обновляемой справки можно установить файлы справки для всех команд, включенных по умолчанию в 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-Help -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 в качестве имени модуля.

$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
{ Get-Module -Name DhcpServer -ListAvailable }
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:\UsbFlashDrive\DhcpModule.xml -InputObject $m

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

Чтобы открыть раздел справки в Интернете для любого командлета или функции, используйте параметр 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 или справки на основе комментариев.

Share via