關於函式

簡短描述

說明如何在 PowerShell 中建立和使用函式。

完整描述

「函式」（function）是具有您所指派名稱的 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。

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屬性新增至參數的描述，並指定PSDefaultValue的help屬性，來提供描述參數預設值的簡短說明字串。若要提供說明字串來描述函式中Size參數的預設值（100） Get-SmallFiles ，請加入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 on"。如果沒有切換參數，則會顯示「關閉切換」。

Switch-Item -on

Switch on

Switch-Item

Switch off

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

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

使用展開來代表命令參數

您可以使用展開來表示命令的參數。這項功能是在 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 語句清單就會執行一次。如果未 Begin Process 使用、或 End 關鍵字，則會將所有語句視為 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 語句清單。 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。

使用 Function：磁片磁碟機來尋找和管理函數

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

參照磁片磁碟機時，請在 [函式] Function: 後面輸入冒號，就像您在Function參照 C 電腦的或磁片磁碟機時所做的一樣 D 。

下列命令會顯示目前 PowerShell 會話中的所有函式：

Get-ChildItem function:

函式中的命令會以腳本區塊的形式儲存在函式的 definition 屬性中。例如，若要顯示 PowerShell 隨附之 Help 函式中的命令，請輸入：

(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 批註為基礎的 help 關鍵字。若沒有這個關鍵字，就找不到函式 Get-Help 說明主題，而且對函式的呼叫只會傳回 Get-Help 自動產生的說明。

如需關鍵字的詳細資訊 ExternalHelp ，請參閱about_Comment_Based_Help。如需以 XML 為基礎之說明的詳細資訊，請參閱 MSDN library 中的如何撰寫 Cmdlet 說明。