about_Functions_Advanced_Methods
Kısa açıklama
Özniteliğini belirten işlevlerin CmdletBinding
derlenmiş cmdlet'ler için kullanılabilen yöntemleri ve özellikleri nasıl kullanabileceğini açıklar.
Uzun açıklama
özniteliğini CmdletBinding
belirten işlevler, değişkeni aracılığıyla ek yöntemlere ve özelliklere $PSCmdlet
erişebilir. Bu yöntemler aşağıdaki yöntemleri içerir:
- Tüm işlevler için kullanılabilen aynı giriş işleme yöntemleri.
- Eylem
ShouldProcess
gerçekleştirilmeden önce kullanıcı geri bildirimi almak için kullanılan veShouldContinue
yöntemleri. ThrowTerminatingError
Hata kayıtları oluşturma yöntemi.- Farklı çıkış türleri döndüren çeşitli
Write
yöntemler.
PSCmdlet sınıfının tüm yöntemleri ve özellikleri gelişmiş işlevler tarafından kullanılabilir. Daha fazla bilgi için bkz . System.Management.Automation.PSCmdlet.
Özniteliği hakkında CmdletBinding
daha fazla bilgi için bkz . about_Functions_CmdletBindingAttribute. CmdletBindingAttribute sınıfı için bkz. System.Management.Automation.Cmdlet.CmdletBindingAttribute.
Giriş işleme yöntemleri
Bu bölümde açıklanan yöntemler giriş işleme yöntemleri olarak adlandırılır. İşlevler için, bu üç yöntem işlevin begin
, process
ve end
bloklarıyla temsil edilir.
İşlevlerinizde bu bloklardan herhangi birini kullanmanız gerekmez. Adlandırılmış bir blok kullanmıyorsanız PowerShell kodu işlevin end
bloğuna yerleştirir. Ancak, bu adlandırılmış bloklardan herhangi birini kullanırsanız veya bir dynamicparam
blok tanımlarsanız, tüm kodu adlandırılmış bir bloğun içine yerleştirmeniz gerekir.
Aşağıdaki örnek, bir kerelik ön işleme için bir begin
blok, birden çok kayıt işleme için bir process
blok ve tek seferlik işlem sonrası için bir blok içeren bir end
işlevin ana hattını gösterir.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
begin{}
process{}
end{}
}
Not
Bu bloklar yalnızca özniteliğini kullanan işlevler için değil, tüm işlevler için CmdletBinding
geçerlidir.
begin
Bu blok, işlev için isteğe bağlı bir kerelik ön işleme sağlamak için kullanılır. PowerShell çalışma zamanı, işlem hattındaki işlevin her örneği için bu bloktaki kodu bir kez kullanır.
process
Bu blok, işlev için kayıt kaydı işleme sağlamak için kullanılır. Diğer blokları tanımlamadan bir process
blok kullanabilirsiniz. Blok yürütmelerinin process
sayısı, işlevi nasıl kullandığınıza ve işlevin hangi girişi aldığına bağlıdır.
Otomatik değişken $_
veya $PSItem
blokta kullanılmak üzere işlem hattındaki process
geçerli nesneyi içerir. Otomatik $input
değişken, yalnızca işlevler ve betik blokları için kullanılabilen bir numaralandırıcı içerir.
Daha fazla bilgi için bkz . about_Automatic_Variables.
- İşlevi bir işlem hattının başında veya dışında çağırmak bloğu bir kez yürütür
process
. - bir işlem hattı içinde, işleve
process
ulaşan her giriş nesnesi için blok bir kez yürütülür. - İşleve ulaşan işlem hattı girişi boşsa,
process
blok yürütülmüyordur .begin
veend
blokları hala yürütülür.
Önemli
İşlev parametresi işlem hattı girişini kabul edecek şekilde ayarlanırsa ve bir process
blok tanımlanmamışsa, kayda göre kayıt işleme başarısız olur. Bu durumda, işleviniz giriş ne olursa olsun yalnızca bir kez yürütülür.
İşlem hattı girişini kabul eden ve kullanan CmdletBinding
process
bir işlev oluşturduğunuzda, blok veya $PSItem
yerine $_
işlem hattı girişi için tanımladığınız parametre değişkenini kullanmalıdır. Örneğin:
function Get-SumOfNumbers {
[CmdletBinding()]
param (
[Parameter(Mandatory, Position=0, ValueFromPipeline)]
[int[]]$Numbers
)
begin { $retValue = 0 }
process {
foreach ($n in $Numbers) {
$retValue += $n
}
}
end { $retValue }
}
PS> Get-SumOfNumbers 1,2,3,4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10
end
Bu blok, işlev için isteğe bağlı bir kerelik işlem sonrası sağlamak için kullanılır.
Onay yöntemleri
ShouldProcess
Bu yöntem, işlev sistemi değiştirecek bir eylem gerçekleştirmeden önce kullanıcıdan onay istemek için çağrılır. İşlev, yöntemi tarafından döndürülen Boole değerini temel alarak devam edebilir. Bu yöntem yalnızca işlevin bloğu içinden Process{}
çağrılabilir. özniteliği, CmdletBinding
işlevin desteklediğini ShouldProcess
de bildirmelidir (önceki örnekte gösterildiği gibi).
Bu yöntem hakkında daha fazla bilgi için bkz . System.Management.Automation.Cmdlet.ShouldProcess.
Onay isteme hakkında daha fazla bilgi için bkz . Onay İsteme.
ShouldContinue
Bu yöntem, ikinci bir onay iletisi istemek için çağrılır. yöntemi döndürdüğünde ShouldProcess
$true
çağrılmalıdır. Bu yöntem hakkında daha fazla bilgi için bkz . System.Management.Automation.Cmdlet.ShouldContinue.
Hata yöntemleri
İşlevler, hatalar oluştuğunda iki farklı yöntemi çağırabilir. Sonlandırılmayan bir hata oluştuğunda, işlevin yöntemler bölümünde açıklanan yöntemini çağırması WriteError
Write
gerekir. Sonlandırma hatası oluştuğunda ve işlev devam edemiyorsa yöntemini çağırması ThrowTerminatingError
gerekir. Ayrıca, hataları sonlandırmak için deyimini Throw
ve sonlandırılmayan hatalar için Write-Error cmdlet'ini de kullanabilirsiniz.
Daha fazla bilgi için bkz . System.Management.Automation.Cmdlet.ThrowTerminatingError.
Yazma yöntemleri
İşlev, farklı çıkış türleri döndürmek için aşağıdaki yöntemleri çağırabilir.
Tüm çıkışın işlem hattında sonraki komuta geçmediğine dikkat edin. Gibi Write-Error
çeşitli Write
cmdlet'leri de kullanabilirsiniz.
WriteCommandDetail
yöntemi hakkında WriteCommandDetails
bilgi için bkz . System.Management.Automation.Cmdlet.WriteCommandDetail.
WriteDebug
Bir işlevin sorunlarını gidermek için kullanılabilecek bilgiler sağlamak için işlevinin yöntemini çağırmasını WriteDebug
sağlayın. yöntemi kullanıcıya WriteDebug
hata ayıklama iletilerini görüntüler. Daha fazla bilgi için bkz . System.Management.Automation.Cmdlet.WriteDebug.
WriteError
sonlandırıcı olmayan hatalar oluştuğunda ve işlev kayıtları işlemeye devam etmek için tasarlandıysa işlevler bu yöntemi çağırmalıdır. Daha fazla bilgi için bkz . System.Management.Automation.Cmdlet.WriteError.
Not
Sonlandırıcı bir hata oluşursa işlev ThrowTerminatingError yöntemini çağırmalıdır.
WriteObject
yöntemi, WriteObject
işlevin işlem hattında bir sonraki komuta nesne göndermesine olanak tanır. Çoğu durumda, WriteObject
işlev veri döndürdüğünde kullanılacak yöntemdir. Daha fazla bilgi için bkz . System.Management.Automation.PSCmdlet.WriteObject.
WriteProgress
Tamamlanması uzun süren eylemlere sahip işlevler için bu yöntem, ilerleme bilgilerinin görüntülenmesi için işlevin WriteProgress
yöntemini çağırmasına olanak tanır. Örneğin, tamamlanan yüzdeyi görüntüleyebilirsiniz.
Daha fazla bilgi için bkz . System.Management.Automation.PSCmdlet.WriteProgress.
WriteVerbose
İşlevin ne yaptığı hakkında ayrıntılı bilgi sağlamak için, işlevin kullanıcıya ayrıntılı iletiler görüntülemesi için yöntemini çağırmasını WriteVerbose
sağlayın. Varsayılan olarak ayrıntılı iletiler görüntülenmez. Daha fazla bilgi için bkz . System.Management.Automation.PSCmdlet.WriteVerbose.
WriteWarning
Beklenmeyen sonuçlara neden olabilecek koşullar hakkında bilgi sağlamak için işlevin kullanıcıya uyarı iletileri görüntülemek için WriteWarning yöntemini çağırmasını sağlayın. Varsayılan olarak uyarı iletileri görüntülenir. Daha fazla bilgi için bkz . System.Management.Automation.PSCmdlet.WriteWarning.
Not
Ayrıca, değişkeni yapılandırarak $WarningPreference
veya ve Debug
komut satırı seçeneklerini kullanarak Verbose
uyarı iletilerini görüntüleyebilirsiniz. değişken hakkında $WarningPreference
daha fazla bilgi için bkz . about_Preference_Variables.
Diğer yöntemler ve özellikler
değişkeni aracılığıyla $PSCmdlet
erişilebilen diğer yöntemler ve özellikler hakkında bilgi için bkz . System.Management.Automation.PSCmdlet.
Örneğin ParameterSetName özelliği, kullanılmakta olan parametre kümesini görmenize olanak tanır. Parametre kümeleri, işlev çalıştırıldığında belirtilen parametrelere göre farklı görevler gerçekleştiren bir işlev oluşturmanıza olanak tanır.
Ayrıca bkz.
PowerShell
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Ç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.Gönderin ve geri bildirimi görüntüleyin