about_Functions

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, 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şi 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 davranabilir. 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ının ve betik tabanlı modüllerin içinde işlevlerin çağrılabilmesi için önce tanımlanması gerekir.

Syntax

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 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 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 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 de 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üğü 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 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

Adlandırılmış parametre için parametre adı olmadan da bir değer 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, aşağıdaki örnekte gösterildiği gibi bir eşittir işareti ve parametre adından Get-SmallFiles sonraki 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 100 $sizeatar. Bir değer sağlarsanız işlev bu değeri kullanır.

İsteğe bağlı olarak, parametrenizin açıklamasına PSDefaultValue özniteliğini ekleyerek ve PSDefaultValueHelp ö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$args[0]ilk konuma 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.

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

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

İşlev adından On sonra switch parametresini 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 bir anahtara Boole değeri de atayabilirsiniz:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Komut Parametrelerini Temsil Etmek için Sıçratmayı Kullanma

Bir komutun parametrelerini temsil etmek için sıçratmayı 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 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 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 Aktarma

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:

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

Önemli

İşleviniz bu adlandırılmış deyim listelerinden birini tanımlıyorsa, tüm kodunuz bu bloklardan birinin içinde olmalıdır. Blokların dışındaki kodlar tanınmaz. İşleviniz bu bloklardan hiçbirini kullanmıyorsa, tüm deyimler bir end deyim listesi olarak kabul edilir.

deyim begin listesi, işlevin başında yalnızca bir kez çalışı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( tek seferde bir işlem hattı nesnesi).

İşlev işlem hattındaki tüm nesneleri aldıktan sonra, end deyim listesi bir kez çalışır.

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

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

Aşağıdaki örnekte ve end anahtar sözcükleriyle $inputbegin otomatik değişken 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 deyimi çalıştırıldığında, işlev işlem hattından gelen girişe sahip olmaz. end deyimi, işlev 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önlendirilen her nesne deyim listesine gönderilir process . Deyimler process her nesne üzerinde, bir kerede bir nesne üzerinde çalışır. İş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ğunu clean ekledi. 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ırma hatası olmadan normal şekilde tamamlandığında
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, bu bir sorun olmayabilir. 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 tarafından 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 otomatik olarak sürücüde Function: 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 D sürücüsüne Function: başvururken C yaptığınız gibi İşlev'in arkasına iki nokta üst üste 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ım

PowerShell komut istemine bir işlev yazdığınızda, işlev geçerli oturumun bir parçası olur. İşlev oturum bitene 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

Get-Help cmdlet işlevleri ve 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 Comment-Based 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 ya da 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-Based 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ü kullanın .EXTERNALHELP . Bu anahtar sözcük olmadan işlev Get-Help 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.

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Parameters
• about_Profiles
• about_Scopes
• about_Script_Blocks