about_Comment_Based_Help
Kısa açıklama
İşlevler ve betikler için açıklama tabanlı yardım konularının 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 konuları yazabilirsiniz.
Yardım Al cmdlet'i, açıklama tabanlı yardımı, XML dosyalarından oluşturulan cmdlet yardım konularını görüntülediğ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 Ayrıntılı, Tam, Örnekler ve Çevrimiçi gibi tüm parametrelerini Get-Helpkullanabilir.
İşlevler ve betikler için XML tabanlı yardım dosyaları da yazabilirsiniz. Cmdlet'in Get-Help bir işlev veya betiğin XML tabanlı yardım dosyasını bulmasını sağlamak için anahtar sözcüğünü .ExternalHelp kullanın. Bu anahtar sözcük olmadan, Get-Help işlevler veya betikler için XML tabanlı yardım konularını bulamıyor.
Bu konu başlığı altında, işlevler ve betikler için yardım konularının nasıl yaz olduğu açıklanmaktadır. İşlevler ve betikler için yardım konularının nasıl görüntüleneceği 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 konularını desteklemez.
Açıklama tabanlı yardım için söz dizimi
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 ve #> simgelerini kullanarak bir açıklama bloğu oluşturabilirsiniz<#. 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ı yardım konusu, yardım konusunun parçası olmayan bir açıklamayı izlerse, yardım dışı son 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 sözcüğü, önünde bir nokta .vardır. 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ının önünde yer alır.
<#
.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. gibi .EXAMPLEbazı 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.
- Anahtar sözcüğünden
functionönce. İşlev yardımının son satırı ilefunctionanahtar sözcüğü arasında birden fazla boş satır olamaz.
Örneğin:
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 yardım 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şına Açıklama tabanlı yardım yerleştirin. Betiğin sonu imza bloğu tarafından işgal edilir.
Örneğin:
<#
.<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öz dizimi
Betik modülünde .psm1, açıklama tabanlı yardım, betiklerin söz dizimini değil, işlevler için söz dizimini kullanır. Betik modülünde tanımlanan tüm işlevler için yardım sağlamak için betik söz dizimini kullanamazsınız.
Örneğin, bir betik modülündeki işlevlerin .ExternalHelp XML tabanlı yardım dosyalarını tanımlamak için anahtar sözcüğünü kullanıyorsanız, her işleve bir .ExternalHelp açıklama eklemeniz gerekir.
# .ExternalHelp <XML-file-name>
function <function-name>
{
...
}
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. Bunlar, genellikle amaçlanan kullanımlarıyla birlikte bir yardım konusunda göründükleri sırayla listelenir. Bu anahtar sözcükler açıklama tabanlı yardımda 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 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ük ekleyin.
Anahtar sözcükle aynı satıra .PARAMETER parametre adını yazın. Anahtar sözcüğünü izleyen .PARAMETER satırlara parametre açıklamasını yazın. Windows PowerShell, satır ile sonraki anahtar sözcük veya açıklama bloğunun sonu arasındaki .PARAMETER 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 söz dizimi açıklaması hem .PARAMETER de anahtar sözcük kullanırsanız, anahtar sözcükle .PARAMETER ilişkili açıklama kullanılır ve söz dizimi açıklaması yoksayı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
İşlevi veya betiği kullanan örnek bir komut, isteğe bağlı olarak örnek çıktı ve 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.
.OUTPUTS
Cmdlet'in döndürdüğü nesnelerin .NET türü. Döndürülen nesnelerin açıklamasını da ekleyebilirsiniz.
.NOTES
İşlev veya betik hakkında ek bilgiler.
.LINK
İlgili bir konunun adı. Değer, ".LINK" anahtar sözcüğün altındaki satırda görünür ve önünde bir açıklama simgesi # bulunmalıdır veya açıklama bloğuna eklenmelidir.
.LINK İlgili her konu için anahtar sözcüğünü yineleyin.
Bu içerik, yardım konusunun İlgili Bağlantılar bölümünde görünür.
Anahtar .Link 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. Çevrimiçi sürüm, çevrimiçi parametresini Get-Helpkullandığınızda açılır. URI"nin "http" veya "https" ile başlaması gerekir.
.COMPONENT
İşlevin veya betiğin kullandığı veya ilişkili olduğu teknolojinin veya özelliğin adı. bileşeni parametresi Get-Help tarafından Get-Helpdö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ı. role parametresi Get-Help tarafından Get-Helpdö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. İşlevsellikparametresi Get-Help tarafından Get-Helpdöndürülen arama sonuçlarını filtrelemek için bu değeri kullanır.
.FORWARDHELPTARGETNAME
Belirtilen komutun yardım konusuna yönlendirir. Kullanıcıları bir işlev, betik, cmdlet veya sağlayıcı için yardım konuları dahil olmak üzere herhangi bir yardım konusuna yönlendirebilirsiniz.
# .FORWARDHELPTARGETNAME <Command-Name>
.FORWARDHELPCATEGORY
içindeki .ForwardHelpTargetNameöğenin yardım kategorisini belirtir. Geçerli değerler , , , , , , Provider, General, , FAQ, ScriptCommandGlossaryExternalScriptFilterveya Alldeğerleridir.AliasFunctionHelpFileCmdlet Aynı ada sahip komutlar olduğunda çakışmaları önlemek için bu anahtar sözcüğü kullanın.
# .FORWARDHELPCATEGORY <Category>
.REMOTEHELPRUNSPACE
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 konularını bulmak için Export-PSSession cmdlet'i tarafından kullanılır.
# .REMOTEHELPRUNSPACE <PSSession-variable>
.EXTERNALHELP
Betik veya işlev için XML tabanlı bir yardım dosyası belirtir.
# .EXTERNALHELP <XML Help File>
Bir .ExternalHelp işlev veya betik XML dosyalarında belgelendiğinde anahtar sözcük gereklidir. Bu anahtar sözcük olmadan, Get-Help işlev veya betik için XML tabanlı yardım dosyasını bulamıyor.
anahtar .ExternalHelp sözcüğü, diğer açıklama tabanlı yardım anahtar sözcüklerinden önceliklidir. Varsa .ExternalHelp , Get-Help anahtar sözcüğün değeriyle .ExternalHelp eşleşen bir yardım konusu bulamasa bile açıklama tabanlı yardımı görüntülemez.
İşlev bir modül tarafından dışarı aktarılıyorsa, anahtar sözcüğün .ExternalHelp 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, ancak en iyi yöntem aşağıdaki biçimi kullanmaktır:
<ScriptModule.psm1>-help.xml
İş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 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 alt dizinlerde arama yapar.
Cmdlet yardımı XML tabanlı yardım dosyası biçimi hakkında daha fazla bilgi için bkz . How to Write Cmdlet Help.
Otomatik oluşturulan içerik
Ad, söz dizimi, parametre listesi, parametre öznitelik tablosu, ortak parametreler ve açıklamalar cmdlet tarafından Get-Help otomatik olarak oluşturulur.
Veri Akışı 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öz dizimi bölümü, işlev veya betik söz diziminden oluşturulur. Parametrenin .NET türü gibi yardım konusu söz dizimine ayrıntı eklemek için söz dizimine ayrıntıyı ekleyin. 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 anahtar sözcüğünü kullanarak .Parameter eklediğiniz açıklamalardan oluşturulur. İşlev parametreleri, yardım konusunun Parametreler 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. Anahtar sözcüğü tarafından belirtilen parametre adından .Parameter 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-Helpparametresinin Tam veya Parametre parametresini kullandığınızda görüntülenen parametre öznitelikleri Get-Helptablosunu oluşturur. Gerekli, Konum ve 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 Et değerleri, 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 değiştiremezsiniz.
Ö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 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
İş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 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
#>
}
Betik için Açıklama Tabanlı Yardım
Aşağıdaki örnek betik, açıklama tabanlı yardım içerir. Kapanış #> ve deyim arasındaki boş satırlara Param dikkat edin. Deyimi olmayan bir Param 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 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 betik yardımını alır. Betik, ortam değişkeninde listelenen bir dizinde $env:Path olmadığından, Get-Help betik yardımını alan komutun 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 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 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, Güncelleştirilebilir Yardım ve birden çok dilde yardım konuları 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, betiğin .ExternalHelp XML tabanlı yardım konusunun yolunu belirtmek için anahtar sözcüğünü kullanır.
Anahtar sözcüğün değerinin .ExternalHelp anahtar sözcükle aynı satırda göründüğünü unutmayın. Diğer yerleşimler etkisizdir.
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
Aşağıdaki örneklerde bir işlevde anahtar sözcüğün .ExternalHelp üç 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.
Cmdlet'in yardım konusu yardım işlevini açıkladığı içinGet-Help, yardım işlevi kullanıcıyı cmdlet yardım konusuna yönlendirmek için Get-Help ve .ForwardHelpCategory anahtar sözcüklerini kullanır.ForwardHelpTargetName.
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 bkz.
PowerShell
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin