Açıklama Tabanlı Yardım Örnekleri

Makale
2025-03-25

Bu konu, betikler ve işlevler için açıklama tabanlı yardımın nasıl kullanılacağını gösteren örnekler içerir.

Örnek 1: İşlev için Açıklama Tabanlı Yardım

Aşağıdaki örnek işlev açıklama tabanlı Yardım'a sahiptir.

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
        Online version: http://www.fabrikam.com/add-extension.html

        .LINK
        Set-Item
    #>
}

Aşağıdaki çıktıda, Add-Extension işlevinin yardımını görüntüleyen bir Get-Help komutunun sonuçları gösterilir.

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 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
    Online version: http://www.fabrikam.com/add-extension.html
    Set-Item

Örnek 2: Betik için Açıklama Tabanlı Yardım

Aşağıdaki örnek işlev açıklama tabanlı Yardım'a sahiptir.

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 betik yerine işleviyle 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, Yardım betiğini alır. Betik PATH ortam değişkeninde listelenen bir dizinde olmadığından, Betik Yardımı'nı alan Get-Help komutunun betik yolunu belirtmesi gerekir.

PS> Get-Help C:\ps-test\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

Örnek 3: `param` Deyimindeki Parametre Açıklamaları

Bu örnek, bir işlevin veya betiğin param deyimine parametre açıklamalarının nasıl ekleyebileceğinizi gösterir. Bu biçim en çok parametre 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.
...
    #>
}

Sonuçlar, Örnek 1 sonuçlarıyla aynıdır. Get-Help, parametre açıklamalarını .PARAMETER anahtar sözcüğüyle birlikteymiş gibi yorumlar.

Örnek 4: XML Dosyasına Yeniden Yönlendirme

İşlevler ve betikler için XML tabanlı Yardım konuları yazabilirsiniz. Açıklama tabanlı Yardım'ın uygulanması daha kolay olsa da, Yardım içeriği üzerinde daha hassas bir denetim istiyorsanız veya Yardım konularını birden çok dile çeviriyorsanız XML tabanlı Yardım gereklidir. 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 C:\MyScripts\Update-Month-Help.xml

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

    function Get-Data { }

Aşağıdaki örnekte bir işlevde .EXTERNALHELP anahtar sözcüğü kullanımı gösterilmektedir.

function Add-Extension
{
    param ([string]$Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name

    # .EXTERNALHELP C:\ps-test\Add-Extension.xml
}

Örnek 5: Farklı Bir Yardım Konusuna Yeniden Yönlendirme

Aşağıdaki kod, PowerShell'deki yerleşik help 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ı Get-Help cmdlet Yardım konusuna yönlendirmek için .FORWARDHELPTARGETNAME ve .FORWARDHELPCATEGORY 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. Kullanıcı help işlevi için bir Get-Help komutu yazdığınızda, Get-HelpGet-Help cmdlet'i için Yardım konusunu görüntüler.

PS> Get-Help help

NAME
    Get-Help

SYNOPSIS
    Displays information about Windows PowerShell cmdlets and concepts.
...

Aracılığıyla paylaş