PowerShell ValidateScript ile Parametreleri Doğrulama [İzlenecek Yol]

PowerShell işlevleri oluştururken parametrelere yapılan girişi doğrulamak önemlidir. Parametre doğrulama, işlevlere iletilenleri sınırlamanıza olanak tanır. Bu makalede, sorunları PowerShell ValidateScript doğrulama özelliğiyle bütünleşmeden önce nasıl yakalayacağınızı öğreneceksiniz.

Parametre doğrulamayı kullanarak, yalnızca işlev çalıştırıldığında sorunların ortaya çıkmamasını sağlamakla kalmaz, aynı zamanda doğrulama mantığı işlevin gövdesine yerleştirilmediğinden daha temiz kodu da desteklersiniz.

Powershell'de çeşitli gelişmiş parametre doğrulama özellikleri mevcuttur. Ancak bu makalede en esnek parametre doğrulamalarından biri olan PowerShell ValidateScript doğrulamasını öğreneceksiniz.

Nasıl çalıştığını göreceksiniz ve nasıl kullanılacağına dair örnekleri de göreceksiniz.

Parametre Doğrulaması (Bir Analoji)

Öğle yemeği yiyordum ve birdenbire soda içmek istedim. Gazoz makinesinin yanına gittim, cebimden 100 sterlinlik bir banknot çıkardım ve banknot yuvasına soktum. Makine hemen tükürür.

Daha sonra yuvanın hemen üstünde yalnızca 20₱ ve 50₱ tutarındaki banknotları kabul ettiğinin yazdığını fark ettim. Yanımda sadece 100 sterlinlik fatura olduğu için soda alamadım.

Hikayenin PowerShell parametre doğrulamasıyla nasıl bir ilişkisi var? Hadi parçalayalım.

  • Soda makinesi şu işlevi görür:
  • Fatura parametredir
  • ₱50 ve ₱20 banknotları geçerli parametre değerleridir
  • ₱100 yanlış parametre değeri olduğundan reddedildi
  • Sonuç olarak makine, yanlış giriş nedeniyle isteğimi işleme koymadı. Bu yüzden bana soda yok. ….ve ben de susadım!

Yukarıdaki soda makinesi senaryosu, parametre doğrulama kavramını açıklayan bir benzetmedir.

Parametre Doğrulama Mantık Akışı

Parametre doğrulama kavramı kaba bir iş akışını takip eder. Aşağıdaki resimde parametre doğrulamanın nasıl çalıştığına ilişkin bir genel bakış gösterilmektedir.

  1. İşlev, PowerShell'de adını çağırarak ve parametre değerlerini sağlayarak yürütülür.
  2. PowerShell sağlanan değerleri değerlendirir.
  3. Doğrulamanın sonucu doğruysa PowerShell, fonksiyonun çıkmadan önce işlemine devam etmesine izin verecektir.
  4. Doğrulamanın sonucu yanlışsa PowerShell bir hata görüntüleyecek ve işlev sonlandırılacaktır.

İzlenecek Yol Gereksinimleri

