Fonksiyonlar

Önceki örnekte sonuçları Fiil sütununa göre sıraladım. Grup sütunu size bu fiillerin nasıl kullanıldığına dair bir fikir verir. Bir modüle işlevler eklendiğinde PowerShell'de onaylanmış bir fiil seçmek önemlidir. Onaylanmamış bir fiil seçerseniz modül yükleme sırasında bir uyarı mesajı oluşturur. Bu uyarı mesajı, işlevlerinizin profesyonellikten uzak görünmesine neden olur. Onaylanmayan fiiller aynı zamanda işlevlerinizin keşfedilebilirliğini de sınırlar.

Basit bir fonksiyon

PowerShell'deki bir işlev, function anahtar sözcüğü, ardından işlev adı ve ardından açma ve kapama küme paranteziyle bildirilir. Fonksiyonun çalıştıracağı kod bu süslü parantezlerin içinde bulunur.

function Get-Version {
    $PSVersionTable.PSVersion
}

Gösterilen işlev, PowerShell sürümünü döndüren basit bir örnektir.

Get-Version

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  693

Get-Version gibi bir adla adlandırılan işlevlerle ve PowerShell'deki varsayılan komutlarla veya başkalarının yazabileceği komutlarla ad çakışması olasılığı yüksektir. Bu nedenle, adlandırma çakışmalarını önlemeye yardımcı olmak için işlevlerinizin isim kısmına önek eklemenizi öneririm. Aşağıdaki örnekte "PS" önekini kullanacağım.

function Get-PSVersion {
    $PSVersionTable.PSVersion
}

Adı dışında bu işlev öncekiyle aynıdır.

Get-PSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  693

İsmin önüne PS gibi bir şey eklenirken bile isim çatışması yaşanma ihtimali yüksektir. Genellikle işlev isimlerimin önüne baş harflerimi koyarım. Bir standart geliştirin ve ona bağlı kalın.

function Get-MrPSVersion {
    $PSVersionTable.PSVersion
}

Bu işlev, diğer PowerShell komutlarıyla adlandırma çakışmalarını önlemeye çalışmak için daha anlamlı bir ad kullanmak dışında önceki iki işlevden farklı değildir.

Get-MrPSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  693

Belleğe yüklendikten sonra işlevleri İşlev PSDrive'da görebilirsiniz.

Get-ChildItem -Path Function:\Get-*Version

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Get-Version
Function        Get-PSVersion
Function        Get-MrPSVersion

Bu işlevleri geçerli oturumunuzdan kaldırmak istiyorsanız bunları İşlev PSDrive'ından kaldırmanız veya PowerShell'i kapatıp yeniden açmanız gerekir.

Get-ChildItem -Path Function:\Get-*Version | Remove-Item

İşlevlerin gerçekten kaldırıldığını doğrulayın.

Get-ChildItem -Path Function:\Get-*Version

İşlevler bir modülün parçası olarak yüklendiyse, bunları kaldırmak için modülün yükü kaldırılabilir.

Remove-Module -Name <ModuleName>

Remove-Module cmdlet'i mevcut PowerShell oturumunuzdaki modülleri bellekten kaldırır, bunları sisteminizden veya diskten kaldırmaz.

Parametreler

Statik olarak değer atamayın! Parametreleri ve değişkenleri kullanın. Parametrelerinizi adlandırma konusunda mümkün olduğunca parametre adlarınız için varsayılan cmdlet'lerle aynı adı kullanın.

