Yorum Tabanlı Yardım Hakkında

Kısa açıklama

İşlevler ve betikler için açıklama tabanlı yardım içeriğinin nasıl yazıldığı açıklanır.

Uzun açıklama

Özel yardım açıklaması anahtar sözcüklerini kullanarak işlevler ve betikler için açıklama tabanlı yardım içeriği yazabilirsiniz.

Get-Help cmdlet'i, açıklama tabanlı yardımı, XML dosyalarından oluşturulan cmdlet yardım içeriğinin görüntülendiği biçimde görüntüler. Kullanıcılar, açıklama tabanlı yardımın içeriğini görüntülemek için Get-HelpAyrıntılı, Tam, Örneklerive Onlinegibi tüm parametrelerini kullanabilir.

İşlevler ve betikler için XML tabanlı yardım dosyaları da yazabilirsiniz. bir işlev veya betiğin XML tabanlı yardım dosyasını bulmak üzere Get-Help cmdlet'ini etkinleştirmek için .EXTERNALHELP anahtar sözcüğünü kullanın. Bu anahtar sözcük olmadan, Get-Help işlevler veya betikler için XML tabanlı yardım içeriğini bulamazsınız.

Bu konu başlığı altında, işlevler ve betikler için yardım içeriğinin nasıl yaz olduğu açıklanmaktadır. İşlevler ve betikler için yardım içeriğini görüntüleme hakkında bilgi için bkz. Get-Help.

Update-Help ve Save-Help cmdlet'leri yalnızca XML dosyalarında çalışır. Güncelleştirilebilir Yardım, açıklama tabanlı yardım içeriğini desteklemez.

Açıklama tabanlı yardım için söz dizimi

Açıklama tabanlı yardım içeriği oluşturmak için açıklama stillerinden birini kullanabilirsiniz: tek satırlı açıklamalar veya blok açıklamaları.

Açıklama tabanlı yardımın söz dizimi aşağıdaki gibidir:

# .<help keyword>
# <help content>

veya

<#
    .<help keyword>
    <help content>
#>

Açıklama tabanlı yardım, bir açıklama dizisi olarak yazılır. Her açıklama satırından önce # bir açıklama simgesi yazabilir veya açıklama bloğu oluşturmak için <# ve #> simgelerini kullanabilirsiniz. Açıklama bloğundaki tüm satırlar açıklama olarak yorumlanır.

Açıklama tabanlı yardım konu başlığındaki tüm satırlar bitişik olmalıdır. Açıklama tabanlı bir yardım konusu, yardım konusunun parçası olmayan bir açıklamayı izlerse, son yardım dışı açıklama satırı ile açıklama tabanlı yardımın başlangıcı arasında en az bir boş satır olmalıdır.

Anahtar sözcükler, açıklama tabanlı yardımın her bölümünü tanımlar. Her açıklama tabanlı yardım anahtar kelimesinin önünde bir nokta bulunur .. Anahtar sözcükler herhangi bir sırada görünebilir. Anahtar kelime adları büyük/küçük harfe duyarlı değildir.

Örneğin, .DESCRIPTION anahtar sözcüğü bir işlevin veya betiğin açıklamasının önündedir.

<#
.DESCRIPTION
Get-Function displays the name and syntax of all functions in the session.
#>

Açıklama bloğu en az bir anahtar sözcük içermelidir. .EXAMPLEgibi bazı anahtar sözcükler aynı açıklama bloğunda birçok kez görünebilir. Her anahtar sözcüğün yardım içeriği, anahtar sözcüğün ardından satırda başlar ve birden çok satıra yayılabilir.

İşlevlerde açıklama tabanlı yardım için söz dizimi

bir işlev için açıklama tabanlı yardım üç konumdan birinde görünebilir:

  • İşlev gövdesinin başında.
  • İşlev gövdesinin sonunda.
  • function anahtar sözcüğünden önce. İşlev yardımının son satırı ile function anahtar sözcüğü arasında birden fazla boş satır olamaz.

Mesela:

function Get-Function {
    <#
        .<help keyword>
        <help content>
    #>

    # function logic
}

veya

function Get-Function {
    # function logic

    <#
        .<help keyword>
        <help content>
    #>
}

veya

<#
    .<help keyword>
    <help content>
#>
function Get-Function { }

Betiklerde açıklama tabanlı yardım için söz dizimi

