Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0
Вставьте сюда введение.
РАЗДЕЛ
about_Comment_Based_Help
КРАТКОЕ ОПИСАНИЕ
В этом разделе объясняется, как писать разделы справки на основе комментариев для функций и сценариев.
ПОДРОБНОЕ ОПИСАНИЕ
Разделы справки на основе комментариев по функциям и сценариям можно писать с помощью специальных ключевых слов комментария справки.
Командлет Get-Help отображает справку на основе комментариев в том же формате, в каком он выводит разделы справки по командлетам, созданные на основе XML-файлов. Чтобы отобразить содержимое справки на основе комментариев, пользователи могут использовать все параметры Get-Help, такие как Detailed, Full, Example и Online.
Можно также писать файлы справки на основе XML по функциям и сценариям. Чтобы командлет Get-Help мог найти файл справки на основе XML по функции или сценарию, используйте ключевое слово ExternalHelp. Без этого ключевого слова Get-Help не сможет найти разделы справки на основе XML по функциям или сценариям.
В этом разделе объясняется, как писать разделы справки по функциям и сценариям. Сведения о способах отображения разделов справки по функциям и сценариям см. в разделе Get-Help.
ПРИМЕЧАНИЕ.
Командлеты Update-Help и Save-Help работают только с XML-файлами. Обновляемая справка не поддерживает разделы справки на основе комментариев.
ЗАМЕЧАНИЕ ПО УСТРАНЕНИЮ НЕПОЛАДОК.
Значения по умолчанию и значение параметра "Принимать подстановочные знаки" не отображаются в таблице атрибутов параметров, даже если они определены в функции или сценарии. Чтобы помочь пользователям, включите эти сведения в описание параметра.
СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ
Синтаксис справки на основе комментариев выглядит следующим образом:
# .< help keyword>
# <help content>
-or -
<#
.< help keyword>
< help content>
#>
Справка на основе комментариев пишется как серия комментариев. Можно ввести символ комментария (#) перед каждой строкой комментариев или использовать символы "<#" и "#>", чтобы создать блок комментариев. Все строки в блоке комментариев интерпретируются как комментарии.
Все строки в разделе справки на основе комментариев должны быть сплошными. Если раздел справки на основе комментариев следует за комментарием, который не является частью раздела справки, должна быть как минимум одна пустая строка между последней строкой несправочного комментария и началом справки на основе комментариев.
Каждый раздел справки на основе комментариев определяется ключевыми словами. Перед каждым ключевым словом справки на основе комментариев ставится точка (.). Ключевые слова могут располагаться в любом порядке. В именах ключевых слов регистр не учитывается.
Например, ключевое слово Description предшествует описанию функции или сценария.
<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>
Блок комментариев должен содержать хотя бы одно ключевое слово. Некоторые ключевые слова, например EXAMPLE, могут многократно использоваться в одном блоке комментариев. Содержание справки по каждому ключевому слову начинается в строке после ключевого слова и может занимать несколько строк.
СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В ФУНКЦИЯХ
Справка по функции на основе комментариев может отображаться в одном из трех мест:
-- At the beginning of the function body.
-- At the end of the function body.
-- Before the Function keyword. There cannot be more than one blank
line between the last line of the function help and the Function
keyword.
Например:
function Get-Function
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
-or -
function Get-Function
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
-or -
<#
.< help keyword>
< help content>
#>
function Get-Function { }
СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В СЦЕНАРИЯХ
Справка на основе комментариев по сценарию может отображаться в одном из следующих двух мест в сценарии:
-- At the beginning of the script file. Script help can be preceded in the
script only by comments and blank lines.
-- If the first item in the script body (after the help) is a function
declaration, there must be at least two blank lines between the end of the
script help and the function declaration. Otherwise, the help is
interpreted as being help for the function, not help for the script.
-- At the end of the script file. However, if the script is signed, place
Comment-based help at the beginning of the script file. The end of the
script is occupied by the signature block.
Например:
<#
.< help keyword>
< help content>
#>
function Get-Function { }
-or-
function Get-Function { }
<#
.< help keyword>
< help content>
#>
СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В МОДУЛЯХ СЦЕНАРИЕВ
В модуле сценариев (.psm1) справка на основе комментариев использует синтаксис функций, а не сценариев. С помощью синтаксиса сценариев невозможно написать справку по всем функциям, определенным в модуле сценариев.
Например, если вы используете ключевое слово ExternalHelp, чтобы определить файлы справки на основе XML по функциям в модуле сценария, необходимо добавить комментарий ExternalHelp в каждую функцию.
# .ExternalHelp <XML-file-name>
function <function-name>
{
...
}
КЛЮЧЕВЫЕ СЛОВА СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ
Ниже приведены допустимые ключевые слова справки на основе комментариев. Они перечислены в порядке, в котором обычно представлены в разделе справки, вместе с описанием. Эти ключевые слова могут располагаться в любом порядке в справке на основе комментариев, и регистр в них не учитывается.
.SYNOPSIS
Краткое описание функции или сценария. Это ключевое слово может использоваться в каждом разделе только один раз.
.DESCRIPTION
Подробное описание функции или сценария. Это ключевое слово может использоваться в каждом разделе только один раз.
.PARAMETER <Parameter-Name>
Описание параметра. Ключевое слово .PARAMETER добавляется к каждому параметру в синтаксисе функции или сценария.
Имя параметра вводится в одной строке с ключевым словом .PARAMETER. Описание параметра вводится в строках после ключевого слова .PARAMETER. Windows PowerShell интерпретирует весь текст между строкой .PARAMETER и следующим ключевым словом или концом блока комментариев как часть описания параметра. Описание может содержать разрывы абзацев.
Ключевые слова Parameter могут располагаться в любом порядке в блоке комментариев, но порядок, в котором параметры (и их описания) отображаются в разделе справки, определяется функцией или сценарием. Чтобы изменить порядок, необходимо изменить синтаксис.
Кроме того, можно указать описание параметра, поместив комментарий в синтаксисе функции или сценария непосредственно перед именем переменной параметра. Если вы одновременно используете комментарий синтаксиса и ключевое слово Parameter, применяется связанное с этим словом описание, а комментарий синтаксиса игнорируется.
.EXAMPLE
Пример команды, использующий функцию или сценарий. При необходимости за ним следует пример выходных данных и описание. Это ключевое слово необходимо повторить для каждого примера.
.INPUTS
Объекты типа Microsoft .NET Framework, которые можно передать в функцию или сценарий по конвейеру. Кроме того, можно включить описание входных объектов.
.OUTPUTS
Объекты типа .NET Framework, возвращаемые командлетом. Кроме того, можно включить описание возвращаемых объектов.
.NOTES
Дополнительные сведения о функции или сценарии.
.LINK
Название связанного раздела. Значение отображается в строке под ключевым словом .LINE и должно следовать за символом комментария (#) или быть включено в блок комментариев.
Ключевое слово .LINK необходимо повторить для каждого связанного раздела.
Это содержимое отображается в разделе справки со ссылками по теме (Related Links).
Ключевое слово Link может также включать универсальный код ресурса (URI) для сетевой версии того же раздела справки. Сетевая версия открывается при использовании параметра Online командлета Get-Help. URI должен начинаться с http или https.
.COMPONENT
Технология или компонент, которые используются функцией или сценарием или связаны с ними. Это содержимое отображается, если команда Get-Help включает параметр Component.
.ROLE
Роль пользователя для раздела справки. Это содержимое отображается, если команда Get-Help включает параметр Role.
.FUNCTIONALITY
Назначение функции. Это содержимое отображается, если команда Get-Help включает параметр Functionality.
.FORWARDHELPTARGETNAME <Command-Name>
Перенаправляет пользователей к разделу справки по указанной команде. Можно перенаправлять пользователей к любому разделу справки, включая разделы справки по функциям, сценариям, командлетам или поставщикам.
.FORWARDHELPCATEGORY <Category>
Определяет категорию справки элемента в ключевом слове ForwardHelpTargetName. Допустимые значения: Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter и All. Это ключевое слово позволяет избежать конфликтов при наличии команд с одинаковым именем.
.REMOTEHELPRUNSPACE <PSSession-variable>
Определяет сеанс, который содержит раздел справки. Необходимо ввести переменную, содержащую PSSession. С помощью этого ключевого слова командлет Export-PSSession находит разделы справки по экспортированным командам.
.EXTERNALHELP <XML Help File>
Определяет файл справки на основе XML по сценарию или функции.
Если функция или сценарий записаны в XML-файлах, требуется ключевое слово ExternalHelp. Без этого ключевого слова командлет Get-Help не сможет найти файл справки на основе XML по функции или сценарию.
Ключевое слово ExternalHelp имеет приоритет над другими ключевыми словами справки на основе комментариев. С ключевым словом ExternalHelp командлет Get-Help не отображает справку на основе комментариев, даже если он не может найти раздел справки, соответствующий значению ключевого слова ExternalHelp.
Если функция экспортируется модулем, задайте значение ключевого слова ExternalHelp для имени файла без пути. Командлет Get-Help выполняет поиск указанного имени файла во вложенной папке каталога модуля, соответствующей выбранному языку. Специальных требований к имени файла справки на основе XML по функции нет, но рекомендуется использовать следующий формат:
<ScriptModule.psm1>-help.xml
Если функция не включена в модуль, в файл справки на основе XML следует добавить путь. Если значение включает путь, а путь содержит подкаталоги, соответствующие выбранным региональным параметрам пользовательского интерфейса, командлет Get-Help выполняет в подкаталогах рекурсивный поиск XML-файла с именем сценария или функции в соответствии с базовыми языковыми параметрами, установленными для Windows, аналогично тому, как это делается в каталоге модуля.
Подробнее о формате файлов справки на основе XML по командлетам можно узнать в статье библиотеки MSDN "Создание справки по командлетам" по адресу https://go.microsoft.com/fwlink/?LinkID=123415.
АВТОМАТИЧЕСКИ СОЗДАВАЕМОЕ СОДЕРЖИМОЕ
Имя, синтаксис, список параметров, таблица атрибутов параметров, общие параметры и замечания автоматически создаются с помощью командлета Get-Help.
Имя.
Узел Name раздела справки по функции создается на основе имени функции в ее синтаксисе. Имя раздела справки по сценарию создается на основе имени файла сценария. Чтобы изменить имя или регистр букв, измените синтаксис функции или имя файла сценария.
Синтаксис:
Узел Syntax раздела справки создается на основе синтаксиса функции или сценария. Чтобы добавить данные в синтаксис раздела справки, например параметр типа .NET Framework, добавьте данные в синтаксис функции или сценария. Если тип параметра не указан, в качестве значения по умолчанию добавляется тип Object.
Список параметров:
Список параметров в разделе справки создается на основе синтаксиса функции или сценария, а также описаний, добавляемых с помощью ключевого слова Parameters. Параметры функции отображаются в узле Parameters раздела справки в том же порядке, в каком они отображаются в синтаксисе функции или сценария. Написание и регистр букв имен параметров также берутся из синтаксиса и не зависят от имени параметра, указанного с помощью ключевого слова Parameter.
Общие параметры:
Общие параметры добавляются в синтаксис и список параметров раздела справки, даже если они недействительны. Подробнее об общих параметрах можно узнать в статье about_CommonParameters.
Таблица атрибутов параметров:
Командлет Get-Help создает таблицу атрибутов параметров, которая отображается при использовании параметра Full или Parameter командлета Get-help. Значения атрибутов Required, Position и Default берутся из синтаксиса функции или сценария.
ЗАМЕЧАНИЕ ПО УСТРАНЕНИЮ НЕПОЛАДОК.
Значения по умолчанию не отображаются в таблице атрибутов параметров, даже если они определены в функции или сценарии. Чтобы помочь пользователям, включите список значений по умолчанию в описание параметра.
Замечания:
Узел Remarks (Замечания) раздела справки автоматически создается на основе имени функции или сценария. Изменить его содержимое невозможно.
ОТКЛЮЧЕНИЕ СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ
[Эта технология была предложена Ричем Прескоттом (Rich Prescott), инженером Windows из Нью-Йорка, США.]
Справку на основе комментариев можно отключить. В результате справка на основе комментариев становится неактивной, но не удаляется.
Чтобы отключить справку на основе комментариев, заключите комментарии в here-строку. Чтобы скрыть here-строку, присвойте ее переменной или передайте по конвейеру в командлет Out-Null.
При отключении справка на основе комментариев теряет свое действие.
Например, следующая функция содержит справку на основе комментариев:
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
Чтобы отключить справку, заключите ее в here-строку, как показано в следующем примере:
@"
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
"@
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
Чтобы скрыть отключенную справку, присвойте here-строку локальной переменной, которая не используется в функции в других целях, как показано в следующем примере: Ее можно также передать по конвейеру в командлет Out-Null.
$x = @"
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
"@
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
Дополнительные сведения о here-строках см. в статье about_Quoting_Rules (https://go.microsoft.com/fwlink/?LinkID=113253).
ПРИМЕРЫ
Пример 1. Справка на основе комментариев по функции
Следующий пример функции содержит справку на основе комментариев:
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Результаты:
C:\PS> get-help add-extension -full
NAME
Add-Extension
SYNOPSIS
Adds a file name extension to a supplied name.
SYNTAX
Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]
DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
PARAMETERS
-Name
Specifies the file name.
Required? false
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-Extension
Specifies the extension. "Txt" is the default.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".
INPUTs
None. You cannot pipe objects to Add-Extension.
OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
-------------------------- EXAMPLE 1 --------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- EXAMPLE 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- EXAMPLE 3 --------------------------
C:\PS> extension "File" "doc"
File.doc
RELATED LINKS
http://www.fabrikam.com/extension.html
Set-Item
Пример 2. Описания параметров в синтаксисе функции
Этот пример отличается от предыдущего только тем, что описания параметров в нем включены в синтаксис функции. Этот формат наиболее целесообразен, когда приводятся краткие описания.
function Add-Extension
{
param
(
[string]
# Specifies the file name.
$name,
[string]
# Specifies the file name extension. \"Txt\" is the default.
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Пример 3. Справка на основе комментариев по сценарию
Следующий пример сценария содержит справку на основе комментариев:
Обратите внимание на пустые строки между закрывающим символом "#>" и оператором Param. В сценарии без оператора Param должно быть не менее двух пустых строк между последним комментарием в разделе справки и первым объявлением функции. Без этих пустых строк командлет Get-Help связывает раздел справки с функцией, а не со сценарием.
<#
.SYNOPSIS
Performs monthly data updates.
.DESCRIPTION
The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.
.PARAMETER InputPath
Specifies the path to the CSV-based input file.
.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.
.INPUTS
None. You cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not generate any output.
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
Следующая команда возвращает справку по сценарию. Так как в каталоге, указанном в переменной среды Path, сценарий отсутствует, команда Get-Help, которая возвращает справку по сценарию, должна указывать путь к нему.
PS C:\ps-test> get-help .\update-month.ps1 -full
NAME
C:\ps-test\Update-Month.ps1
SYNOPSIS
Performs monthly data updates.
SYNTAX
C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]
DESCRIPTION
The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.
PARAMETERS
-InputPath
Specifies the path to the CSV-based input file.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
None. You cannot pipe objects to Update-Month.ps1.
OUTPUTS
None. Update-Month.ps1 does not generate any output.
-------------------------- EXAMPLE 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- EXAMPLE 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- EXAMPLE 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
RELATED LINKS
Пример 4. Перенаправление к XML-файлу
Разделы справки по функциям и сценариям можно создавать на основе XML. Хотя справку на основе комментариев реализовать проще, справка на основе XML необходима для обновляемой справки, чтобы разделы справки могли создаваться на различных языках.
В следующем примере показаны первые несколько строк сценария Update-Month.ps1. В сценарии используется ключевое слово ExternalHelp, которое указывает путь к разделу на справки на основе XML по сценарию.
Обратите внимание, что значение ключевого слова ExternalHelp находится с ним в одной строке. В любом другом положении это значение недействительно.
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
В следующем примере показаны три допустимых положения ключевого слова ExternalHelp в функции:
function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}
Пример 5. Перенаправление в другой раздел справки
Приведенный ниже код — это фрагмент начала встроенной функции справки в Windows PowerShell, которая одновременно выводит только одно окно текста справки. Так как в разделе справки по командлету Get-Help описывается функция справки, эта функция использует ключевые слова ForwardHelpTargetName и ForwardHelpCategory для перенаправления пользователя к разделу справки по командлету Get-Help.
function help
{
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...
Эта функция используется в следующей команде:
C:\PS> get-help help
NAME
Get-Help
SYNOPSIS
Displays information about Windows PowerShell cmdlets and concepts.
...
КЛЮЧЕВЫЕ СЛОВА
about_Comment Based_Help
СМ. ТАКЖЕ
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"Создание справки по командлетам" (https://go.microsoft.com/fwlink/?LinkID=123415)