共用方式為


關於函式

簡短描述

描述如何在PowerShell中建立和使用函式。

完整描述

函式是PowerShell語句的清單,其中包含您指派的名稱。 當您執行函式時,請輸入函式名稱。 清單中的 語句會執行,就像您在命令提示字元中輸入語句一樣。

函式可以像:

function Get-PowerShellProcess { Get-Process PowerShell }

函式也可以像 Cmdlet 或應用程式程序一樣複雜。

如同 Cmdlet,函式可以有參數。 參數可以命名、位置、參數或動態參數。 函式參數可以從命令行或管線讀取。

函式可以傳回可顯示、指派給變數或傳遞至其他函式或 Cmdlet 的值。 您也可以使用 return 關鍵詞來指定傳回值。 關鍵詞 return 不會影響或隱藏函式傳回的其他輸出。 不過, return 關鍵詞會在該行結束函式。 如需詳細資訊,請參閱 about_Return

函式的語句清單可以包含不同類型的語句清單,其中包含關鍵詞 BeginProcessEnd。 這些語句會以不同的方式列出處理管線的輸入。

篩選是使用 Filter 關鍵詞的特殊函式類型。

函式也可以像 Cmdlet 一樣運作。 您可以建立像 Cmdlet 一樣運作的函式,而不需使用 C# 程序設計。 如需詳細資訊,請參閱 about_Functions_Advanced

Syntax

以下是函式的語法:

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

函式包含下列專案:

  • 關鍵詞Function
  • 選擇性 (範圍)
  • 您選取的名稱
  • 選擇性 () 任何數目的具名參數
  • 一或多個以大括弧括住的 PowerShell 命令 {}

如需函式中關鍵詞和動態參數的詳細資訊 Dynamicparam ,請參閱 about_Functions_Advanced_Parameters

簡單函式

函式不一定很複雜,才能很有用。 最簡單的函式具有下列格式:

function <function-name> {statements}

例如,下列函式會使用 [以系統管理員身分執行] 選項啟動 PowerShell。

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

若要使用 函式,請輸入: Start-PSAdmin

若要將語句新增至函式,請在個別行上輸入每個語句,或使用分號 ; 分隔 語句。

例如,下列函式會尋找在開始日期之後變更之目前用戶目錄中的所有 .jpg 檔案。

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

您可以建立實用小型函式的工具箱。 請將這些函式新增至 PowerShell 配置檔,如本主題中 about_Profiles 及更新版本所述。

函式名稱

您可以將任何名稱指派給函式,但與其他人共用的函式應該遵循針對所有 PowerShell 命令所建立的命名規則。

函式名稱應該包含動詞名詞組,其中動詞會識別函式所執行的動作,而名詞會識別 Cmdlet 執行其動作的專案。

函式應該使用已針對所有 PowerShell 命令核准的標準動詞。 這些動詞可協助我們保持命令名稱簡單、一致且容易讓用戶瞭解。

如需標準 PowerShell 動詞的詳細資訊,請參閱 Microsoft Docs 中的核准動詞

具有參數的函式

您可以搭配函式使用參數,包括具名參數、位置參數、參數和動態參數。 如需函式中動態參數的詳細資訊,請參閱 about_Functions_Advanced_Parameters

具名參數

您可以定義任意數目的具名參數。 您可以包含具名參數的預設值,如本主題稍後所述。

您可以使用 關鍵字在大括弧 Param 內定義參數,如下列範例語法所示:

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

您也可以定義大括弧以外的參數,而不使用 Param 關鍵詞,如下列範例語法所示:

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

以下是這個替代語法的範例。

Function Add-Numbers($one, $two) {
    $one + $two
}

雖然慣用第一個方法,但這兩種方法之間沒有任何差異。

當您執行函式時,您為參數提供的值會指派給包含參數名稱的變數。 該變數的值可用於函式中。

下列範例是稱為的 Get-SmallFiles函式。 此函式具有 $Size 參數。 函式會顯示小於 參數值 $Size 的所有檔案,並排除目錄:

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

在函式中,您可以使用 $Size 變數,這是為 參數定義的名稱。

若要使用此函式,請輸入下列命令:

Get-SmallFiles -Size 50

