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

  • Статья

КРАТКОЕ ОПИСАНИЕ

Описывает обновляемую справочную систему в 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 см. в разделе HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP этой статьи.

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

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

ОБНОВЛЯЕМЫЕ КОМАНДЛЕТЫ СПРАВКИ

  • Update-Help: скачивает новейшие файлы справки из Интернета или общей папки и устанавливает их на локальный компьютер.

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

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

ОБНОВЛЕНИЕ СПРАВКИ В ИНТЕГРИРОВАННОЙ СРЕДЕ СЦЕНАРИЕВ PowerShell

Вы также можете обновить справку с помощью элемента "Обновить справку PowerShell" в меню "Справка" в интегрированной среде сценариев PowerShell (ISE).

Элемент "Обновить справку PowerShell" выполняет команду Update-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, необходимо быть членом группы Администраторы на компьютере.

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

Обновление справки для модулей в каталоге $home\Documents\WindowsPowerShell\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 имеет значение * (все), Update-Help пытается обновить справку для всех установленных модулей, включая модули, которые не поддерживают обновляемую справку. Эта команда обычно вызывает множество ошибок, так как командлет сталкивается с модулями, которые не поддерживают обновляемую справку.

ОБНОВЛЕНИЕ СПРАВКИ ИЗ ОБЩЕЙ ПАПКИ: SAVE-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 скачивает справку для всех модулей в сеансе и для всех установленных модулей, поддерживающих обновляемую справку. Для включения модули должны быть установлены в каталогах, перечисленных в значении переменной среды PSModulePath, на локальном компьютере или на удаленном компьютере, для которого требуется сохранить справку. Эти модули также возвращаются при выполнении команды Get-Help -ListAvailable.

ОБНОВЛЕНИЕ ФАЙЛОВ СПРАВКИ НА РАЗНЫХ ЯЗЫКАХ

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

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

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

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

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

АВТОМАТИЧЕСКОЕ ОБНОВЛЕНИЕ СПРАВКИ

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

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

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

Start-Job {Update-Help} | Out-Null

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

Например, следующая команда создает запланированное задание, которое выполняет команду Update-Help help каждую пятницу в 5:00. Чтобы выполнить эту команду, запустите PowerShell с параметром "Запуск от имени администратора".

Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")

ИСПОЛЬЗОВАНИЕ СПРАВКИ ИЗ ИНТЕРНЕТА

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

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

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

Get-Help Get-Job -Online

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

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

СВЕДЕНИЯ О ТОМ, КАК СВЕСТИ К МИНИМУМУ ИЛИ ПРЕДОТВРАТИТЬ СКАЧИВАНИЕ ИЗ ИНТЕРНЕТА

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

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

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

ПРИМЕЧАНИЕ. Параметр групповой политики "Задать исходный путь по умолчанию для Update-Help" отображается в разделе Конфигурация компьютера и Конфигурация пользователя. Однако действует только параметр политики в разделе Конфигурация компьютера. Параметр политики в разделе Конфигурация пользователя игнорируется.

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

ОБНОВЛЕНИЕ СПРАВКИ ДЛЯ НЕСТАНДАРТНЫХ МОДУЛЕЙ

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

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

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

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

ПОДДЕРЖКА ОБНОВЛЯЕМОЙ СПРАВКИ

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

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

ПРИМЕЧАНИЯ

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

СМ. ТАКЖЕ

Get-Help

Save-Help

Update-Help