PowerShell işlevi parametre doğrulamasından bahsetmenin ötesinde, bu makalenin geri kalanında kendi başınıza kopyalayıp deneyebileceğiniz örnekler bulunacaktır. Takip etmek için takip etmeniz gereken birkaç şeye ihtiyacınız olacak.

  • Aşağıdaki PowerShell sürümlerinden herhangi birine sahip bir Windows 10 bilgisayarı:
  • Windows PowerShell 5.1
  • PowerShell Çekirdeği 6.2
  • PowerShell Core 7 (bu yazının en son sürümü Önizleme 4'tür)
  • Seçtiğiniz bir senaryo editörü. Notepad++, PowerShell ISE veya Visual Studio Code gibi.

ValidateScript Doğrulama Özelliğini Anlamak

ValidateScript, PowerShell 3.0'da kullanıma sunulan PowerShell'de kullanılabilen parametre doğrulama özniteliklerinden biridir. Bir işlevin parametre tanımlama bloğunun içine eklenebilir veya doğrudan PowerShell konsolunda da kullanılabilir.

ValidateScript girdiğiniz parametrenin değerini doğrulamak için kullanılır. Doğrulama sonucu $true ise komut dosyası çalışmaya devam eder. Öte yandan, sonuç $false ise işlev bir sonlandırma hatası verecektir.

Gelin derinlemesine inceleyelim ve nasıl çalıştığını görelim.

ValidateScript'i bir İşlevde Kullanma

ValidateScript özelliğinin en yaygın kullanımı, bir işlev parametresine eklenir. Bu bölümde yapay bir işlev oluşturacak ve ValidateScript parametre doğrulamasını uygulayacaksınız.

Sahte işlev aşağıdaki eylemleri gerçekleştirecektir:

  1. Tutar girişini kabul edin.
  2. Girilen tutarın kabul edilen değerlere eşit olup olmadığını doğrulayın.
  3. Doğrulama başarılı olursa işlemi çalıştırın.
  4. Doğrulama başarısız olursa bir hata görüntüle.

Bir sonraki bölümde bu fonksiyonun adım adım nasıl oluşturulacağını öğreneceksiniz. Betik düzenleyicinizi çalıştırın ve kodlamaya başlayın!

İşlevi Oluşturun

Öncelikle bir fonksiyon oluşturalım ve ona bir isim verelim. Bu seçtiğiniz herhangi bir isim olabilir. İşlevinizi açıklayıcı hale getirmek için Fiil-İsim adlandırma kuralını takip etmek en iyi uygulamadır. Bu örnek için Get-Soda adını kullanın.

Function Get-Soda {
    [CmdletBinding()]
    param ()
}

param() bloğunun içine kullanacağınız parametrenin adını girin: Bill.

Function Get-Soda {
    [CmdletBinding()]
    param ( 
        $Bill
    )
}

Bu noktada fonksiyon Bill parametresine herhangi bir değer kabul etmekten başka bir şey yapmıyor.

Get-Soda işlevini PowerShell konsolunuza kopyaladığınızdan emin olun. İşlev PowerShell oturumuna aktarıldıktan sonra şu komutu çalıştırarak işlevi test edin: Get-Soda -Bill 100.

Get-Soda fonksiyonunu çalıştırdığınızda hiçbir hatanın atılmadığını ve hiçbir şey yapmadığını fark edeceksiniz. Bu noktada beklenen bir şey.

Parametre Doğrulaması Ekleme

Belki de tüm değerlerin Bill parametresine aktarılmasına izin vermek istemiyorsunuzdur. Bu makalenin başında açıklanan benzetmeyi kullanırsak, fonksiyon 100₱ tutarındaki faturalara izin vermemelidir. Yalnızca ₱50 ve ₱20 tutarındaki faturalara izin verilmelidir.

Bill parametresinin önüne [ValidateScript()] ekleyerek ValidateScript parametre doğrulamasını ekleyin. Fonksiyonunuz aşağıdaki kod gibi görünmelidir.

Function Get-Soda {
    [CmdletBinding()]
    param (
        [ValidateScript()]
        $Bill 
    )
}

[ValidateScript()]bloğunun içine {$_ -eq 20 doğrulama kodunu ekleyin. Bu doğrulama kodu, bill parametresine sağlanan değerin 20'ye eşit olup olmadığını kontrol eder. Aşağıdaki kod parçası, kodun nasıl görünmesi gerektiğini gösterir.

Not: $_ kapsamdaki geçerli parametrenin değerini temsil eder. Bu örnekte $_ değeri, Bill parametresinin değeridir.

Function Get-Soda {
    [CmdletBinding()]
    param (
        [ValidateScript({$_ -eq 20})]
        $Bill
    )
}

Şimdi parametre doğrulamanın çalıştığını doğrulamak için bu işlevi tekrar çalıştırın:

PS51> Get-Soda -Bill 20
PS51> Get-Soda -Bill 30

Aşağıda değer olarak 20 iletildiğinde hiçbir şey olmadığını ancak 20 dışında bir şey iletildiğinde hata verdiğini görebilirsiniz.

Get-Soda işlevi hata vermediğinde bu, işlevin başarıyla yürütüldüğü anlamına gelir. Bunu göstermek amacıyla, konsola bir mesaj döndürmek için fonksiyonun içine aşağıdaki kodu ekleyin.

Write-Host "$Bill is an accepted value. Please select your soda."

Get-Soda işlevi daha sonra aşağıdaki gibi görünecektir:

Function Get-Soda {
    [CmdletBinding()]
    param (
        [ValidateScript({$_ -eq 20})]
        $Bill 
    )

    Write-Host "$Bill is an accepted value. Please select your soda."
}

Şimdi Bill parametresine 20 gibi kabul edilen bir değeri iletin. Sonucu aşağıda görmelisiniz.

Daha Anlamlı Hata Mesajları Görüntüleme

Eminim şimdiye kadar parametre değeri doğrulamayı geçemediğinde döndürülen hata mesajının pek sezgisel olmadığını ve çirkin olduğunu fark etmişsinizdir.

Ne yazık ki hatanın nasıl göründüğü konusunda yapabileceğiniz hiçbir şey yok. Doğrulama hatalarının biçimlendirilmesini sağlayan bir özellik yayınlanıncaya kadar (umarız), ona bağlı kalacaksınız.

Ancak bunu biraz geliştirip hataları daha anlamlı hale getirerek kullanıcılarınıza fayda sağlamak mümkün. Bundan sonra bunun nasıl yapılacağına dair örneği göreceksiniz.

Windows PowerShell (5.1) Kullanarak Özel Doğrulama Hatası Ekleme

Get-Soda işlevini genişleterek, değer doğrulamayı karşılamadığında belirli bir hata mesajı atmak mümkündür. Bunu yapmak için ValidateScript bloğunun içine bir if/then yapısı ekleyebilirsiniz.

Aşağıdaki örnekte olduğu gibi basit bir if/then yapısı oluşturun. Bu örnekte Bill parametresinin değeri 20'ye eşit değilse seçtiğiniz bir hata mesajını döndürecektir (X geçersiz. Geçerli değer yalnızca 20'dir.). .

Bunun neye benzediğine dair bir örneği aşağıda görebilirsiniz:

Function Get-Soda {
    [CmdletBinding()]
    param (
        [ValidateScript({
        if ($_ -eq 20) {
            $true
        } else {
            throw "$_ is invalid. Valid value is 20 only."
        }
    })]
    $bill
    )
    process {
        Write-Host "$bill is an accepted value. Please select your soda."
    }
}

Aşağıdaki ekran görüntüsü özel hata mesajını çalışırken göstermektedir. Hata hala çirkin görünüyor ancak bu sefer mesaj açık ve anlaşılır.

PowerShell Core Kullanarak Özel Doğrulama Hataları Ekleme (6+)

PowerShell Core 6'dan başlayarak, ValidateScript parametre doğrulamasına özel hata mesajları ekleme özelliği zaten yerleşiktir. Buna ErrorMessage tekniği adını verelim.

Aşağıdaki değiştirilmiş Get-Soda işlev kodunda, [ValidateScript()] bloğu artık < yerine kullanılabilecek bir ErrorMessage özelliği içermektedir.at. Artık $_ değişkenini kullanmak yerine, iletilen parametre değerini temsil edecek {0} değişkenini kullanabilirsiniz.

Function Get-Soda {
    [CmdletBinding()]
    param (
        [ValidateScript({
            $_ -eq 20            
        },
        ErrorMessage = "{0} is invalid. Valid value is 20 only."
        )]
        $Bill
	)
    Write-Host "$Bill is an accepted value. Please select your soda."
}

Aşağıdaki ekran görüntüsü beklenen çıktının if-else ve throw tekniği kullanımıyla tamamen aynı olduğunu göstermektedir.

PowerShell ValidateScript Kullanım Örnekleri

Bunlar, ValidateScript'in uygulanabileceği gerçek dünyadaki bazı kullanım senaryolarıdır. Bu örnekleri inceleyin ve test edin, ardından önceki bölümde öğrendiğiniz teknikleri kullanarak hata mesajını kendi başınıza iyileştirmeye çalışın.

Tarih Parametre Doğrulaması

Bu kod parçası bir başlangıç ve bitiş tarihini kabul eden bir işlevdir. Girilen tarihlerin gelecekte olmadığının ve 90 günden eski olmadığının doğrulamasını yapar.

<#
    Dummy function to search logs.
    Accepts the following parameters.

        * startDate
            - date must not be older than 90 days.
            - date must not be in the future.
        * endDate
            - date must not be older than 90 days.
            - date must not be in the future.
#>
Function Search-Log {
    [CmdletBinding()]
    param (
        [parameter(Mandatory)]
        [ValidateScript({
            ($_ -gt (Get-Date -Hour 0 -Minute 0 -Second 0).AddDays(-90) -and $_ -le (Get-Date))
        })]
        [datetime]$startDate,


        [parameter(Mandatory)]
        [ValidateScript({
            ($_ -gt (Get-Date -Hour 0 -Minute 0 -Second 0).AddDays(-90) -and $_ -le (Get-Date))
        })]
        [datetime]$endDate
    )

    process {
        Write-Host "I will search the logs between [$startDate] and [$endDate"]
    } 
}