您也可以針對沒有參數名稱的具名參數輸入值。 例如,下列命令會提供與命名 Size 參數的命令相同的結果:

Get-SmallFiles 50

若要定義參數的預設值,請在參數名稱後面輸入等號和值,如下列範例的變化 Get-SmallFiles 所示:

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

如果您輸入 Get-SmallFiles 不含值,則函式會將 100 指派給 $size。 如果您提供值,函式會使用該值。

您可以選擇性地提供簡短的說明字串,藉由將 PSDefaultValue 屬性新增至參數的描述,並指定 PSDefaultValueHelp 屬性,以描述參數的預設值。 若要提供說明字串,描述函式中 Get-SmallFilesSize 參數的預設值 (100) ,請新增 PSDefaultValue 屬性,如下列範例所示。

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

如需 PSDefaultValue 屬性類別的詳細資訊,請參閱 PSDefaultValue 屬性成員

位置參數

位置參數是不含參數名稱的參數。 PowerShell 會使用參數值順序,將每個參數值與函式中的參數產生關聯。

當您使用位置參數時,請在函式名稱後面輸入一或多個值。 位置參數值會指派給 $args 陣列變數。 函式名稱後面的值會指派給陣列中的$args第一個位置。 $args[0]

下列 Get-Extension 函式會將 .txt 擴展名新增至您提供的檔案名:

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

參數

參數是不需要值的參數。 相反地,您會輸入函式名稱,後面接著 switch 參數的名稱。

若要定義 switch 參數,請在參數名稱之前指定類型 [switch] ,如下列範例所示:

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

當您在 On 函式名稱後面輸入 switch 參數時,函式會顯示「開啟」。 如果沒有 switch 參數,它會顯示「關閉」。

Switch-Item -on
Switch on
Switch-Item
Switch off

您也可以在執行函式時將 布林 值指派給參數,如下列範例所示:

Switch-Item -on:$true
Switch on
Switch-Item -on:$false
Switch off

使用 Splatting 來表示命令參數

您可以使用splatting來代表命令的參數。 此功能是在 Windows PowerShell 3.0 中引進。

在呼叫會話中命令的函式中使用這項技術。 您不需要宣告或列舉命令參數,或在命令參數變更時變更函式。

下列範例函式會呼叫 Get-Command Cmdlet。 命令會使用 @Args 來表示 的參數 Get-Command

function Get-MyCommand { Get-Command @Args }

呼叫 函式時Get-MyCommand,您可以使用 的所有參數Get-Command。 參數和參數值會使用 @Args傳遞至命令。

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

此功能 @Args 會使用 $Args 自動參數,代表其餘自變數中未宣告的 Cmdlet 參數和值。

如需有關splatting的詳細資訊,請參閱 about_Splatting

將物件管線傳送至函式

任何函式都可以從管線取得輸入。 您可以使用、 ProcessEnd 關鍵詞來控制函式如何處理來自管線Begin的輸入。 下列範例語法顯示三個關鍵字:

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

Begin語句清單只會在函式的開頭執行一次。

重要

如果您的函式定義 BeginProcessEnd 區塊,則所有程式代碼都必須位於這些區塊內。 如果已定義任何區塊,就不會在區塊外部辨識 任何 程序代碼。

Process語句清單會針對管線中的每個物件執行一次。 Process當區塊正在執行時,每個管線對象都會指派給$_自動變數,一次一個管線物件。

函式收到管線中的所有物件之後,語句清單就會 End 執行一次。 Begin如果沒有使用、 ProcessEnd 關鍵詞,所有語句都會視為End語句清單。

下列函式會使用 Process 關鍵詞。 函式會顯示管線中的範例:

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

若要示範此函式,請輸入以逗號分隔的數字清單,如下列範例所示:

1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4

當您在管線中使用函式時,傳送至函式的物件會指派給 $input 自動變數。 函式會在任何對象來自管線之前, Begin 使用 關鍵詞執行 語句。 函式會在從管線接收所有對象之後,使用 End 關鍵詞執行 語句。

下列範例顯示 $input 具有 BeginEnd 關鍵詞的自動變數。

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

如果使用管線執行此函式,則會顯示下列結果:

1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End:   The input is 1 2 4

Begin當語句執行時,函式沒有來自管線的輸入。 語句會在函 End 式具有 值之後執行。

