about_Functions_Advanced_Methods

Kısa açıklama

CmdletBinding özniteliğini belirten işlevlerin derlenmiş cmdlet'ler için kullanılabilen yöntemleri ve özellikleri nasıl kullanabileceğini açıklar.

Uzun açıklama

CmdletBinding özniteliğini belirten işlevler, $PSCmdlet değişkeni aracılığıyla ek yöntemlere ve özelliklere 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 gerçekleştirilmeden önce kullanıcı geri bildirimi almak için kullanılan ShouldProcess ve ShouldContinue yöntemleri.
  • Hata kayıtları oluşturmak için ThrowTerminatingError yöntemi.
  • Farklı çıkış türleri döndüren çeşitli Write yöntemleri.

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.

CmdletBinding özniteliği hakkında 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, processve end bloklarıyla temsil edilir. PowerShell 7.3 bir clean blok işlemi yöntemi ekler.

İşlevlerinizde bu bloklardan herhangi birini kullanmanız gerekmez. Adlandırılmış 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 bloğu tanımlarsanız, tüm kodu adlandırılmış bir bloğa yerleştirmeniz gerekir.

Aşağıdaki örnek, tek seferlik ön işleme için begin bloğu, birden çok kayıt işleme için process bloğu ve tek seferlik işlem sonrası için end bloğu içeren bir işlevin ana hattını gösterir.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Not

Bu bloklar yalnızca CmdletBinding özniteliğini kullanan işlevler için değil, tüm işlevler için 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 bloğu kullanabilirsiniz. process blok yürütmelerinin sayısı, işlevi nasıl kullandığınıza ve işlevin hangi girişi aldığına bağlıdır.

$_ veya $PSItem otomatik değişkeni, process bloğunda kullanılmak üzere işlem hattındaki 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, process bloğunu bir kez yürütür.
  • bir işlem hattı içinde, işleve ulaşan her giriş nesnesi için process bloğu bir kez yürütülür.
  • İşleve ulaşan işlem hattı girişi boşsa, process bloğu yürütmez.
    • begin, endve clean blokları hala yürütülür.

Önemli

İşlev parametresi işlem hattı girişini kabul edecek şekilde ayarlanırsa ve process bloğu tanımlanmamışsa, kayıt kaydı 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 CmdletBindingkullanan bir işlev oluşturduğunuzda, process bloğu $_ veya $PSItemyerine işlem hattı girişi için tanımladığınız parametre değişkenini kullanmalıdır. Mesela:

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.

clean

clean bloğu PowerShell 7.3'e eklendi.

clean bloğu, kullanıcıların begin, processve end bloklarına yayılan kaynakları temizlemesi için kullanışlı bir yoldur. Bir betik işlevinin veya betik cmdlet'inin diğer tüm adlandırılmış bloklarını kapsayan finally bloğuna benzer. Kaynak temizleme aşağıdaki senaryolar için zorunlu kılındı:

  1. işlem hattı yürütmesi sonlandırılmadan normal şekilde tamamlandığında hata
  2. sonlandırma hatası nedeniyle işlem hattı yürütmesi kesintiye uğradığında
  3. işlem hattı Select-Object -First tarafından durdurulduğunda
  4. işlem hattı Ctrl+c veya StopProcessing() tarafından durdurulduğunda

Temiz blok, Success akışına yazılan tüm çıktıları atar.

Dikkat

clean bloğunun eklenmesi hataya neden olan bir değişikliktir. clean Anahtar sözcük olarak ayrıştırıldığından, kullanıcıların betik bloğundaki ilk deyim olarak adlandırılan clean bir komutu doğrudan çağırmasını engeller. Ancak, büyük olasılıkla bir sorun olmayacaktır. Komut hala çağrı işleci (& clean) kullanılarak çağrılabilir.

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 process {} bloğu içinden çağrılabilir. CmdletBinding özniteliği, işlevin ShouldProcess desteklediğini 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 isteme .

ShouldContinue

Bu yöntem, ikinci bir onay iletisi istemek için çağrılır. ShouldProcess yöntemi $truedöndürdüğünde ç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ıcı olmayan bir hata oluştuğunda, işlevin WriteError yöntemleri bölümünde açıklanan Write yöntemini çağırması gerekir. Sonlandırma hatası oluştuğunda ve işlev devam edemiyorsa, ThrowTerminatingError yöntemini çağırması gerekir. Ayrıca hataları sonlandırmak için throw deyimini ve sonlandırmayan hatalar için Yazma Hatası 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. Writegibi çeşitli Write-Error cmdlet'lerini de kullanabilirsiniz.

WriteCommandDetail

WriteCommandDetails yöntemi hakkında 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şlevin WriteDebug yöntemini çağırmasını sağlayın. WriteDebug yöntemi kullanıcıya 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şlevin ThrowTerminatingError yöntemini çağırması gerekir.

WriteObject

WriteObject yöntemi, işlevin işlem hattındaki bir sonraki komuta nesne göndermesine olanak tanır. Çoğu durumda, WriteObject işlevi 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 WriteVerbose yöntemini çağırmasını 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

Uyarı iletilerini, $WarningPreference değişkenini yapılandırarak veya Verbose ve Debug komut satırı seçeneklerini kullanarak da görüntüleyebilirsiniz. $WarningPreference değişkeni hakkında daha fazla bilgi için bkz. about_Preference_Variables.

Diğer yöntemler ve özellikler

$PSCmdlet değişkeni aracılığıyla 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 bakınız

  • Last updated on