function Test-MrParameter {

    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

Parametre adım için neden Bilgisayar, SunucuAdı veya Ana Bilgisayar yerine BilgisayarAdı kullandım? Çünkü fonksiyonumun varsayılan cmdlet'ler gibi standartlaştırılmasını istedim.

Bir sistemdeki tüm komutları sorgulayacak ve belirli parametre adlarına sahip komutların sayısını döndürecek bir fonksiyon oluşturacağım.

function Get-MrParameterCount {
    param (
        [string[]]$ParameterName
    )

    foreach ($Parameter in $ParameterName) {
        $Results = Get-Command -ParameterName $Parameter -ErrorAction SilentlyContinue

        [pscustomobject]@{
            ParameterName = $Parameter
            NumberOfCmdlets = $Results.Count
        }
    }
}

Aşağıda gösterilen sonuçlarda görebileceğiniz gibi BilgisayarAdı parametresine sahip 39 komut. Bilgisayar, SunucuAdı, Ana Bilgisayar veya Makine gibi parametrelere sahip herhangi bir cmdlet yok.

Get-MrParameterCount -ParameterName ComputerName, Computer, ServerName, Host, Machine

ParameterName NumberOfCmdlets
------------- ---------------
ComputerName               39
Computer                    0
ServerName                  0
Host                        0
Machine                     0

Ayrıca parametre adlarınız için varsayılan cmdlet'lerle aynı durumu kullanmanızı öneririm. Bilgisayaradı değil, BilgisayarAdı kullanın. Bu, işlevlerinizin varsayılan cmdlet'ler gibi görünmesini ve hissettirmesini sağlar. PowerShell'e zaten aşina olan kişiler kendilerini evlerindeymiş gibi hissedecekler.

param ifadesi bir veya daha fazla parametre tanımlamanıza olanak sağlar. Parametre tanımları virgülle (,) ayrılır. Daha fazla bilgi için bkz. about_Functions_Advanced_Parameters.

Gelişmiş Fonksiyonlar

PowerShell'deki bir işlevi gelişmiş bir işleve dönüştürmek gerçekten basittir. Bir işlev ile gelişmiş bir işlev arasındaki farklardan biri, gelişmiş işlevlerin, işleve otomatik olarak eklenen bir dizi ortak parametreye sahip olmasıdır. Bu ortak parametreler, Verbose ve Debug gibi parametreleri içerir.

Önceki bölümde kullanılan Test-MrParameter işleviyle başlayacağım.

function Test-MrParameter {

    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

Dikkatinizi çekmenizi istediğim şey, Test-MrParameter fonksiyonunun herhangi bir ortak parametresinin olmamasıdır. Ortak parametreleri görmenin birkaç farklı yolu vardır. Bunlardan biri, Get-Command kullanarak sözdizimini görüntülemektir.

Get-Command -Name Test-MrParameter -Syntax

Test-MrParameter [[-ComputerName] <Object>]

Bir diğeri ise Get-Command ile parametrelerin detayına inmektir.

(Get-Command -Name Test-MrParameter).Parameters.Keys

ComputerName

İşlevi gelişmiş bir işleve dönüştürmek için CmdletBinding ekleyin.

function Test-MrCmdletBinding {

    [CmdletBinding()] #<<-- This turns a regular function into an advanced function
    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

CmdletBinding'in eklenmesi ortak parametreleri otomatik olarak ekler. CmdletBinding bir param bloğu gerektirir, ancak param bloğu boş olabilir.

Get-Command -Name Test-MrCmdletBinding -Syntax

Test-MrCmdletBinding [[-ComputerName] <Object>] [<CommonParameters>]

Get-Command ile parametrelerin ayrıntılarına inmek, yaygın olanlar da dahil olmak üzere gerçek parametre adlarını gösterir.

(Get-Command -Name Test-MrCmdletBinding).Parameters.Keys

ComputerName
Verbose
Debug
ErrorAction
WarningAction
InformationAction
ErrorVariable
WarningVariable
InformationVariable
OutVariable
OutBuffer
PipelineVariable

DesteklerShouldProcess

SupportsShouldProcess, WhatIf ve Confirm parametrelerini ekler. Bunlar yalnızca değişiklik yapan komutlar için gereklidir.

function Test-MrSupportsShouldProcess {

    [CmdletBinding(SupportsShouldProcess)]
    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

Artık WhatIf ve Onayla parametrelerinin mevcut olduğuna dikkat edin.

Get-Command -Name Test-MrSupportsShouldProcess -Syntax

Test-MrSupportsShouldProcess [[-ComputerName] <Object>] [-WhatIf] [-Confirm] [<CommonParameters>]

Bir kez daha, WhatIf ve Confirm ile birlikte yaygın olanlar da dahil olmak üzere gerçek parametre adlarının bir listesini döndürmek için Get-Command komutunu da kullanabilirsiniz.

(Get-Command -Name Test-MrSupportsShouldProcess).Parameters.Keys

ComputerName
Verbose
Debug
ErrorAction
WarningAction
InformationAction
ErrorVariable
WarningVariable
InformationVariable
OutVariable
OutBuffer
PipelineVariable
WhatIf
Confirm

Parametre Doğrulaması

Girişi erkenden doğrulayın. Geçerli bir giriş olmadan çalıştırılması mümkün olmadığında kodunuzun bir yolda devam etmesine neden izin veresiniz?

Her zaman parametreleriniz için kullanılan değişkenleri yazın (bir veri türü belirtin).

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [string]$ComputerName
    )

    Write-Output $ComputerName

}

Önceki örnekte, BilgisayarAdı parametresinin veri türü olarak Dize'yi belirtmiştim. Bu, yalnızca tek bir bilgisayar adının belirtilmesine izin vermesine neden olur. Virgülle ayrılmış listede birden fazla bilgisayar adı belirtilirse hata oluşturulur.

Test-MrParameterValidation -ComputerName Server01, Server02

Test-MrParameterValidation : Cannot process argument transformation on parameter
'ComputerName'. Cannot convert value to type System.String.
At line:1 char:42
+ Test-MrParameterValidation -ComputerName Server01, Server02
+
    + CategoryInfo          : InvalidData: (:) [Test-MrParameterValidation], ParameterBindingArg
     umentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Test-MrParameterValidation

Geçerli tanımdaki sorun, BilgisayarAdı parametresinin değerinin atlanmasının geçerli olması, ancak işlevin başarıyla tamamlanması için bir değerin gerekli olmasıdır. Zorunlu parametre özelliğinin kullanışlı olduğu yer burasıdır.

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]$ComputerName
    )

    Write-Output $ComputerName

}