如果函式有 Process 關鍵字,則中的 $input 每個物件都會從 $input 中移除,並指派給 $_。 下列範例有 Process 語句清單:

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

在此範例中,傳送至函式的每個物件都會傳送至 Process 語句清單。 語句 Process 會在每個物件上執行,一次一個物件。 當 $input 函式到達 關鍵詞時,自動變數是空的 End

1,2,4 | Get-PipelineInput
Processing:  1
Processing:  2
Processing:  4
End:   The input is:

如需詳細資訊,請參閱 使用列舉值

篩選器

篩選條件是在管線中的每個物件上執行的函式類型。 篩選條件類似於函式,其區塊中的所有 Process 語句。

篩選的語法如下所示:

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

下列篩選會從管線擷取記錄專案,然後顯示整個專案或只顯示項目的訊息部分:

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

函式範圍

函式存在於建立函式的範圍中。

如果函式是腳本的一部分,函式就可供該腳本內的語句使用。 根據預設,文稿中的函式無法在命令提示字元中使用。

您可以指定函式的範圍。 例如,函式會在下列範例中新增至全域範圍:

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

當函式位於全域範圍時,您可以在腳本、函式和命令行中使用 函式。

函式通常會建立範圍。 在函式中建立的專案,例如變數,只存在於函式範圍中。

如需 PowerShell 中範圍的詳細資訊,請參閱 about_Scopes

使用函式尋找和管理函式:磁碟驅動器

PowerShell 中的所有函式和篩選都會自動儲存在磁碟驅動器中 Function: 。 PowerShell 式提供者會公開此磁碟驅動器。

參考 Function: 磁碟驅動器時,請在 Function 後面輸入冒號,就像參考 C 電腦的 或 D 磁碟驅動器一樣。

下列命令會顯示 PowerShell 目前工作階段中的所有函式:

Get-ChildItem function:

函式中的命令會儲存為函式定義屬性中的腳本區塊。 例如,若要在 PowerShell 隨附的說明函式中顯示命令,請輸入:

(Get-ChildItem function:help).Definition

您也可以使用下列語法。

$function:help

如需磁碟驅動器的詳細資訊 Function: ,請參閱 式提供者的說明主題。 輸入 Get-Help Function

在新會話中重複使用函式

當您在PowerShell命令提示字元中輸入函式時,函式會變成目前會話的一部分。 在工作階段結束之前,可以使用它。

若要在所有 PowerShell 工作階段中使用您的函式,請將函式新增至 PowerShell 配置檔。 如需設定檔的詳細資訊,請參閱 about_Profiles

您也可以將函式儲存在PowerShell腳本檔案中。 在文本文件中輸入您的函式,然後使用擴展名儲存盤 .ps1 案。

撰寫函式的說明

Cmdlet Get-Help 會取得函式的說明,以及 Cmdlet、提供者和腳本的說明。 若要取得函式的說明,請輸入 Get-Help ,後面接著函式名稱。

例如,若要取得函 Get-MyDisks 式的說明,請輸入:

Get-Help Get-MyDisks

您可以使用下列兩種方法之一來撰寫函式的說明:

  • 函式的 Comment-Based 說明

    在批注中使用特殊關鍵詞來 Create 說明主題。 若要為函式建立以批注為基礎的說明,批注必須放在函式主體的開頭或結尾,或在函式關鍵詞前面的行上。 如需批注型說明的詳細資訊,請參閱 about_Comment_Based_Help

  • 函式的 XML-Based 說明

    Create XML 型說明主題,例如通常為 Cmdlet 建立的類型。 如果您要將說明主題當地語系化成多種語言,則需要以 XML 為基礎的說明。

    若要將函式與 XML 型說明主題產生關聯,請使用 .ExternalHelp 批注式說明關鍵詞。 如果沒有這個關鍵詞, Get-Help 則找不到函式說明主題,而且呼叫 Get-Help 函式只會傳回自動產生的說明。

    如需 關鍵詞的詳細資訊 ExternalHelp ,請參閱 about_Comment_Based_Help。 如需 XML 型說明的詳細資訊,請參閱 如何撰寫 Cmdlet 說明

另請參閱

about_Automatic_Variables

about_Comment_Based_Help

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

about_Function_provider