about_Comment_Based_Help
Kısa açıklama
İşlevler ve betikler için açıklama tabanlı Yardım konularının nasıl yazılacağını açıklar.
Uzun açıklama
Özel yardım açıklaması anahtar sözcüklerini kullanarak işlevler ve betikler için açıklama tabanlı yardım konuları yazabilirsiniz.
Get-Help cmdlet 'ı, XML dosyalarından oluşturulan cmdlet yardım konularını görüntüleyen aynı biçimde açıklama tabanlı yardım görüntüler. Kullanıcılar Get-Help , açıklama tabanlı yardım içeriğini göstermek Için ayrıntılı, tam, örnekler ve çevrimiçi gibi tüm parametrelerini kullanabilir.
Ayrıca, işlevler ve betikler için XML tabanlı yardım dosyaları yazabilirsiniz. Get-HelpCmdlet 'i bir işlev veya betik IÇIN XML tabanlı yardım dosyasını bulmak üzere etkinleştirmek için .ExternalHelp anahtar sözcüğünü kullanın. Bu anahtar sözcük olmadan, Get-Help işlevler ve betikler IÇIN XML tabanlı yardım konuları bulunamıyor.
Bu konuda, işlevler ve betikler için Yardım konularının nasıl yazılacağı açıklanmaktadır. İşlevler ve betikler için yardım konularını görüntüleme hakkında daha fazla bilgi için bkz. Get-Help.
Güncelleştirme-yardım ve Kaydet-yardım cmdlet 'leri yalnızca XML dosyalarında çalışır. Güncelleştirilebilir yardım, açıklama tabanlı yardım konularını desteklemez.
Açıklama tabanlı yardım için sözdizimi
Açıklama tabanlı yardım için sözdizimi aşağıdaki gibidir:
# .<help keyword>
# <help content>
veya
<#
.<help keyword>
<help content>
#>
Açıklama tabanlı yardım, bir dizi yorum olarak yazılmıştır. Her bir açıklama satırının önüne bir yorum sembolü yazabilir # veya <# #> bir açıklama bloğu oluşturmak için ve simgelerini kullanabilirsiniz. Açıklama bloğu içindeki tüm satırlar yorum olarak yorumlanır.
Açıklama tabanlı Yardım konusunun tüm satırları bitişik olmalıdır. Açıklama tabanlı yardım konusu, Yardım konusunun parçası olmayan bir yorumu izliyorsa, son yardım dışı yorum satırı ve 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 sözcüğünün önünde nokta gelir . . Anahtar sözcükler herhangi bir sırada görünebilir. Anahtar sözcük adları büyük/küçük harfe duyarlı değildir.
Örneğin, .Description anahtar sözcüğü bir işlevin veya betiğin açıklamasıyla önce gelir.
<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>
Açıklama bloğunun en az bir anahtar sözcük içermesi gerekir. Gibi bazı anahtar sözcüklerden bazıları .EXAMPLE aynı açıklama bloğunda birçok kez görünebilir. Her anahtar sözcüğünün yardım içeriği, anahtar sözcüğünden sonraki satırda başlar ve birden çok satıra yayılabilir.
İşlevlerde açıklama tabanlı yardım için sözdizimi
Bir işlev için açıklama tabanlı yardım, üç konumdan birinde görünebilir:
- İşlev gövdesinin başlangıcında.
- İşlev gövdesinin sonunda.
functionAnahtar sözcüğünden önce. İşlev yardımı ve anahtar sözcüğünün son satırı arasında birden fazla boş satır olamazfunction.
Örnek:
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 { }
Betiklerdeki açıklama tabanlı yardım için sözdizimi
Komut dosyası için açıklama tabanlı yardım, betikteki aşağıdaki iki konumdan birinde görünebilir.
Betik dosyasının başlangıcında. Betik yardımı öncesinde yalnızca açıklamalar ve boş satırlar tarafından bulunabilir.
Komut dosyası gövdesindeki ilk öğe (yardım sonrası) bir işlev bildirimidir, komut dosyası yardım sonu ve işlev bildirimi arasında en az iki boş satır olmalıdır. Aksi halde, yardım, komut için yardım değil, işlev için yardım olarak yorumlanır.
Komut dosyasının sonunda. Ancak, komut dosyası imzalanmışsa, kod dosyasının başına açıklama tabanlı yardım koyun. Betiğin sonu imza bloğu tarafından kullanılıyor.
Örnek:
<#
.<help keyword>
<help content>
#>
function Get-Function { }
veya
function Get-Function { }
<#
.<help keyword>
<help content>
#>
Betik modüllerinde açıklama tabanlı yardım için sözdizimi
Bir betik modülünde .psm1 , açıklama tabanlı yardım betiklerin sözdizimini değil, işlevleri için sözdizimini kullanır. Betik modülünde tanımlanan tüm işlevler için yardım sağlamak üzere komut dosyası sözdizimini kullanamazsınız.
Örneğin, .ExternalHelp bir betik modülündeki IŞLEVLERIN XML tabanlı yardım dosyalarını tanımlamak için anahtar sözcüğünü kullanıyorsanız, .ExternalHelp her işleve bir açıklama eklemeniz gerekir.
# .ExternalHelp <XML-file-name>
function <function-name>
{
...
}
Açıklama tabanlı Yardım anahtar sözcükleri
Geçerli açıklama tabanlı Yardım anahtar kelimeleri aşağıda verilmiştir. Bunlar, genellikle amaçlanan kullanımları ile birlikte bir yardım konusunda göründükleri sırada listelenir. Bu anahtar sözcükler, açıklama tabanlı yardım 'da herhangi bir sırada görünebilir ve büyük/küçük harfe duyarlı değildir.
.SYNOPSIS
İşlevin veya betiğin kısa bir açıklaması. Bu anahtar sözcük, her konu başlığında yalnızca bir kez kullanılabilir.
.DESCRIPTION
İşlevin veya betiğin ayrıntılı bir açıklaması. Bu anahtar sözcük, her konu başlığında yalnızca bir kez kullanılabilir.
.PARAMETER
Bir parametrenin açıklaması. .PARAMETERİşlev veya betik sözdiziminde her parametre için bir anahtar sözcük ekleyin.
Anahtar sözcüğü ile aynı satıra parametre adını yazın .PARAMETER . Anahtar sözcüğünü izleyen satırlara parametre açıklamasını yazın .PARAMETER . Windows PowerShell, .PARAMETER satır ile sonraki anahtar sözcüğü veya açıklama bloğunun sonundaki tüm metinleri 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özdizimi, parametre (ve açıklamalarının) yardım konusunda görünme sırasını belirler. Sırayı değiştirmek için söz dizimini değiştirin.
Parametre değişkeni adından hemen önce işlev veya betik sözdizimine bir açıklama yerleştirerek bir parametre açıklaması da belirtebilirsiniz. Bunun çalışması için, en az bir anahtar sözcük içeren bir açıklama bloğuna de sahip olmanız gerekir.
Hem bir sözdizimi yorumu hem de .PARAMETER anahtar sözcük kullanırsanız, .PARAMETER anahtar sözcüğüyle ilişkili açıklama kullanılır ve söz dizimi açıklaması yok sayılır.
<#
.SYNOPSIS
Short description here
#>
function Verb-Noun {
[CmdletBinding()]
param (
# This is the same as .Parameter
[string]$Computername
)
# Verb the Noun on the computer
}
.EXAMPLE
İsteğe bağlı olarak örnek çıktı ve açıklama tarafından izlenen işlevi veya betiği kullanan örnek bir komut. Bu anahtar sözcüğü her örnek için tekrarlayın.
.INPUTS
İşleve veya betiğe yönelilelebilir nesnelerin .NET türleri. Giriş nesnelerinin bir açıklamasını da ekleyebilirsiniz.
.OUTPUTS
Cmdlet 'in döndürdüğü nesnelerin .NET türü. Döndürülen nesneler için bir açıklama da ekleyebilirsiniz.
.NOTES
İşlev veya betik hakkında ek bilgiler.
.LINK
İlgili konunun adı. Değer, "" anahtar sözcüğünün altındaki satırda görünür .LINK ve öncesinde bir açıklama simgesi gelmelidir # veya açıklama bloğuna eklenmelidir.
.LINKİlgili her konu için anahtar sözcüğünü tekrarlayın.
Bu içerik Yardım konusunun Ilgili bağlantılar bölümünde görüntülenir.
.LinkAnahtar sözcük içeriği aynı Yardım konusunun çevrimiçi bir sürümüne tek bir Tekdüzen Kaynak tanımlayıcısı (URI) de içerebilir. Çevrimiçi sürümü, ' nin çevrimiçi parametresini kullandığınızda açılır Get-Help . URI "http" veya "https" ile başlamalıdır.
.COMPONENT
İşlevin veya betiğin kullandığı ya da ilişkili olduğu teknolojinin veya özelliğin adı. Öğesinin bileşen parametresi, Get-Help tarafından döndürülen arama sonuçlarını filtrelemek için bu değeri kullanır Get-Help .
.ROLE
Yardım konusu için Kullanıcı rolünün adı. Öğesinin rol parametresi, Get-Help tarafından döndürülen arama sonuçlarını filtrelemek için bu değeri kullanır Get-Help .
.FUNCTIONALITY
İşlevin amaçlanan kullanımını tanımlayan anahtar sözcükler. İşlev parametresi, Get-Help tarafından döndürülen arama sonuçlarını filtrelemek için bu değeri kullanır Get-Help .
.FORWARDHELPTARGETNAME
Belirtilen komut için yardım konusuna yeniden yönlendirir. Kullanıcıları bir işlev, betik, cmdlet veya sağlayıcıya yönelik yardım konuları dahil olmak üzere herhangi bir yardım konusuna yönlendirebilirsiniz.
# .FORWARDHELPTARGETNAME <Command-Name>
.FORWARDHELPCATEGORY
İçindeki öğenin yardım kategorisini belirtir .ForwardHelpTargetName . Geçerli değerler şunlardır,,,,,,, Alias Cmdlet HelpFile Function Provider General FAQ Glossary , ScriptCommand , ExternalScript , Filter veya All . Aynı ada sahip komutlar varsa çakışmaları önlemek için bu anahtar sözcüğünü kullanın.
# .FORWARDHELPCATEGORY <Category>
.REMOTEHELPRUNSPACE
Yardım konusunu içeren bir oturumu belirtir. PSSession nesnesi içeren bir değişken girin. Bu anahtar sözcük, Export-PSSession cmdlet 'i tarafından dışarı aktarılmış komutlara ilişkin yardım konularını bulmak için kullanılır.
# .REMOTEHELPRUNSPACE <PSSession-variable>
.EXTERNALHELP
Betik veya işlev için XML tabanlı yardım dosyasını belirtir.
# .EXTERNALHELP <XML Help File>
.ExternalHelpAnahtar sözcüğü, bir işlev veya BETIK XML dosyalarında belgelendiği zaman gereklidir. Bu anahtar sözcük olmadan, Get-Help işlev veya betik IÇIN XML tabanlı yardım dosyası bulunamıyor.
.ExternalHelpAnahtar sözcüğü, açıklama tabanlı diğer Yardım anahtar kelimelerinin üzerine gelir. Varsa .ExternalHelp , Get-Help anahtar sözcüğünün değeriyle eşleşen bir yardım konusu bulamazsa bile yorum tabanlı yardım görüntülemez .ExternalHelp .
İşlev bir modül tarafından aktarılıyorsa, .ExternalHelp anahtar sözcüğünün değerini yol olmadan bir dosya adına ayarlayın. Get-Help Modül dizininin dile özgü alt dizininde belirtilen dosya adını arar. Bir işlev için XML tabanlı yardım dosyasının adı için bir gereksinim yoktur, ancak en iyi uygulama aşağıdaki biçimi kullanmaktır:
<ScriptModule.psm1>-help.xml
İşlev bir modüle dahil değilse, XML tabanlı yardım dosyasına bir yol ekleyin. değer bir yol içeriyorsa ve yol, uı-kültüre özgü alt dizinler içeriyorsa, Get-Help bir modül dizininde olduğu gibi, Windows için belirlenen dil geri dönüş standartlarına uygun olarak, alt dizinleri, komut dosyası veya işlev adına sahip bir XML dosyası için yinelemeli olarak arar.
Cmdlet yardımı XML tabanlı yardım dosyası biçimi hakkında daha fazla bilgi için bkz. cmdlet yardımı yazma.
Otomatik olarak oluşturulan içerik
Ad, sözdizimi, parametre listesi, parametre öznitelik tablosu, ortak parametreler ve açıklamalar cmdlet tarafından otomatik olarak oluşturulur Get-Help .
Name
İşlev Yardım konusunun ad bölümü işlev sözdiziminde işlev adından alınır. Betik Yardım konusunun adı betik dosya adından alınmıştır. Adı veya büyük/küçük harf durumunu değiştirmek için, işlev sözdizimini veya betik dosya adını değiştirin.
Syntax
Yardım konusunun sözdizimi bölümü, işlev veya betik sözdiziminden oluşturulur. Bir parametre .NET türü gibi yardım konusu söz dizimine ayrıntı eklemek için, söz dizimini sözdizimine ekleyin. Bir parametre türü belirtmezseniz, nesne türü varsayılan değer olarak eklenir.
Parametre Listesi
Yardım konusundaki parametre listesi, işlev veya betik sözdiziminden ve anahtar sözcüğü kullanılarak eklediğiniz açıklamalardan oluşturulur .Parameter . İşlev parametreleri, Yardım konusunun Parametreler bölümünde, işlev veya betik sözdiziminde göründükleri sırada görüntülenir. Parametre adlarının yazım ve büyük harfleri sözdiziminden de alınır. Anahtar sözcüğü tarafından belirtilen parametre adından etkilenmemektedir .Parameter .
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 özniteliği tablosu
Get-Helptam veya parametre parametresini kullandığınızda görüntülenen parametre özniteliklerinin tablosunu oluşturur Get-Help . Gerekli, konum ve varsayılan değer özniteliklerinin değeri, işlev veya betik sözdiziminden alınır.
Varsayılan değerler ve joker karakter kabul eden bir değer, işlev veya betikte tanımlandıklarında bile parametre öznitelik tablosunda görünmez. Kullanıcılara yardımcı olmak için bu bilgileri parametre açıklamasında 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 etkilemezsiniz.
Örnekler
Bir Iş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 cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension
or file name.
.EXAMPLE
PS> extension -name "File"
File.txt
.EXAMPLE
PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
PS> 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 cannot pipe objects to Add-Extension.
OUTPUTS
System.String. Add-Extension returns a string with the extension or
file name.
Example 1
PS> extension -name "File"
File.txt
Example 2
PS> extension -name "File" -extension "doc"
File.doc
Example 3
PS> extension "File" "doc"
File.doc
RELATED LINKS
http://www.fabrikam.com/extension.html
Set-Item
Işlev sözdiziminde parametre açıklamaları
Bu örnek öncekiyle aynıdır, ancak parametre açıklamaları işlev sözdizimine eklenir. Bu biçim, açıklamalar kısa olduğunda en yararlı seçenektir.
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
PS> extension -name "File"
File.txt
.EXAMPLE
PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
PS> extension "File" "doc"
File.doc
.LINK
http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Bir betik için açıklama tabanlı yardım
Aşağıdaki örnek betik, açıklama tabanlı yardım içerir. Kapanış ve ekstre arasındaki boş satırlara dikkat edin #> Param . Bir deyime sahip olmayan bir betikte Param , Yardım konusunun son yorumu ile ilk işlev bildiriminde en az iki boş satır olmalıdır. Bu boş satırlar olmadan Get-Help Yardım konusunu komut dosyası değil 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 cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not 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ı yardımını alır. Betik, ortam değişkeninde listelenen bir dizinde olmadığından $env:Path , komut Get-Help dosyası yardımını alan komut betik yolunu belirtmelidir.
Get-Help -Path .\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
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 yönlendirme
İşlevler ve betikler için XML tabanlı yardım konuları yazabilirsiniz. Açıklama tabanlı yardım 'ın uygulanması daha kolay olsa da, güncelleştirilebilir yardım için XML tabanlı yardım ve birden çok dilde yardım konuları sağlamak için gereklidir.
Aşağıdaki örnekte Update-Month.ps1 betiğinin ilk birkaç satırı gösterilmektedir.
Betiği, .ExternalHelp betiğe yönelik BIR XML tabanlı Yardım konusunun yolunu belirtmek için anahtar sözcüğünü kullanır.
.ExternalHelpAnahtar sözcüğünün değerinin, anahtar sözcüğüyle aynı satırda göründüğünü unutmayın. Diğer tüm yerleştirme etkisiz hale getirilebilir.
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
Aşağıdaki örneklerde .ExternalHelp bir işlevindeki anahtar sözcüğünü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 yönlendirme
Aşağıdaki kod, tek seferde yardım metninin bir ekranını görüntüleyen PowerShell 'deki yerleşik yardım işlevinin başlangıcından itibaren bir alıntıdır.
Get-HelpCmdlet 'in yardım konusu yardım işlevini açıkladığı için yardım işlevi, .ForwardHelpTargetName .ForwardHelpCategory Kullanıcı cmdlet yardım konusuna yeniden yönlendirmek için ve anahtar sözcüklerini kullanır Get-Help .
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.
...