Önceki örnekte kullanılan sözdizimi PowerShell sürüm 3.0 ve üzeriyle uyumludur. İşlevi PowerShell sürüm 2,0 ve üzeri ile uyumlu hale getirmek için bunun yerine [Parameter(Mandatory=$true)] belirtilebilir. Artık BilgisayarAdı gerekli olduğundan, belirtilmemişse işlev bir tane isteyecektir.

Test-MrParameterValidation

cmdlet Test-MrParameterValidation at command pipeline position 1
Supply values for the following parameters:
ComputerName:

BilgisayarAdı parametresi için birden fazla değere izin vermek istiyorsanız Dize veri türünü kullanın ancak bir dize dizisine izin vermek için veri türüne açık ve kapalı köşeli parantez ekleyin .

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string[]]$ComputerName
    )

    Write-Output $ComputerName

}

Belki belirtilmemişse BilgisayarAdı parametresi için varsayılan bir değer belirtmek isteyebilirsiniz. Sorun, varsayılan değerlerin zorunlu parametrelerle kullanılamamasıdır. Bunun yerine, varsayılan değerle ValidateNotNullOrEmpty parametre doğrulama özelliğini kullanmanız gerekir.

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    Write-Output $ComputerName

}

Varsayılan bir değer ayarlarken bile statik değerleri kullanmamaya çalışın. Önceki örnekte, varsayılan değer olarak $env:COMPUTERNAME kullanılmıştır ve bir değer sağlanmadığı takdirde otomatik olarak yerel bilgisayar adına çevrilir.

Ayrıntılı Çıktı

Satır içi yorumlar yararlı olsa da, özellikle karmaşık bir kod yazıyorsanız, kodun kendisine bakmadıkları sürece kullanıcılar tarafından asla görülmezler.

Aşağıdaki örnekte gösterilen işlevin foreach döngüsünde satır içi bir yorumu vardır. Bu özel yorumu bulmak o kadar da zor olmasa da, fonksiyonun yüzlerce satır kod içerdiğini hayal edin.

function Test-MrVerboseOutput {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    foreach ($Computer in $ComputerName) {
        #Attempting to perform some action on $Computer <<-- Don't use
        #inline comments like this, use write verbose instead.
        Write-Output $Computer
    }

}

Daha iyi bir seçenek, satır içi yorumlar yerine Write-Verbose kullanmaktır.