Bu komutları kullanarak işlevi test edin. Kendi startDate ve endDate değerlerinizi belirtebilirsiniz

#TEST: Dates are valid
$startDate = (Get-Date).AddDays(-90) #Today - 90 days
$endDate = (Get-Date) # Today
search-log -startDate $startDate -endDate $endDate

Aşağıdaki örnek çıktı, geçerli tarih değerlerinin girildiği zamandır.

Şimdi 90 günden eski startDate ile tekrar test edin. Ardından hata mesajının görüntülendiğini doğrulayın.

Windows İşlem Parametresi Doğrulaması

Bu sonraki kod parçası, bir sürecin adını kabul eden bir işlevdir. İşlemin bellekte çalıştığını doğrular, ardından bu işlemin çalışan tüm örneklerini öldürür veya doğrulama sonucuna bağlı olarak çıkar.

<#
    A function to kill all instances of a process.
    Usage: Kill-Process -name <process name>
    Example: Kill-Process -name notepad
#>

Function Kill-Process {
    [CmdletBinding()]
    param (
        [parameter(Mandatory)]
        [ValidateScript(
            {
                if (Get-Process -Name $_) {
                    $true
                }
                else {
                    throw "A process with name $_ is not found."
                }
            }
        )]
        [string]$Name
    )
    process {
        Write-Host "Killing Process: $Name"
        Stop-Process -Name $Name -Force
    }
}

