about_Functions

  • Makale

Kısa açıklama

PowerShell'de işlevlerin nasıl oluşturulacağını ve kullanılacağını açıklar.

Uzun açıklama

İşlev, atadığınız bir ada sahip PowerShell deyimlerinin listesidir. Bir işlevi çalıştırdığınızda işlev adını yazarsınız. Listedeki deyimler, komut isteminde yazdığınız gibi çalışır.

İşlevler aşağıdaki kadar basit olabilir:

function Get-PowerShellProcess { Get-Process PowerShell }

İşlev, cmdlet veya uygulama kadar karmaşık da olabilir.

Cmdlet'ler gibi işlevlerin de parametreleri olabilir. Parametreler adlandırılmış, konumsal, anahtar veya dinamik parametreler olabilir. İşlev parametreleri komut satırından veya işlem hattından okunabilir.

İşlevler görüntülenebilir, değişkenlere atanabilir veya diğer işlevlere veya cmdlet'lere geçirilebilen değerler döndürebilir. Anahtar sözcüğünü return kullanarak bir dönüş değeri de belirtebilirsiniz. anahtar return sözcüğü işlevinizden döndürülen diğer çıkışı etkilemez veya gizlemez. Ancak anahtar return sözcüğü bu satırdaki işlevden çıkar. Daha fazla bilgi için bkz . about_Return.

İşlevin deyim listesi, , processendve cleananahtar sözcükleriyle beginfarklı türde deyim listeleri içerebilir. Bu deyim listeleri, işlem hattından gelen girişleri farklı işler.

Filter anahtar sözcüğü, işlem hattındaki her nesne üzerinde çalışan bir işlev türü oluşturmak için kullanılır. Filtre, tüm deyimleri bir blokta olan bir process işleve benzer.

İşlevler cmdlet'ler gibi de hareket edebilir. Programlama kullanmadan C# bir cmdlet gibi çalışan bir işlev oluşturabilirsiniz. Daha fazla bilgi için bkz . about_Functions_Advanced.

Önemli

Betik dosyaları ve betik tabanlı modüller içinde işlevlerin çağrılabilmesi için önce tanımlanması gerekir.

Sözdizimi

Bir işlevin söz dizimi aşağıdadır:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

İşlev aşağıdaki öğeleri içerir:

  • Anahtar function sözcük
  • Kapsam (isteğe bağlı)
  • Seçtiğiniz bir ad
  • Herhangi bir sayıda adlandırılmış parametre (isteğe bağlı)
  • Küme ayracı içine alınmış bir veya daha fazla PowerShell komutu {}

İşlevlerdeki dynamicparam anahtar sözcük ve dinamik parametreler hakkında daha fazla bilgi için bkz . about_Functions_Advanced_Parameters.

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{}
}

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.

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.

Basit işlevler

İşlevlerin yararlı olması için karmaşık olması gerekmez. En basit işlevler aşağıdaki biçime sahiptir:

function <function-name> {statements}

Örneğin, aşağıdaki işlev PowerShell'i Yönetici istrator olarak çalıştır seçeneğiyle başlatır.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

işlevini kullanmak için şunu yazın: Start-PSAdmin

İşleve deyim eklemek için her deyimi ayrı bir satıra yazın veya deyimleri ayırmak için noktalı virgül ; kullanın.

Örneğin, aşağıdaki işlev geçerli kullanıcının dizinlerinde başlangıç tarihinden sonra değiştirilen tüm .jpg dosyaları bulur.

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

Kullanışlı küçük işlevlerden oluşan bir araç kutusu oluşturabilirsiniz. Bu konunun about_Profiles ve sonraki bölümlerinde açıklandığı gibi bu işlevleri PowerShell profilinize ekleyin.

İşlev Adları

bir işleve herhangi bir ad atayabilirsiniz, ancak başkalarıyla paylaştığınız işlevler tüm PowerShell komutları için oluşturulmuş adlandırma kurallarına uymalıdır.

İşlev adları, fiilin işlevin gerçekleştirdiği eylemi, isim ise cmdlet'in eylemini gerçekleştirdiği öğeyi tanımladığı bir fiil-isim çifti içermelidir.

İşlevler, tüm PowerShell komutları için onaylanmış standart fiilleri kullanmalıdır. Bu fiiller, komut adlarımızı tutarlı ve kullanıcıların anlaması kolay tutmamıza yardımcı olur.

