Yoruma Dayalı Yardım Örnekleri

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

Örnek 1: Bir İşlev için Yoruma Dayalı Yardım

Aşağıdaki örnek işlev, yoruma dayalı 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
        Online version: http://www.fabrikam.com/add-extension.html

        .LINK
        Set-Item
    #>
}

Aşağıdaki çıktı, Add-Extension işlevine ilişkin yardımı görüntüleyen Get-Help komutunun sonuçlarını gösterir.

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: Bir Komut Dosyası için Yoruma Dayalı Yardım

Aşağıdaki örnek işlev, yoruma dayalı Yardım'ı içerir.

#> kapanışı ile Param ifadesi arasındaki boş satırlara dikkat edin. Param ifadesi olmayan bir komut dosyasında, Yardım konusundaki son açıklama ile 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 komut dosyası yerine 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 komut dosyasının Yardımını alır. Betik, Yol 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 İfadesindeki Parametre Açıklamaları

Bu örnek, bir işlevin veya betiğin Param ifadesine parametre açıklamalarının nasıl ekleneceğini gösterir. Bu format, parametre açıklamaları kısa olduğunda en 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'in sonuçlarıyla aynıdır. Get-Help, parametre açıklamalarını sanki .Parameter anahtar sözcüğü eşlik ediyormuş gibi yorumlar.

Örnek 4: XML Dosyasına Yönlendirme

İşlevler ve komut dosyaları için XML tabanlı Yardım konuları yazabilirsiniz. Yorum tabanlı Yardım'ın uygulanması daha kolay olsa da, Yardım içeriği üzerinde daha hassas kontrol istiyorsanız veya Yardım konularını birden çok dile çeviriyorsanız XML tabanlı Yardım gereklidir. Aşağıdaki örnek, Güncelleme'nin ilk birkaç satırını gösterir. -Month.ps1 komut dosyası. Betik, betiğin XML tabanlı Yardım konusunun yolunu belirtmek için .ExternalHelp anahtar sözcüğünü kullanır.

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

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

    function Get-Data { }

Aşağıdaki örnek, bir işlevde .ExternalHelp anahtar sözcüğünün kullanımını gösterir.

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 Yönlendirme

Aşağıdaki kod, PowerShell'de aynı anda bir Yardım metni ekranı görüntüleyen yerleşik Yardım işlevinin başlangıcından bir alıntıdır. Get-Help cmdlet'inin Yardım konusu Yardım işlevini açıkladığından, Yardım işlevi kullanıcıyı Get-Help cmdlet'ine yönlendirmek için .ForwardHelpTargetName ve .ForwardHelpCategory anahtar sözcüklerini kullanır. Yardım konusu.

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. Bir kullanıcı Help işlevi için bir Get-Help komutu yazdığında, Get-Help, Get-Help için Yardım konusunu görüntüler. cmdlet'i.

PS> get-help help

NAME
    Get-Help

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