function Test-MrVerboseOutput {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    foreach ($Computer in $ComputerName) {
        Write-Verbose -Message "Attempting to perform some action on $Computer"
        Write-Output $Computer
    }

}

İşlev Verbose parametresi olmadan çağrıldığında ayrıntılı çıktı görüntülenmez.

Test-MrVerboseOutput -ComputerName Server01, Server02

Verbose parametresiyle çağrıldığında ayrıntılı çıktı görüntülenecektir.

Test-MrVerboseOutput -ComputerName Server01, Server02 -Verbose

Boru Hattı Girişi

İşlevinizin boru hattı girişini kabul etmesini istediğinizde bazı ek kodlamalar gereklidir. Bu kitapta daha önce de belirtildiği gibi, komutlar ardışık düzen girişini değere göre (türe göre) veya özellik adına göre kabul edebilir. İşlevlerinizi, bu tür girişlerden birini veya her ikisini de kabul edecek şekilde yerel komutlar gibi yazabilirsiniz.

Ardışık düzen girişini değere göre kabul etmek için, söz konusu parametreye ilişkin ValueFromPipeline parametre özelliğini belirttik. Her veri türünün birinden yalnızca değere göre ardışık düzen girişini kabul edebileceğinizi unutmayın. Örneğin, dize girişini kabul eden iki parametreniz varsa, bunlardan yalnızca biri ardışık düzen girişini değere göre kabul edebilir; çünkü bunu her iki dize parametresi için de belirtirseniz, ardışık düzen girişi hangisi olduğunu bilemez. bağlanacak biri. Bu tür ardışık düzen girişini değere göre yerine türe göre olarak adlandırmamın bir başka nedeni de budur.

İşlem hattı girişi, foreach döngüsünde öğelerin işlenme şekline benzer şekilde, her seferinde bir öğe halinde gelir. Bir diziyi girdi olarak kabul ediyorsanız, bu öğelerin her birini işlemek için en azından bir işlem bloğu gerekir. Giriş olarak yalnızca tek bir değeri kabul ediyorsanız process bloğu gerekli değildir ancak yine de tutarlılık için bunu belirtmenizi öneririm.

function Test-MrPipelineInput {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline)]
        [string[]]$ComputerName
    )

    PROCESS {
        Write-Output $ComputerName
    }

}

Ardışık düzen girişini özellik adına göre kabul etmek, ValueFromPipelineByPropertyName parametre özelliğiyle belirtilmesi dışında benzerdir ve veri türünden bağımsız olarak herhangi bir sayıda parametre için belirtilebilir. Önemli olan, aktarılan komutun çıktısının, parametrenin adıyla veya işlevinizin parametre takma adıyla eşleşen bir özellik adına sahip olması gerektiğidir.

function Test-MrPipelineInput {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
            Write-Output $ComputerName
    }

}

BEGIN ve END blokları isteğe bağlıdır. BEGIN, PROCESS bloğundan önce belirtilir ve öğeler ardışık düzenden alınmadan önce herhangi bir başlangıç çalışmasını gerçekleştirmek için kullanılır. Bunu anlamak önemlidir. Aktarılan değerlere BEGIN bloğundan erişilemez. END bloğu, PROCESS bloğundan sonra belirtilir ve aktarılan tüm öğeler işlendikten sonra temizlik için kullanılır.

Hata İşleme

Aşağıdaki örnekte gösterilen işlev, bir bilgisayarla bağlantı kurulamadığında işlenmeyen bir özel durum oluşturur.

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            Test-WSMan -ComputerName $Computer
        }
    }

}

PowerShell'de hataları işlemenin birkaç farklı yolu vardır. Dene/Yakala, hataları ele almanın daha modern yoludur.

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            try {
                Test-WSMan -ComputerName $Computer
            }
            catch {
                Write-Warning -Message "Unable to connect to Computer: $Computer"
            }
        }
    }

}

Önceki örnekte gösterilen işlev hata işlemeyi kullansa da, komut bir sonlandırma hatası oluşturmadığından işlenmeyen bir özel durum da oluşturur. Bunu anlamak da önemlidir. Yalnızca sonlandırma hataları yakalanır. Sonlanmayan bir hatayı sonlandırıcı bir hataya dönüştürmek için ErrorAction parametresini Durdur değeriyle belirtin.

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            try {
                Test-WSMan -ComputerName $Computer -ErrorAction Stop
            }
            catch {
                Write-Warning -Message "Unable to connect to Computer: $Computer"
            }
        }
    }

}