Betik için açıklama tabanlı yardım, betikte aşağıdaki iki konumdan birinde görüntülenebilir.

  • Betik dosyasının başında. Betik yardımının önüne yalnızca açıklamalar ve boş satırlar eklenebilir.

    Betik gövdesindeki ilk öğe (yardımdan sonra) bir işlev bildirimiyse, betik yardımının sonu ile işlev bildirimi arasında en az iki boş satır olmalıdır. Aksi takdirde, yardım betik için değil, işlev için yardım olarak yorumlanır.

  • Betik dosyasının sonunda. Ancak, betik imzalıysa, betik dosyasının başlangıcına açıklama tabanlı yardım yerleştirin. Betiğin sonunda imza bloğu yer almaktadır.

Mesela:

<#
.<help keyword>
<help content>
#>
function Get-Function { }

veya

function Get-Function { }
<#
.<help keyword>
<help content>
#>

Açıklama tabanlı yardım anahtar sözcükleri

Aşağıda geçerli açıklama tabanlı yardım anahtar sözcükleri yer alır. Bu anahtar sözcükler yorum tabanlı yardımda herhangi bir sırada görünebilir ve büyük/küçük harfe duyarlı değildir. Anahtar sözcükler bu makalede genellikle bir yardım konusunda göründükleri sırayla listelenir.

.SYNOPSIS

İşlevin veya betiğin kısa bir açıklaması. Bu anahtar sözcük her konuda yalnızca bir kez kullanılabilir.

.DESCRIPTION

İşlevin veya betiğin ayrıntılı açıklaması. Bu anahtar sözcük her konuda yalnızca bir kez kullanılabilir.

.PARAMETER

Parametrenin açıklaması. İşlev veya betik söz dizimindeki her parametre için bir .PARAMETER anahtar sözcüğü ekleyin.

parametre adını .PARAMETER anahtar sözcüğüyle aynı satıra yazın. .PARAMETER anahtar sözcüğünü izleyen satırlara parametre açıklamasını yazın. Windows PowerShell, .PARAMETER satırı ile sonraki anahtar sözcük veya açıklama bloğunun sonu arasındaki tüm metni parametre açıklamasının bir parçası olarak yorumlar. Açıklama paragraf sonları içerebilir.

.PARAMETER  <Parameter-Name>

Parametre anahtar sözcükleri açıklama bloğunda herhangi bir sırada görünebilir, ancak işlev veya betik söz dizimi, yardım konusunda parametrelerin (ve açıklamalarının) görüntülenme sırasını belirler. Sırayı değiştirmek için söz dizimini değiştirin.

Ayrıca, parametre değişkeni adından hemen önce işleve veya betik söz dizimine bir açıklama ekleyerek parametre açıklaması belirtebilirsiniz. Bunun işe yaraması için en az bir anahtar sözcük içeren bir açıklama bloğuna da sahip olmanız gerekir.

Hem bir söz dizimi yorumu hem de .PARAMETER anahtar kelimesi kullanırsanız, .PARAMETER anahtar kelimesiyle ilişkili açıklama kullanılır ve söz dizimi yorumu göz ardı edilir.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .PARAMETER
        [string]$ComputerName
    )
    # Verb the Noun on the computer
}

.EXAMPLE

İşlevi veya betiği kullanan örnek bir komut ve isteğe bağlı olarak örnek bir çıktı ile açıklama. Her örnek için bu anahtar sözcüğü yineleyin.

.INPUTS

İşleve veya betike aktarılabilir nesnelerin .NET türleri. Giriş nesnelerinin açıklamasını da ekleyebilirsiniz. Her giriş türü için bu anahtar sözcüğü yineleyin.

.OUTPUTS

Cmdlet'in döndürdüğü nesnelerin .NET türü. Döndürülen nesnelerin açıklamasını da ekleyebilirsiniz. Her çıkış türü için bu anahtar sözcüğü yineleyin.

.NOTES

İşlev veya betik hakkında ek bilgiler.

İlgili bir konunun adı. İlgili her konu için bu anahtar sözcüğü yineleyin. Bu içerik, Yardım konusunun İlgili Bağlantılar bölümünde görünür.

.LINK anahtar sözcük içeriği, aynı yardım konusunun çevrimiçi sürümüne tekdüzen Kaynak Tanımlayıcısı (URI) da içerebilir. Online parametresini kullandığınızda Get-Helpçevrimiçi sürüm açılır. URI veya httpile https başlamalıdır.

.COMPONENT

İşlevin veya betiğin kullandığı veya ilişkili olduğu teknolojinin veya özelliğin adı. Get-Help parametresi, Get-Helptarafından döndürülen arama sonuçlarını filtrelemek için bu değeri kullanır.

.ROLE