Standart PowerShell fiilleri hakkında daha fazla bilgi için bkz . Onaylı Fiiller.

Parametrelerle İşlevler

Adlandırılmış parametreler, konumsal parametreler, anahtar parametreleri ve dinamik parametreler dahil olmak üzere işlevlerle parametreleri kullanabilirsiniz. İşlevlerdeki dinamik parametreler hakkında daha fazla bilgi için bkz . about_Functions_Advanced_Parameters.

Adlandırılmış Parametreler

İstediğiniz sayıda adlandırılmış parametre tanımlayabilirsiniz. Bu konunun ilerleyen bölümlerinde açıklandığı gibi adlandırılmış parametreler için varsayılan bir değer ekleyebilirsiniz.

Aşağıdaki örnek söz diziminde gösterildiği gibi anahtar sözcüğünü param kullanarak küme ayraçlarının içinde parametreler tanımlayabilirsiniz:

function <name> {
  param ([type]$parameter1 [,[type]$parameter2])
  <statement list>
}

Aşağıdaki örnek söz diziminde gösterildiği gibi anahtar sözcük olmadan Param ayraçların dışında parametreler de tanımlayabilirsiniz:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Aşağıda bu alternatif söz diziminin bir örneği verilmiştir.

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

İlk yöntem tercih edilirken, bu iki yöntem arasında bir fark yoktur.

İşlevi çalıştırdığınızda, parametre için sağladığınız değer parametre adını içeren bir değişkene atanır. Bu değişkenin değeri işlevde kullanılabilir.

Aşağıdaki örnek adlı Get-SmallFilesbir işlevdir. Bu işlevin bir $Size parametresi vardır. işlevi, parametresinin değerinden $Size küçük olan tüm dosyaları görüntüler ve dizinleri dışlar:

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

işlevinde parametresi için tanımlanan ad olan değişkenini kullanabilirsiniz $Size .

Bu işlevi kullanmak için aşağıdaki komutu yazın:

Get-SmallFiles -Size 50

Ayrıca, parametre adı olmadan adlandırılmış parametre için bir değer de girebilirsiniz. Örneğin, aşağıdaki komut Size parametresini adlandıran bir komutla aynı sonucu verir:

Get-SmallFiles 50

Parametre için varsayılan bir değer tanımlamak için, örneğin aşağıdaki varyasyonunda Get-SmallFiles gösterildiği gibi, parametre adından sonra bir eşittir işareti ve değeri yazın:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Bir değer olmadan yazarsanız Get-SmallFiles , işlevine $size100 atar. Bir değer sağlarsanız işlev bu değeri kullanır.

İsteğe bağlı olarak, PSDefaultValue özniteliğini parametrenizin açıklamasına ekleyerek ve PSDefaultValue'nunHelp özelliğini belirterek parametrenizin varsayılan değerini açıklayan kısa bir yardım dizesi sağlayabilirsiniz. İşlevdeki Size parametresinin Get-SmallFiles varsayılan değerini (100) açıklayan bir yardım dizesi sağlamak için, aşağıdaki örnekte gösterildiği gibi PSDefaultValue özniteliğini ekleyin.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

PSDefaultValue öznitelik sınıfı hakkında daha fazla bilgi için bkz. PSDefaultValue Öznitelik Üyeleri.

KonumSal Parametreler

Konumsal parametre, parametre adı olmayan bir parametredir. PowerShell, her parametre değerini işlevdeki bir parametreyle ilişkilendirmek için parametre değeri sırasını kullanır.

Konumsal parametreler kullandığınızda, işlev adından sonra bir veya daha fazla değer yazın. Konumsal parametre değerleri dizi değişkenine $args atanır. İşlev adını izleyen değer, dizideki $args[0]ilk konuma $args atanır.

Aşağıdaki Get-Extension işlev, dosya adı uzantısını .txt sağladığınız bir dosya adına ekler:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Anahtar Parametreleri

Anahtar, değer gerektirmeyen bir parametredir. Bunun yerine işlev adını ve ardından switch parametresinin adını yazarsınız.

Anahtar parametresi tanımlamak için, aşağıdaki örnekte gösterildiği gibi parametre adından önce türü [switch] belirtin:

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

switch parametresini On işlev adından sonra yazdığınızda, işlev görüntülenir Switch on. switch parametresi olmadan görüntülenir Switch off.