Kesinlikle gerekmedikçe global $ErrorActionPreference değişkenini değiştirmeyin. Doğrudan PowerShell işlevinizin içinden .NET gibi bir şey kullanıyorsanız ErrorAction'ı komutun kendisinde belirtemezsiniz. Bu senaryoda, genel $ErrorActionPreference değişkenini değiştirmeniz gerekebilir, ancak değiştirirseniz, komutu denedikten hemen sonra eski durumuna döndürün.

Yoruma Dayalı Yardım

İşlevlerinize yoruma dayalı yardım eklemek en iyi uygulama olarak kabul edilir, böylece bunları paylaştığınız kişiler bunları nasıl kullanacaklarını bilir.

function Get-MrAutoStoppedService {

<#
.SYNOPSIS
    Returns a list of services that are set to start automatically, are not
    currently running, excluding the services that are set to delayed start.

.DESCRIPTION
    Get-MrAutoStoppedService is a function that returns a list of services from
    the specified remote computer(s) that are set to start automatically, are not
    currently running, and it excludes the services that are set to start automatically
    with a delayed startup.

.PARAMETER ComputerName
    The remote computer(s) to check the status of the services on.

.PARAMETER Credential
    Specifies a user account that has permission to perform this action. The default
    is the current user.

.EXAMPLE
     Get-MrAutoStoppedService -ComputerName 'Server1', 'Server2'

.EXAMPLE
     'Server1', 'Server2' | Get-MrAutoStoppedService

.EXAMPLE
     Get-MrAutoStoppedService -ComputerName 'Server1' -Credential (Get-Credential)

.INPUTS
    String

.OUTPUTS
    PSCustomObject

.NOTES
    Author:  Mike F Robbins
    Website: http://mikefrobbins.com
    Twitter: @mikefrobbins
#>

    [CmdletBinding()]
    param (

    )

    #Function Body

}

İşlevlerinize yoruma dayalı yardım eklediğinizde, varsayılan yerleşik komutlar gibi onlar için de yardım alınabilir.

PowerShell'de bir işlev yazmaya yönelik tüm söz dizimi, özellikle yeni başlayan biri için çok zor görünebilir. Çoğu zaman, bir şeyin sözdizimini hatırlamıyorsam, ISE'nin ikinci bir kopyasını ayrı bir monitörde açarım ve işlevimin kodunu yazarken "Cmdlet (gelişmiş işlev) - Tamamlandı" pasajını görüntülerim. Snippet'lere PowerShell ISE'de Ctrl+J tuş kombinasyonu kullanılarak erişilebilir.

Özet

Bu bölümde, bir fonksiyonun gelişmiş bir fonksiyona nasıl dönüştürüleceğini dahil olmak üzere PowerShell'de fonksiyon yazmanın temellerini ve PowerShell fonksiyonlarını yazarken parametre doğrulama, ayrıntılı çıktı, ardışık düzen girişi gibi göz önünde bulundurmanız gereken daha önemli unsurlardan bazılarını öğrendiniz. , hata yönetimi ve yoruma dayalı yardım.

Gözden geçirmek

1. PowerShell'de onaylanmış fiillerin listesini nasıl edinirsiniz?
2. PowerShell işlevini gelişmiş bir işleve nasıl dönüştürürsünüz?
3. WhatIf ve Confirm parametreleri PowerShell işlevlerinize ne zaman eklenmelidir?
4. Sonlanmayan bir hatayı sonlandırıcı bir hataya nasıl dönüştürürsünüz?
5. İşlevlerinize neden yoruma dayalı yardım eklemelisiniz?

Önerilen Okuma

• about_Functions
• about_Functions_Advanced_Parameters
• about_CommonParameters
• about_Functions_CmdletBindingAttribute
• about_Functions_Advanced
• about_Try_Catch_Finally
• about_Comment_Based_Help
• Video: Gelişmiş İşlevler ve Komut Dosyası Modülleriyle PowerShell Araç Yapımı