Yardım konusu için kullanıcı rolünün adı. Get-Help parametresi, Get-Helptarafından döndürülen arama sonuçlarını filtrelemek için bu değeri kullanır.

.FUNCTIONALITY

İşlevin amaçlanan kullanımını açıklayan anahtar sözcükler. Get-Help parametresi, Get-Helptarafından döndürülen arama sonuçlarını filtrelemek için bu değeri kullanır.

.FORWARDHELPTARGETNAME <Command-Name>

Belirtilen komutun yardım konusuna yönlendirir. Kullanıcıları bir işlev, betik, cmdlet veya sağlayıcı için yardım içeriği dahil olmak üzere herhangi bir yardım konusuna yönlendirebilirsiniz.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

.FORWARDHELPTARGETNAMEiçindeki öğenin yardım kategorisini belirtir. Geçerli değerler Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filterveya All. Aynı ada sahip komutlar olduğunda çakışmaları önlemek için bu anahtar sözcüğü kullanın.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE <PSSession-variable>

Yardım konusunu içeren bir oturum belirtir. PSSession nesnesi içeren bir değişken girin. Bu anahtar sözcük, dışarı aktarılan komutların yardım içeriğini bulmak için Export-PSSession cmdlet'i tarafından kullanılır.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Betik veya işlev için XML tabanlı yardım dosyasını belirtir.

# .EXTERNALHELP <XML Help File>

xml dosyalarında bir işlev veya betik belgelendiğinde .EXTERNALHELP anahtar sözcüğü gereklidir. Bu anahtar sözcük olmadan Get-Help, işlev veya betik için XML tabanlı yardım dosyasını bulamaz.

.EXTERNALHELP anahtar sözcüğü, diğer açıklama tabanlı yardım anahtar sözcüklerinden önceliklidir. .EXTERNALHELP mevcutsa, Get-Help, .EXTERNALHELP anahtar sözcüğünün değerine uyan bir yardım konusu bulamasa bile açıklama tabanlı yardımı göstermez.

İşlev bir modül tarafından dışarı aktarılırsa, .EXTERNALHELP anahtar sözcüğü değerini yolu olmayan bir dosya adı olarak ayarlayın. Get-Help modül dizininin dile özgü bir alt dizininde belirtilen dosya adını arar. bir işlev için XML tabanlı yardım dosyasının adı için herhangi bir gereksinim yoktur. PowerShell 5.0'da başlayarak, modül tarafından dışarı aktarılan işlevler, modül için adlandırılan bir yardım dosyasında belgelenebilir. Açıklama anahtar sözcüğünü kullanmanız .EXTERNALHELP gerekmez. Örneğin, işlev modül tarafından Test-Function dışarı aktarılırsaMyModule, yardım dosyasını MyModule-help.xmlolarak adlandırabilirsiniz. Cmdlet, Get-Help modül dizinindeki Test-Function dosyasındaki işlev için MyModule-help.xml yardım arar.

İşlev bir modüle dahil değilse, XML tabanlı yardım dosyasının yolunu ekleyin. Değer bir yol içeriyorsa ve yol UI kültürüne özgü alt dizinler içeriyorsa Get-Help alt dizinlerde, aynı modül dizininde olduğu gibi, Windows için oluşturulan dil geri dönüş standartlarına uygun olarak betiğin veya işlevin adıyla bir XML dosyası için özyinelemeli olarak arama yapar.

Cmdlet yardımı XML tabanlı yardım dosyası biçimi hakkında daha fazla bilgi için bkz. Cmdlet Yardımı Yazma Yönergeleri.

Otomatik oluşturulan içerik

Ad, söz dizimi, parametre listesi, parametre öznitelik tablosu, ortak parametreler ve açıklamalar Get-Help cmdlet'i tarafından otomatik olarak oluşturulur.

Adı

İşlev yardım konusunun Adı bölümü, işlev söz dizimindeki işlev adından alınır. Betik yardım konusunun Adı betik dosya adından alınır. Adı veya büyük harf kullanımını değiştirmek için işlev söz dizimini veya betik dosya adını değiştirin.

Sözdizimi

Yardım konusunun Sözdizimi bölümü, işlev veya betik söz diziminden oluşturulur. .NET türü gibi parametrelerin detaylarını yardım konusu söz dizimine eklemek için, bu detayları söz dizimine dahil edin. Parametre türü belirtmezseniz, Nesne türü varsayılan değer olarak eklenir.

Parametre listesi

