about_Updatable_Help
Назначение: Windows PowerShell 3.0
РАЗДЕЛ
About_Updatable_Help
КРАТКОЕ ОПИСАНИЕ
Содержит описание обновляемой системы справки в Windows PowerShell®.
ПОДРОБНОЕ ОПИСАНИЕ
Windows PowerShell предоставляет несколько разных способов доступа к самым актуальным разделам справки по командлетам и понятиям Windows PowerShell.
Обновляемая справочная система, появившаяся в Windows PowerShell 3.0, призвана обеспечить наличие новейших разделов справки на локальном компьютере, которые можно читать в командной строке. Она упрощает скачивание и установку файлов справки и их обновление при появлении новых версий.
Для обновления справки на нескольких компьютерах в организации, а также на компьютерах без доступа к Интернету обновляемая справочная система позволяет скачивать файлы справки в папку в файловой системе или в общую папку, а затем устанавливать их из этой папки.
В Windows PowerShell 4.0 свойство HelpInfoUri сохраняется при удаленном взаимодействии Windows PowerShell, благодаря чему командлет Save-Help работает для модулей, которые установлены на удаленном компьютере, но не обязательно установлены на локальном. Объект PSModuleInfo можно сохранить на диск или съемный носитель (например, USB-накопитель), выполнив командлет Export-CliXml на компьютере без доступа к Интернету, импортировав объект PSModuleInfo на компьютер без доступа к Интернету, а затем выполнив командлет Save-Help применительно к объекту PSModuleInfo. Сохраненную справку можно скопировать на удаленный отключенный компьютер с помощью съемного носителя, а затем установить, выполнив командлет Update-Help. Эти улучшения в плане функциональных возможностей командлета Save-Help позволяют установить справку на компьютерах, полностью лишенных доступа к сети. Пример использования новых функциональных возможностей командлета Save-Help см. в подразделе «ОБНОВЛЕНИЕ СПРАВКИ ИЗ ОБЩЕЙ ПАПКИ: SAVE-HELP» этого раздела.
Обновляемая справка также поддерживает доступ к новейшим разделам справки и основной справке по командлетам в Интернете, даже если на компьютере нет файлов справки.
В состав Windows PowerShell 3.0 файлы справки не входят. С помощью функции обновляемой справки можно установить файлы справки по всем командам, которые входят в состав Windows PowerShell по умолчанию, и по всем модулям Windows.
КОМАНДЛЕТЫ ДЛЯ РАБОТЫ С ОБНОВЛЯЕМОЙ СПРАВКОЙ
Update-Help.
Скачивает последние файлы справки из Интернета или общей папки и устанавливает их на локальном компьютере.
Save-Help.
Скачивает последние файлы справки из Интернета и сохраняет их в каталоге файловой системы или в общей папке. Чтобы установить файлы справки на компьютерах, используйте командлет Update-Help.
Get-Help.
Выводит разделы справки в командной строке.
Получает справку из файлов справки на компьютере.
Выводит автоматически создаваемую справку по командлетам и функциям, для которых нет файлов справки.
Открывает разделы справки в Интернете для командлетов, функций, сценариев и рабочих процессов в браузере по умолчанию.
ОБНОВЛЕНИЕ СПРАВКИ В ИНТЕГРИРОВАННОЙ СРЕДЕ СЦЕНАРИЕВ WINDOWS POWERSHELL
Справку можно также обновить с помощью пункта «Обновить справку Windows PowerShell» в меню «Справка» интегрированной среды сценариев Windows PowerShell (ISE).
Пункт «Обновить справку Windows PowerShell» выполняется как команда Update-Help без параметров.
АВТОМАТИЧЕСКИ СОЗДАВАЕМАЯ СПРАВКА: СПРАВКА БЕЗ ФАЙЛОВ СПРАВКИ
Если на компьютере нет файла справки по командлету, функции или рабочему процессу, командлет Get-Help выводит автоматически созданную справку и предлагает скачать файлы справки или прочитать их в Интернете.
Автоматически созданная справка содержит описание синтаксиса и псевдонимов, а также примечания касательно использования командлетов для работы с обновляемой справкой и доступа к разделам справки в Интернете.
Например, приведенная ниже команда возвращает базовую справку по командлету Get-Culture. Если на компьютере нет файлов справки, в выходных данных приводится командлет Get-Help.
PS C:\> Get-Help Get-Culture
НАЗВАНИЕ
Get-Culture
СИНТАКСИС
Get-Culture [<Общие_параметры>]
ПСЕВДОНИМЫ
Нет
ЗАМЕЧАНИЯ
Чтобы получить новейшую справку, включая описания и примеры, введите: 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. Перезапускать Windows PowerShell не нужно.
Чтобы установить или обновить справку для всех модулей на компьютере, которые поддерживают обновляемую справку, введите следующую команду:
Update-Help
Чтобы обновить справку по определенным модулям, добавьте параметр Module командлета Update-Help. В именах модулей можно использовать подстановочные знаки.
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 с клиентского компьютера, подключенного к Интернету, без установки роли DHCP-сервера или модуля DhcpServer на локальном компьютере.
Вариант 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 в свой профиль Windows PowerShell.
Внутренняя квота запрещает выполнение команды Update-Help чаще, чем один раз в день. Чтобы переопределить это ограничение, используйте параметр Force.
Используйте в своем профиле команду наподобие приведенной ниже. Эта команда обновляет справку для всех установленных модулей в фоновом режиме, не мешая вам работать. В ней используется команда Out-Null, чтобы отключить возврат из задания и сообщения об ошибках, которые отображаются при использовании команды чаще, чем один раз в день.
Start-Job {Update-Help} | Out-Null
Также можно создать запланированное задание, которое выполняет командлет Update-Help или Save-Help через любой промежуток времени.
Например, приведенная ниже команда создает запланированное задание, которое выполняет командлет Update-Help каждую пятницу в 5:00. Чтобы выполнить эту команду, запустите Windows PowerShell в режиме «Запуск от имени администратора».
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
Подробнее о запланированных заданиях см. в разделе about_Scheduled_Jobs.
ИСПОЛЬЗОВАНИЕ СПРАВКИ В ИНТЕРНЕТЕ
Если вы не можете или не хотите обновлять файлы справки на локальном компьютере, то можете получить доступ к последним файлам справки в Интернете.
Чтобы открыть справку по любому командлету или функции в Интернете, используйте параметр Online командлета Get-Help.
Например, приведенная ниже команда открывает раздел веб-справки по командлету Get-Job в браузере по умолчанию.
Get-Help Get-Job -Online
– или –
Get-Help -on Get-Job
Чтобы открыть справку по сценарию в Интернете, используйте параметр Online и полный путь к сценарию.
Параметр Online не работает с общими разделами справки. Чтобы получить доступ к общим разделам, касающимся базовых модулей Windows PowerShell, включая разделы справки по языку Windows PowerShell, посетите страницу «Разделы справки по модулю Windows PowerShell Core» по адресу https://go.microsoft.com/fwlink/?LinkID=113206.
СВЕДЕНИЕ К МИНИМУМУ ИЛИ ПРЕДОТВРАЩЕНИЕ СКАЧИВАНИЯ ФАЙЛОВ ИЗ ИНТЕРНЕТА
Чтобы свести к минимуму скачивание файлов из Интернета и предоставить обновляемую справку пользователям, не имеющим доступа к Интернету, используйте командлет Save-Help. Скачайте справку из Интернета и сохраните ее в сетевой папке. Затем создайте параметр групповой политики или запланированное задание, которое выполняет команду Update-Help на всех компьютерах. Укажите сетевую папку в качестве значения параметра SourcePath командлета Update-Help.
Чтобы запретить пользователям, которые имеют доступ к Интернету, скачивать обновляемую справку из Интернета, используйте параметр групповой политики «Задать исходный путь по умолчанию для Update-Help».
Этот параметр неявно добавляет параметр SourcePath с указанной папкой файловой системы в качестве значения к каждой команде Update-Help на каждом затронутом компьютере. С помощью параметра SourcePath пользователи могут явно указать другую папку файловой системы, но не могут исключить параметр SourcePath и скачать справку из Интернета.
ПРИМЕЧАНИЕ.
Параметр групповой политики «Задать исходный путь по умолчанию для Update-Help» находится в разделах «Конфигурация компьютера» и «Конфигурация пользователя». Тем не менее, силу имеет только параметр политики в разделе «Конфигурация компьютера». Параметр политики в разделе «Конфигурация пользователя» игнорируется.
Подробнее см. в разделе about_Group_Policy_Settings.
ОБНОВЛЕНИЕ СПРАВКИ ДЛЯ НЕСТАНДАРТНЫХ МОДУЛЕЙ
Чтобы обновить или сохранить справку по модулю, который не возвращается параметром ListAvailable командлета Get-Module, импортируйте модуль в текущий сеанс перед выполнением команды Update-Help или Save-Help. На удаленном компьютере, прежде чем выполнять команду Save-Help, импортируйте модуль в текущей сеанс CIM или PSSession либо в блок сценария Invoke-Command, подключенный к удаленному компьютеру.
Когда модуль будет включен в текущий сеанс, выполните командлет Update-Help или Save-Help без параметров либо укажите имя модуля с помощью параметра Module.
Параметр Module командлетов Update-Help и Save-Help принимает в качестве значения только имя модуля. Он не принимает путь к файлу модуля.
Используйте этот прием для обновления или сохранения справки по любому модулю, который не возвращается параметром ListAvailable командлета Get-Module, например по модулю, установленному в папке, которая не указана в переменной среды PSModulePath, или модулю, имеющему неправильный формат (каталог модуля не содержит ни одного файла, базовое имя которого совпадает с именем каталога).
ПОДДЕРЖКА ОБНОВЛЯЕМОЙ СПРАВКИ
При создании модуля вы можете обеспечить для него справку в Интернете и обновляемую справку. Подробнее см. в разделах «Поддержка обновляемой справки» и «Поддержка справки в Интернете» в библиотеке MSDN.
Обновляемая справка не доступна для оснасток Windows PowerShell и справки на основе комментариев.
КЛЮЧЕВЫЕ СЛОВА
About_Updateable_Help
ЗАМЕЧАНИЯ
Командлеты Update-Help и Save-Help не поддерживаются в среде предустановки Windows (Windows PE).
СМ. ТАКЖЕ
Get-Help
Save-Help
Update-Help
Таблица состояния обновляемой справки