Fonksiyonlar_Hakkında

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 }

Bir işlev, bir cmdlet veya uygulama programı 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. return anahtar sözcüğünü kullanarak bir dönüş değeri de belirtebilirsiniz. Anahtar return sözcük, işlevinizden döndürülen diğer çıktıları etkilemez veya bastırmaz. Ancak anahtar return sözcüğü bu satırdaki işlevden çıkar. Daha fazla bilgi için bkz . about_Return.

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

Filtre, anahtar sözcüğü kullanan Filter özel bir işlev türüdür.

İş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>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<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 ayraçları {} 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.

Basit Fonksiyonlar

İşlevlerin kullanışlı 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 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 deyimler 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 tanımladığı ve ismin cmdlet'in eylemini gerçekleştirdiği öğeyi tanımladığı bir fiil-isim çiftinden oluşmalıdır.

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

Standart PowerShell fiilleri hakkında daha fazla bilgi için Microsoft Belgeleri'nde Onaylanan Fiiller'e bakın.

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 varsayılan değerini (100) açıklayan bir yardım dizesi sağlamak için, aşağıdaki örnekte gösterildiği gibi PSDefaultValueGet-SmallFiles.

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 $argsilk konuma $args[0] atanır.

Aşağıdaki Get-Extension işlev, .txt sağladığınız bir dosya adına dosya adı uzantısını 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" }
}

İşlev adından sonra anahtar parametresini On yazdığınızda, işlevde "Aç" görüntülenir. Anahtar parametresi olmadan, "Kapat" mesajını görüntüler.

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' (parametre yayma tekniği) 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 numaralandırmanız ya da 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 @Argstemsil etmek için kullanırGet-Command.

function Get-MyCommand { Get-Command @Args }

İşlevi çağırdığınızda Get-Command tüm Get-MyCommand parametreleri 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 .

Sıçrama hakkında daha fazla bilgi için about_Splatting bakın.

nesneleri İşlevlere Borulama

Herhangi bir işlev işlem hattından giriş alabilir. bir işlevin , Beginve Process anahtar sözcüklerini kullanarak Endişlem hattından gelen girişleri nasıl işlediğini denetleyebilirsiniz. Aşağıdaki örnek sözdizimi üç anahtar sözcüğü gösterir:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Deyim Begin listesi, işlevin başında yalnızca bir kez çalışır.

Önemli

İşleviniz bir Beginveya ProcessEnd blok tanımlıyorsa, kodunuzun tamamı bu blokların içinde bulunmalıdır. Bloklardan herhangi biri tanımlanmışsa, blokların dışında hiçbir kod tanınmayacaktır.

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.

İşlev işlem hattındaki tüm nesneleri aldıktan sonra, End deyim listesi bir kez çalışır. , BeginProcess, veya End anahtar sözcükler kullanılmazsa, tüm deyimler bir End deyim listesi gibi değerlendirilir.

Aşağıdaki işlev anahtar sözcüğünü Process kullanır. İşlev, işlem hattından örnekler görüntüler:

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

Bu işlevi göstermek için, aşağıdaki örnekte gösterildiği gibi virgülle ayrılmış bir sayı listesi girin:

1,2,4 | Get-Pipeline

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

İş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 Begin anahtar sözcüğüyle deyimleri çalıştırır. İşlev, tüm nesneler işlem hattından alındıktan sonra End anahtar sözcüğüyle deyimleri çalıştırır.

Aşağıdaki örnekte, $input ve Begin anahtar sözcükleriyle End otomatik değişkeni gösterilmektedir.

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 Deyim çalıştırıldığında, işlev işlem hattından gelen girişe sahip değildir. 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

Filtreler

Filtre, işlem hattındaki her nesne üzerinde çalışan bir işlev türüdür. Filtre, Process bloğundaki tüm deyimleriyle bir 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 { $_ }
}

İşlev Kapsamı

Bir iş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, komut dosyasındaki bir işlev komut isteminde 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 normalde bir kapsam oluşturur. Bir işlevde oluşturulan değişkenler gibi öğeler yalnızca işlev kapsamında bulunur.

PowerShell'deki kapsam hakkında daha fazla bilgi için about_Scopes bakın.

İş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'iniki nokta üst üste C 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

Function: sürücüsü hakkında daha fazla bilgi için İşlevi 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. 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 ardından dosyayı dosya adı uzantısıyla .ps1 kaydedin.

İşlevler için Yardım Yazma

Get-Help cmdlet'i 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

    Yorumlarda özel anahtar kelimeler 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 .ExternalHelp açıklama tabanlı yardım anahtar sözcüğünü kullanın. Bu anahtar sözcük olmadan, Get-Help işlev yardım konusu bulunamıyor ve işlev için yapılan çağrılar Get-Help yalnızca otomatik olarak oluşturulan yardımı döndürüyor.

    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. Cmdlet'i Yazma Yardımı.

Ayrıca bakınız

  • Last updated on