Yardım konu başlığındaki parametre listesi, işlev veya betik söz diziminden ve .PARAMETER anahtar sözcüğü kullanılarak eklediğiniz açıklamalardan oluşturulur. İşlev parametreleri, yardım konusunun Parametreleri bölümünde işlevde veya betik söz diziminde göründükleri sırayla görüntülenir. Parametre adlarının yazım ve büyük harf kullanımı da söz diziminden alınır. .PARAMETER anahtar sözcüğü tarafından belirtilen parametre adından etkilenmez.

Ortak Parametreler

Ortak parametreler, hiçbir etkisi olmasa bile yardım konusunun söz dizimi ve parametre listesine eklenir. Ortak parametreler hakkında daha fazla bilgi için bkz. about_CommonParameters.

Parametre öznitelik tablosu

Get-Help, 'teki Tam veya Get-Help parametresini kullandığınızda görüntülenen parametre öznitelikleri tablosunu oluşturur. Gerekli, Positionve Varsayılan değer özniteliklerinin değeri işlev veya betik söz diziminden alınır.

Varsayılan değerler ve Joker Karakter Kabul için değer, işlevde veya betikte tanımlansalar bile parametre özniteliği tablosunda görünmez. Kullanıcılara yardımcı olmak için parametre açıklamasında bu bilgileri sağlayın.

Açıklamalar

Yardım konusunun Açıklamalar bölümü, işlev veya betik adından otomatik olarak oluşturulur. İçeriğini değiştiremez veya etkileyemezsiniz.

Örnekler

İşlev için Açıklama Tabanlı Yardım

Aşağıdaki örnek işlev açıklama tabanlı yardım içerir:

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 can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Sonuçlar aşağıdaki gibidir:

Get-Help -Name "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 can't pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-Extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

İşlev Söz Diziminde Parametre Açıklamaları

Bu örnek, parametre açıklamalarının işlev söz dizimine eklenmesi dışında öncekiyle aynıdır. Bu biçim en çok açıklamalar kısa olduğunda kullanışlıdır.

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 can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Betik için Yorum Tabanlı Yardım

Aşağıdaki örnek betik, yorum tabanlı yardım içerir. Kapanış #> ile param deyimi arasındaki boş satırlara dikkat edin. param deyimi olmayan bir betikte, yardım konusunun son açıklamasıyla ilk işlev bildirimi arasında en az iki boş satır olmalıdır. Bu boş satırlar olmadan, Get-Help yardım konusunu betikle değil işlevle ilişkilendirir.

<#
.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 can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutputPath)

function Get-Data { }
...

Aşağıdaki komut betik yardımını alır. Betik, $Env:PATH ortam değişkeninde listelenen bir dizinde olmadığından, betik yardımını alan Get-Help komutunun betik yolunu belirtmesi gerekir.

Get-Help -Name .\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 can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath
C:\Reports\2009\January.csv

# RELATED LINKS

XML Dosyasına Yeniden Yönlendirme

İşlevler ve betikler için XML tabanlı yardım içeriği yazabilirsiniz. Açıklama tabanlı yardımın uygulanması daha kolay olsa da, Güncelleştirilebilir Yardım ve birden çok dilde yardım içeriği sağlamak için XML tabanlı yardım gerekir.

Aşağıdaki örnekte, Update-Month.ps1 betiğinin ilk birkaç satırı gösterilmektedir. Betik, .EXTERNALHELP anahtar sözcüğünü kullanarak betiğin XML tabanlı yardım konusunun yolunu belirtir.

.EXTERNALHELP anahtar sözcüğü değerinin anahtar sözcükle aynı satırda göründüğüne dikkat edin. Herhangi bir başka yerleşim yeri etkisizdir.

# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutputPath)
function Get-Data { }
...

Aşağıdaki örneklerde bir işlevdeki .EXTERNALHELP anahtar sözcüğünü üç geçerli yerleşimi gösterilmektedir.

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
}

Farklı Bir Yardım Konusuna Yeniden Yönlendirme

Aşağıdaki kod, PowerShell'deki yerleşik yardım işlevinin başından bir alıntıdır ve her seferinde bir ekran yardım metni görüntüler. Get-Help cmdlet'inin yardım konusu yardım işlevini açıkladığı için, yardım işlevi kullanıcıyı .FORWARDHELPTARGETNAME cmdlet yardım konusuna yönlendirmek için .FORWARDHELPCATEGORY ve Get-Help anahtar sözcüklerini kullanır.

function help {
    <#
    .FORWARDHELPTARGETNAME Get-Help
    .FORWARDHELPCATEGORY Cmdlet
    #>

    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
        [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
        [System.String]
        ${Name},
    ...

Aşağıdaki komut bu özelliği kullanır:

Get-Help -Name help
NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Ayrıca bakınız