about_Functions_Advanced_Methods

  • Makale

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 ve ShouldContinue 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, 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ış 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, endve clean blokları yine 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 CmdletBindingprocess bir işlev oluşturduğunuzda, blok veya $PSItemyerine $_ 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.

clean

Blok clean PowerShell 7.3'e eklendi.

Blokclean, kullanıcıların , processve end bloklarına yayılan kaynakları temizlemesi beginiçin kullanışlı bir yoldur. Bir betik işlevinin veya betik finally cmdlet'inin diğer tüm adlandırılmış bloklarını kapsayan bir bloka 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ı tarafından durdurulduğunda Select-Object -First
  4. işlem hattı Ctrl+c veya StopProcessing()

Dikkat

Bloğu eklemek clean 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 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ı WriteErrorWrite 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.