Bu komutu kullanarak test edin: Kill-Process -Name

Aşağıdaki örnek çıktıda notepad adlı işlemle test yaptığınız varsayılmaktadır.

  • İlk komut başarılı bir şekilde çalıştı çünkü notepad işleminin çalıştığını tespit etti ve onu sonlandırmaya başladı.
  • notepad artık çalışmadığından ve işlev, oluşturduğunuz özel hata mesajıyla sona erdiğinden ikinci komut başarısız oldu.

Parametreleri Başka Bir Parametre Değerine Göre Doğrulama

Artık işlevlerinizde ValidateScript kullanmanın değeri hakkında bir fikre sahip olmalısınız. Ancak bahsetmeye değer bir sınırlama var. ValidateScript'in kapsamı yalnızca kullanılan parametrenin içindedir. Bu, bir parametrenin diğer parametrelerin değerini kullanamayacağı anlamına gelir.

Geçici bir çözüm olarak, $PSBoundParameters otomatik değişkenine erişilerek parametreler arası değer kontrolü yapılabilir.

Belki de Spam Gönder adında bir işleviniz vardır. Bu fonksiyonun üç parametresi vardır:

  1. Kimden - Gönderenin e-posta adresi. (ör. [e-posta korumalı]). Zorunlu değil.
  2. Kime - Alıcının e-posta adresi. (ör. [e-posta korumalı]). Zorunlu değil.
  3. SendEmail - Değer gerektirmeyen bir anahtar parametresi. Ancak kullanılırsa From ve To parametre değerleri gerekli olacaktır.

SendEmail anahtarı kullanılırsa, From ve To parametrelerinin kullanıldığını onaylamak için bir doğrulama kodu çalıştırılır. Daha sonra True değerini döndürecektir. Öte yandan, eğer From ve To kullanımda değilse, fonksiyon bir hata verip çıkacaktır.

Aşağıdaki kodu kopyalayıp PowerShell oturumunuza yapıştırın.