Switch-Item -on

Switch on

Switch-Item

Switch off

Aşağıdaki örnekte gösterildiği gibi işlevi çalıştırdığınızda anahtara boole değeri de atayabilirsiniz:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Komut Parametrelerini Temsil Etmek için Splatting Kullanma

Bir komutun parametrelerini temsil etmek için splatting kullanabilirsiniz. Bu özellik Windows PowerShell 3.0'da kullanıma sunulmuştur.

Oturumdaki komutları çağıran işlevlerde bu tekniği kullanın. Komut parametrelerini bildirmeniz veya listelemeniz veya komut parametreleri değiştiğinde işlevi değiştirmeniz gerekmez.

Aşağıdaki örnek işlev cmdlet'ini Get-Command çağırır. komutu, parametrelerini Get-Commandtemsil etmek için kullanır@Args.

function Get-MyCommand { Get-Command @Args }

işlevini çağırdığınızda Get-MyCommand tüm parametrelerini Get-Command kullanabilirsiniz. parametreler ve parametre değerleri komutu kullanılarak @Argskomutuna geçirilir.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Özellik @Args , geri kalan bağımsız değişkenlerden bildirilmemiş cmdlet parametrelerini ve değerlerini temsil eden otomatik parametreyi kullanır $Args .

Daha fazla bilgi için bkz . about_Splatting.

nesneleri İşlevlere Borulama

Herhangi bir işlev işlem hattından giriş alabilir. bir işlevin , , processendve clean anahtar sözcüklerini kullanarak beginişlem hattından gelen girişleri nasıl işlediğini denetleyebilirsiniz. Aşağıdaki örnek söz dizimi şu anahtar sözcükleri gösterir:

Deyim process listesi, işlem hattındaki her nesne için bir kez çalışır. process Blok çalışırken, her işlem hattı nesnesi otomatik değişkene $_ atanır ve her seferinde bir işlem hattı nesnesi olur.

Aşağıdaki işlev anahtar sözcüğünü process kullanır. İşlev işlem hattındaki değerleri görüntüler:

function Get-Pipeline
{
  process {"The value is: $_"}
}

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Bir parametreden işlem hattı girişi veya girişi alabilen bir işlev istiyorsanız bloğun her iki durumu da işlemesi process gerekir. Örneğin:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10

İşlem hattında bir işlev kullandığınızda, işleve yöneltilen nesneler otomatik değişkene $input atanır. İşlev, herhangi bir nesne işlem hattından gelmeden önce anahtar sözcüğüyle begin deyimleri çalıştırır. İşlev, tüm nesneler işlem hattından alındıktan sonra anahtar sözcüğüyle end deyimleri çalıştırır.

Aşağıdaki örnekte ve end anahtar sözcükleriyle begin otomatik değişken gösterilmektedir$input.

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Bu işlev işlem hattı kullanılarak çalıştırılırsa aşağıdaki sonuçları görüntüler:

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

begin deyimi çalıştırıldığında, işlev işlem hattından gelen girişe sahip olmaz. deyimi, end işlevin değerlerine sahip olduktan sonra çalışır.

İşlevin bir process anahtar sözcüğü varsa içindeki her nesne $input öğesinden $input kaldırılır ve öğesine $_atanır. Aşağıdaki örnekte bir process deyim listesi vardır:

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

Bu örnekte, işleve yöneltilen her nesne deyim listesine gönderilir process . Deyimler process her nesne üzerinde çalışır ve her seferinde bir nesnedir. İşlev $input anahtar sözcüğüne ulaştığında end otomatik değişken boş olur.

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Daha fazla bilgi için bkz . Numaralandırıcıları Kullanma

PowerShell 7.3 bloğu ekledi clean . Blokclean, kullanıcıların , processve end bloklarında oluşturulan ve kullanı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.

Filtreler

Filtre, işlem hattındaki her nesne üzerinde çalışan bir işlev türüdür. Filtre, tüm deyimleri bir blokta olan bir process işleve benzer.

Filtrenin söz dizimi aşağıdaki gibidir:

filter [<scope:>]<name> {<statement list>}

Aşağıdaki filtre işlem hattından günlük girdilerini alır ve girişin tamamını veya yalnızca ileti bölümünü görüntüler:

filter Get-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Aşağıdaki gibi kullanılabilir:

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

İşlev Kapsamı

