Fonksiyonlar hakkında Gelişmiş Yöntemler

Kısa açıklama

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

Uzun açıklama

CmdletBinding niteliğ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 aynı girdi işleme yöntemleri mevcuttur.
• Bir 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 ThrowTerfacingError yöntemi.
• Farklı türde çıktılar döndüren birkaç Write yöntemi.

PSCmdlet sınıfının tüm yöntemleri ve özellikleri gelişmiş işlevlerde kullanılabilir. Daha fazla bilgi için bkz. System.Management.Automation.PSCmdlet.

CmdletBinding özelliğ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 anlatılan yöntemlere girdi işleme yöntemleri adı verilmektedir. İşlevler için bu üç yöntem, işlevin begin, process ve end bloklarıyla temsil edilir. PowerShell 7.3 bir temiz blok işlem yöntemi ekler.

İşlevlerinizde bu bloklardan herhangi birini kullanmanıza gerek yoktur. Adlandırılmış bir blok kullanmazsanı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 koymalısınız.

Aşağıdaki örnek, tek seferlik ön işleme için bir begin bloğu, çoklu kayıt işleme için bir process bloğu ve bir end bloğu içeren bir fonksiyonun ana hatlarını gösterir. tek seferlik son işlem için blok.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

başla

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ı, bu bloktaki kodu ardışık düzendeki işlevin her örneği için bir kez kullanır.

işlem

Bu blok, işlev için kayıt bazında işlem sağlamak için kullanılır. Bir process bloğunu diğer blokları tanımlamadan kullanabilirsiniz. işlem blok yürütmelerinin sayısı, işlevi nasıl kullandığınıza ve işlevin hangi girdiyi aldığına bağlıdır.

Otomatik değişken $_ veya $PSItem, process bloğunda kullanılmak üzere ardışık düzendeki geçerli nesneyi içerir. $input otomatik değişkeni, yalnızca işlevler ve kod blokları için kullanılabilen bir numaralandırıcı içerir. Daha fazla bilgi için bkz. about_Automatic_Variables.

• İşlevi başlangıçta veya bir işlem hattının dışında çağırmak, process bloğunu bir kez yürütür.
• Bir işlem hattında process bloğu, işleve ulaşan her giriş nesnesi için bir kez yürütülür.

• İşleve ulaşan ardışık düzen girişi boşsa, işlem bloğu yürütülmez.

  • begin, end ve clean blokları çalışmaya devam eder.

İşlem hattı girişini kabul eden ve CmdletBinding kullanan bir işlev oluşturduğunuzda, process bloğunun $_ veya $PSItem. Ö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

son

Bu blok, işlev için isteğe bağlı bir kerelik son işlem sağlamak için kullanılır.

temizle

clean bloğu PowerShell 7.3'e eklendi.

clean bloğu, kullanıcıların begin, process ve end boyunca uzanan kaynakları temizlemesinin kullanışlı bir yoludur. > bloklar. Anlamsal olarak, bir komut dosyası işlevinin veya bir komut dosyası cmdlet'inin tüm diğer adlandırılmış bloklarını kapsayan bir finally bloğuna benzer. Kaynak temizleme aşağıdaki senaryolar için uygulanır:

1. boru hattı yürütmesi hatayı sonlandırmadan normal şekilde tamamlandığında
2. sonlandırma hatası nedeniyle boru hattının yürütülmesi kesintiye uğradığında
3. ardışık düzen Select-Object -First tarafından durdurulduğunda
4. ardışık düzen Ctrl+c veya StopProcessing() tarafından durdurulduğunda

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

Onay yöntemleri

ShouldProcess

Bu yöntem, fonksiyon sistemi değiştirecek bir eylem gerçekleştirmeden önce kullanıcıdan onay istemek için çağrılır. Fonksiyon, metodun döndürdüğü Boolean değerine göre devam edebilir. Bu yöntem yalnızca işlevin Process{ bloğunun içinden çağrılabilir. CmdletBinding özelliği ayrıca işlevin ShouldProcess'i 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ın nasıl isteneceği hakkında daha fazla bilgi için bkz. Onay İsteme.

ShouldContinue

Bu yöntem ikinci bir onay mesajı istemek için çağrılır. ShouldProcess yöntemi $true değerini dö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

Fonksiyonlar hata oluştuğunda iki farklı metodu çağırabilirler. Sonlanmayan bir hata oluştuğunda, işlevin Write yöntemleri bölümünde açıklanan WriteError yöntemini çağırması gerekir. Bir sonlandırma hatası oluştuğunda ve işlev devam edemediğinde ThrowTerfacingError yöntemini çağırmalıdır. Hataları sonlandırmak için Throw deyimini ve sonlanmayan hatalar için Write-Error cmdlet'ini de kullanabilirsiniz.

Daha fazla bilgi için bkz. System.Management.Automation.Cmdlet.ThrowTerfacingError.

Yöntemleri yaz

Bir fonksiyon, farklı çıktı türlerini döndürmek için aşağıdaki yöntemleri çağırabilir. Çıktının tamamının işlem hattındaki bir sonraki komuta gitmediğine dikkat edin. Ayrıca Write-Error gibi çeşitli Write cmdlet'lerini de kullanabilirsiniz.

KomutDetayını Yaz

WriteCommandDetails yöntemi hakkında bilgi için bkz. System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Bir işlevde sorun gidermek amacıyla kullanılabilecek bilgileri sağlamak için işlevin WriteDebug yöntemini çağırmasını sağlayın. WriteDebug yöntemi kullanıcıya hata ayıklama mesajlarını görüntüler. Daha fazla bilgi için bkz. System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Sonlanmayan hatalar oluştuğunda ve işlev kayıtları işlemeye devam edecek şekilde tasarlandığında işlevler bu yöntemi çağırmalıdır. Daha fazla bilgi için bkz. System.Management.Automation.Cmdlet.WriteError.

WriteObject

WriteObject yöntemi, işlevin işlem hattındaki bir sonraki komuta bir 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 zaman alan eylemler içeren işlevler için bu yöntem, işlevin WriteProgress yöntemini çağırmasına ve böylece ilerleme bilgilerinin görüntülenmesine 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östermesi amacıyla WriteVerbose yöntemini çağırmasını sağlayın. Varsayılan olarak ayrıntılı mesajlar 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üleyecek WriteWarning yöntemini çağırmasını sağlayın. Varsayılan olarak uyarı mesajları görüntülenir. Daha fazla bilgi için bkz. System.Management.Automation.PSCmdlet.WriteWarning.

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ılan parametre kümesini görmenize olanak tanır. Parametre setleri, işlev çalıştırıldığında belirtilen parametrelere dayalı olarak farklı görevleri gerçekleştiren bir işlev oluşturmanıza olanak tanır.

Ayrıca bakınız

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Preference_Variables