<#
    Dummy function to send spam
    Accepts the parameters
        
        From
            - sender email address
            - cannot be null or empty
        To
            - recipient email address
            - cannot be null or empty
        SendEmail
            - a switch (on/off) parameter.
            - it will validate if 'To' and 'From' values are present.

    Usage: Send-Spam -From [email  -To [email  -SendEmail
#>

Function Send-Spam {
    [CmdletBinding()]
    param (
        [parameter()]
        [ValidateNotNullOrEmpty()] #Ensure From is not equal to $null or ""
        [mailaddress]$From,

        [parameter()]
        [ValidateNotNullOrEmpty()] #Ensure To is not equal to $null or ""
        [mailaddress]$To,

        [parameter()]
        [ValidateScript(
            {
                # Check if the From and To parameters are specified

                if ($PSBoundParameters.Keys -contains 'From' -AND
                    $PSBoundParameters.Keys -contains 'To') {
                        $true
                }
                else {
                    throw "From and To parameters are required when using SendEmail"
                }
            }
        )]
        [switch]$SendEmail
    )

    process {
        Write-Host "From: $From" -ForegroundColor Yellow
        Write-Host "To: $To" -ForegroundColor Cyan
        if ($SendEmail) {
            Write-Host "Sending Spam from '$From' to '$To'" -ForegroundColor Green
        }        
    }
}

Aşağıda gösterilen komut başarılı bir doğrulamayla sonuçlanacaktır. Çünkü SendEmail anahtarıyla birlikte From ve To parametreleri de kullanıldı.

PS51> Send-Spam -From [email  -To [email  -SendEmail

Şimdi From veya To parametresini kullanmadan test edin. Doğrulama komut dosyası başarısız olacağından bu bir hatayla sonuçlanmalıdır. Aşağıdaki örnek sonuca bakın.

Konsolda ValidateScript'i Kullanma

ValidateScript özelliğinin en yaygın kullanımı işlev parametrelerini doğrulamak olsa da doğrudan PowerShell konsolundan da kullanılabilir. ValidateScript, doğrulama kodunuzu bir komut dosyasına veya işleve eklemeden önce bile test etmek için kullanışlıdır.

Aşağıda ValidateScript'i bir işlevin dışında kullanmanın bazı örnekleri verilmiştir.

Tamsayı Değerinin Doğrulanması

Aşağıdaki bu örnek, belirli bir tamsayı değerinin beşten büyük olduğunu doğrular.

[ValidateScript({$_ -gt 5})]$i=4

Yukarıdaki kodu çalıştırdıktan sonra beklenen sonuç başarısız oluyor çünkü verilen değer 5'ten küçük olan 4'tür. Aşağıdaki örnek ekran görüntüsü, görmeyi beklediğiniz şeydir.

Tarih Değerini Doğrulama

Aşağıdaki örnek kod, verilen tarihin geçerli tarihten daha yeni veya ona eşit olduğunun nasıl doğrulanacağını gösterir.

[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)
[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date).AddHours(-1)

Yukarıdaki kod parçasındaki kodun ilk satırını çalıştırdıktan sonra, sağlanan DateTime değeri aynı veya birkaç saniye daha büyük olduğundan beklenen sonuç iletilir (True).

DateTime değeri geçerli saatten bir saat daha az olduğundan ikinci kod satırı başarısız bir sonuç üretecektir. Örnek çıktı için aşağıdaki ekran görüntüsüne bakın.

Özet

Bu makalede parametre doğrulamanın ne olduğunu ve ValidateScript parametre doğrulama özelliğinin nasıl kullanılacağını öğrendiniz.

Ayrıca, daha açıklayıcı bir hata mesajı görüntüleme yeteneğini nasıl genişleteceğinizi de öğrendiniz. Örnekleri takip ederken hem başarılı hem de başarısız doğrulama sonuçlarını deneyimlediniz.

Artık ValidateScript'in parametreler arası referanslama açısından sınırlamasını ve $PSBoundParameters otomatik değişkenini kullanarak bu sınırlamayı nasıl çözebileceğinizi anlamalısınız.

Umarım bu makalede PowerShell araç oluşturma yolculuğunuzda uygulayabileceğiniz kadar bilgi edinmişsinizdir!

Daha fazla okuma

  • Powershell İşlevlerine Giriş
  • PowerShell Modüllerini Anlama ve Oluşturma
  • ValidateScript doğrulama özelliği
  • Atış Hakkında

İlgili makaleler