關於 Functions

簡短描述

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

完整描述

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

函式可以像：

function Get-PowerShellProcess { Get-Process PowerShell }

函數也可以像 cmdlet 或應用程式一樣複雜。

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

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

函式的語句清單可以包含不同類型的語句清單，其中包含關鍵詞 Begin、 Process和 End。 這些語句清單會以不同的方式處理來自管線的輸入。

過濾器是一種使用關鍵字的特殊 Filter 函數。

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

語法

以下是函數的語法：

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}

例如，以下函數使用 Run as Administrator （以管理員身份運行） 選項啟動 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 文檔中 的已批准謂 詞。

具有參數的函式

您可以搭配函式使用參數，包括具名參數、位置參數、參數參數和動態參數。 如需函式中動態參數的詳細資訊，請參閱 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 屬性新增至參數的描述，並指定 PSDefaultValue 的 Help 屬性。 若要提供說明字串，描述函式中 SizeGet-SmallFiles預設值 （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 參數，請在參數名稱之前指定類型 [switch] ，如下列範例所示：

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

當您在函數名稱後鍵入 On switch 參數時，函數將顯示 「Switch on」。 如果沒有 switch 參數，則顯示 「Switch off」。

Switch-Item -on

Switch on

Switch-Item

Switch off

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

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

使用 Splatting 代表命令參數

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

在呼叫會話中命令的函式中使用這項技術。 您無需聲明或枚舉命令參數，也無需在命令參數更改時更改函數。

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

function Get-MyCommand { Get-Command @Args }

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

Get-MyCommand -Name Get-ChildItem

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

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

有關展開的更多資訊，請參閱 about_Splatting。

將物件管線傳送至函式

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

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

語句清單 Begin 僅在函數開始時運行一次。

這很重要

如果您的函數定義了 Begin， Process 或 End 塊，則所有代碼都必須位於其中一個塊內。

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

在函數收到管道中的所有物件后， End 語句 list 將運行一次。 如果未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 和 Begin 關鍵詞的 End 自動變數。

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 statement list。 語句 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 。

撰寫函式的說明

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

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

Get-Help Get-MyDisks

您可以使用以下兩種方法之一為函數編寫説明：

• 函式的批註型說明

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

• 以 XML 為基礎的函式說明

  創建基於 XML 的幫助主題，例如通常為 cmdlet 創建的類型。 如果您要將說明主題當地語系化為多種語言，則需要 XML 型說明。

  若要將函式與 XML 型說明主題產生關聯，請使用以批注為基礎的說明關鍵詞 .ExternalHelp。 如果沒有此關鍵字， Get-Help 則無法找到函數説明主題，並且對函數的 Get-Help 調用僅返回自動生成的説明。

  如需 關鍵詞的詳細資訊 ExternalHelp ，請參閱 about_Comment_Based_Help。 有關基於 XML 的説明的更多資訊，請參見 MSDN 庫中的 如何編寫 Cmdlet 説明 。

另請參閱

自動變數概覽

關於_基於註釋的幫助

about_Functions_Advanced

函數進階方法簡介

關於_函數_進階_參數

about_Functions_CmdletBindingAttribute

關於_函數_輸出類型屬性

關於_參數

關於_簡介

about_Scopes

關於腳本區塊

about_Function_provider