İşlev, oluşturulduğu kapsamda bulunur.

İşlev bir betiğin parçasıysa, işlev bu betik içindeki deyimler için kullanılabilir. Varsayılan olarak, betikteki bir işlev bu betiğin dışında kullanılamaz.

bir işlevin kapsamını belirtebilirsiniz. Örneğin, işlev aşağıdaki örnekte genel kapsama eklenir:

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

bir işlev genel kapsamda olduğunda, işlevi betiklerde, işlevlerde ve komut satırında kullanabilirsiniz.

İşlevler yeni bir kapsam oluşturur. Bir işlevde oluşturulan değişkenler gibi öğeler yalnızca işlev kapsamında bulunur.

Daha fazla bilgi için bkz . about_Scopes.

İşlevi Kullanarak İşlevleri Bulma ve Yönetme: Sürücü

PowerShell'deki tüm işlevler ve filtreler sürücüde Function: otomatik olarak depolanır. Bu sürücü PowerShell İşlevi sağlayıcısı tarafından kullanıma sunulur.

Sürücüye başvururken, bir bilgisayarın veya sürücüsüne Function: başvururken yaptığınız gibi İşlev'inC arkasına iki nokta üst üste D yazın.

Aşağıdaki komut, PowerShell'in geçerli oturumundaki tüm işlevleri görüntüler:

Get-ChildItem function:

İşlevdeki komutlar, işlevin tanım özelliğinde betik bloğu olarak depolanır. Örneğin, PowerShell ile birlikte gelen Yardım işlevindeki komutları görüntülemek için şunu yazın:

(Get-ChildItem function:help).Definition

Aşağıdaki söz dizimini de kullanabilirsiniz.

$function:help

Sürücü hakkında Function: daha fazla bilgi için İşlev sağlayıcısının yardım konusuna bakın. Get-Help Function yazın.

Yeni Oturumlarda İşlevleri Yeniden Kullan

PowerShell komut isteminde bir işlev yazdığınızda, işlev geçerli oturumun bir parçası olur. İşlev, oturum sona erene kadar kullanılabilir.

İşlevinizi tüm PowerShell oturumlarında kullanmak için işlevi PowerShell profilinize ekleyin. Profiller hakkında daha fazla bilgi için bkz . about_Profiles.

İşlevinizi bir PowerShell betik dosyasına da kaydedebilirsiniz. İşlevinizi bir metin dosyasına yazın ve dosyayı dosya adı uzantısıyla .ps1 kaydedin.

İşlevler için Yardım Yazma

cmdlet'i Get-Help hem işlevler hem de cmdlet'ler, sağlayıcılar ve betikler için yardım alır. Bir işlevle ilgili yardım almak için, ardından işlev adını yazın Get-Help .

Örneğin, işlevle ilgili Get-MyDisks yardım almak için şunu yazın:

Get-Help Get-MyDisks

Aşağıdaki iki yöntemden birini kullanarak bir işlev için yardım yazabilirsiniz:

  • İşlevler için Açıklama Tabanlı Yardım

    Açıklamalarda özel anahtar sözcükler kullanarak bir yardım konusu oluşturun. Bir işlev için açıklama tabanlı yardım oluşturmak için, açıklamaların işlev gövdesinin başına veya sonuna veya işlev anahtar sözcüğünden önceki satırlara yerleştirilmesi gerekir. Açıklama tabanlı yardım hakkında daha fazla bilgi için bkz . about_Comment_Based_Help.

  • İşlevler için XML Tabanlı Yardım

    Genellikle cmdlet'ler için oluşturulan tür gibi XML tabanlı bir yardım konusu oluşturun. Yardım konularını birden çok dilde yerelleştiriyorsanız XML tabanlı yardım gereklidir.

    İşlevi XML tabanlı yardım konusuyla ilişkilendirmek için açıklama tabanlı yardım anahtar sözcüğünü .EXTERNALHELP kullanın. Bu anahtar sözcük olmadan, Get-Help işlev yardım konusunu bulamıyor ve yalnızca otomatik olarak oluşturulan yardımı döndürecek işlev çağrıları Get-Help .

    Anahtar sözcük hakkında .EXTERNALHELP daha fazla bilgi için bkz . about_Comment_Based_Help. XML tabanlı yardım hakkında daha fazla bilgi için bkz . How to Write Cmdlet Yardımı.

Ayrıca bkz.