Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
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, yorum tabanlı yardımı, XML dosyalarından oluşturulan cmdlet yardım içeriğiyle aynı formatta gösterir.
Kullanıcılar, açıklama tabanlı yardımın içeriğini görüntülemek için Ayrıntılı, Get-Help
, Örnekler ve Çevrimiçi gibi tüm parametrelerini kullanabilir.
İş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 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 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ı 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 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 .EXAMPLE
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.
- Anahtar sözcüğünden
function
önce. İşlev yardımının son satırı ilefunction
anahtar 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>
#>
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 açıklama tabanlı yardımda herhangi bir sırayla görünebilir ve büyük/küçük harf duyarlılığı yoktur. 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ü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-Help
kullandığı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-Help
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ı.
role parametresi Get-Help
tarafından Get-Help
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. İşlevsellikparametresi Get-Help
tarafından Get-Help
dö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 içeriği 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 , , , , , , Alias
, Cmdlet
, , HelpFile
, Function
Provider
General
FAQ
veya Glossary
değerleridir.ScriptCommand
ExternalScript
Filter
All
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 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ı 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ı bulamaz.
anahtar .EXTERNALHELP
sözcüğü, diğer açıklama tabanlı yardım anahtar sözcüklerinden önceliklidir.
.EXTERNALHELP
varsa, Get-Help
, .EXTERNALHELP
anahtar sözcüğünün değeriyle 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.
.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
parametresinin Tam veya Parametre parametresini kullandığınızda görüntülenen parametre öznitelikleri Get-Help
tablosunu oluşturur. Gerekli, Konum ve Varsayılan değer özniteliklerinin değeri, işlev veya betik söz diziminden alınır.
Joker karakterleri kabul etme değeri ve varsayılan değerler, işlevde veya betikte tanımlansalar bile, parametre öznitelik 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ği 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 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.
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, 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 .FORWARDHELPTARGETNAME
ve .FORWARDHELPCATEGORY
anahtar sözcüklerini kullanırGet-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.
...
Ayrıca bkz.
PowerShell