主題
about_Functions
簡短描述
描述如何在 Windows PowerShell 中建立和使用函數。
完整描述
函數是具有您所指派之名稱的陳述式清單。當您執行函數時，要輸入函數名稱。清
單中的陳述式就會執行，如同您在命令提示字元輸入陳述式一樣。
與 Cmdlet 一樣，函數可以擁有參數。這些參數可以為具名、位置、切換或動態參
數。可以從命令列或管線讀取函數參數。
函數所傳回的值則可加以顯示、指派給變數，或是傳遞給其他函數或 Cmdlet。
函數的陳述式清單可以包含具有 Begin、Process 和 End 關鍵字的不同類型的陳述
式清單。這些陳述式清單會以不同的方式處理來自管線的輸入。
篩選器是使用 Filter 關鍵字的特殊函數類型。
函數也可以具有與 Cmdlet 相同的功能。您不需使用 C# 程式設計，就可以建立功
能與 Cmdlet 相同的函數。如需詳細資訊，請參閱 about_Functions_Advanced。
語法
函數的語法如下：
function [<範圍:>]<名稱>
[([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<陳述式清單>}
begin {<陳述式清單>}
process {<陳述式清單>}
end {<陳述式清單>}
}
函數包括下列項目：
- Function 關鍵字
- 範圍 (選擇性)
- 您選取的名稱
- 任何數量的具名參數 (選擇性)
- 包含在大括號 ({}) 中的一或多個 Windows PowerShell 命令
如需函數中的 Dynamicparam 關鍵字和動態參數的詳細資訊，請參閱
about_Functions_Advanced_Parameters。
簡單函數
函數不必複雜，也可以很有用。下列函數會取得不屬於目前系統的 System 帳戶
的環境變數：
function other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<System>"}
}
若要執行此函數，請輸入 "other_env"。
您可以建立工具箱，其中納入有用的小函數。請將這些函數新增到 Windows
PowerShell 設定檔，如 about_Profiles 和本主題稍後內容所述。
具有參數的函數
您可以將參數搭配函數使用，包括具名參數、位置參數、切換參數和動態參數等。
如需 函數中的動態參數的詳細資訊，請參閱
about_Functions_Advanced_Parameters。
具名參數
您可以定義任何數量的具名參數。您可以包含具名參數的預設值，如本主題稍後內
容所述。
您可以使用 Param 關鍵字在大括號中定義參數，如下列範例語法所示：
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
您也可以不用 Param 關鍵字而在大括號外定義參數，如下列範例語法所示：
function <名稱> [([type]$parameter1[,[type]$parameter2])] {
<陳述式清單>
}
這兩種方法之間並無差異， 請依您的喜好選擇。
當您執行函數時，為參數所提供的值會指派給包含參數名稱的變數。該變數的值可
用於函數中。
以下範例示範稱為 Small_files 的函數。這個函數具有 $size 參數。會顯示所有
小於 $size 參數值的檔案，並且排除目錄：
function small_files {
param ($size)
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
在此函數中，您可以使用 $size 變數，也就是為參數所定義的名稱。
若要使用此函數，請輸入下列命令：
C:\PS> function small_files -size 50
您也可以輸入具名參數的值，而不輸入參數名稱。例如，下列命令的結果，與為
Size 參數命名的命令相同：
C:\PS> function small_files 50
若要定義參數的預設值，請在參數名稱之後輸入等號及值，如下列 Small_files
範例的變化形式所示：
function small_files ($size = 100) {
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
如果您輸入 "small_files" 而不提供值，則函數會指派 100 給 $size。如果您提
供值，則函數會使用該值。
位置參數
位置參數是不具參數名稱的參數。Windows PowerShell 會使用參數值順序，將每個
參數值與函數中的一個參數建立關聯。
當您使用位置參數時，請在函數名稱之後輸入一或多個值。位置參數值會指派給
$args 陣列變數。接在函數名稱後的值會指派給 $args array, $args[0] 中的
第一個位置。
下列 Extension 函數會將 .txt 副檔名新增到您提供的檔案名稱：
function extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> extension myTextFile
myTextFile.txt
函數可使用一個以上的位置參數。下列範例顯示任何以函數名稱所輸入的值。
function repeat { foreach ($arg in $args) { "輸入為 $arg" } }
C:\PS>repeat 一
輸入為一
C:\PS> repeat 一二三
輸入為一
輸入為二
輸入為三
此函數可用於任何數量的值。此函數可將每個值指派到 $args 陣列中的位置。
切換參數
切換參數是不需要值的參數。相反地，您要輸入函數名稱，後面接著切換參數的
名稱。
若要定義切換參數，請在參數名稱之前指定類型 [switch]，如下列範例所示：
function switchExample {
param ([switch]$on)
if ($on) { "開啟" }
else { "關閉" }
}
當您在函數名稱之後輸入 On 切換參數時，該函數會顯示「開啟」。沒有切換參
數時，會顯示「關閉」。
C:\PS> SwitchExample -on
開啟
C:\PS> SwitchExample
關閉
您也可以在執行函數時將布林值指派給切換參數，如下列範例所示：
C:\PS> SwitchExample -on:$true
Switch on
C:\PS> SwitchExample -on:$false
Switch off
經由管線將物件輸出至函數
任何函數都可以使用來自管線的輸入。您可以使用 Begin、Process 和 End 關
鍵字，對函數處理來自管線之輸入的方式進行控管。下列範例語法會示範這三個
關鍵字：
function <名稱> {
begin {<陳述式清單>}
process {<陳述式清單>}
end {<陳述式清單>}
}
Begin 陳述式清單只會在函數起始處執行一次。
Process 陳述式清單會針對管線中的每個命令執行一次。
在 Process 區塊執行時，每個管線物件都會指派到 $_ 自動變數，且一次指派一
個管線物件。
在函數收到管線中的所有物件之後，End 陳述式清單會執行一次。如果沒有使用任
何 Begin、Process 和 End 關鍵字，則所有的陳述式都會被視為 End 陳述式清單。
下列函數會使用 Process 關鍵字。此函數會顯示來自管線的範例：
function pipelineFunction
{
process {"值為：$_"}
}
若要示範此函數，請輸入以逗號建立的數字陣列，如下列範例所示：
C:\PS> 1,2,4 | pipelineFunction
值為：1
值為：2
值為：4
當您在管線中使用函數時，傳入函數的物件會指派給 $input 自動變數。函數會在
從管線傳來任何物件之前，執行具有 Begin 關鍵字的陳述式。而在從管線收到所
有物件之後，函數就會執行具有 End 關鍵字的陳述式。
下列範例示範具有 Begin 和 End 關鍵字的 $input 自動變數。
function PipelineBeginEnd
{
begin {"開始：輸入為 $input"}
end {"結束：輸入為 $input" }
}
如果此函數是藉由管線而執行，則會顯示下列結果：
C:\PS> 1,2,4 | PipelineBeginEnd
開始：輸入為
結束：輸入為 1 2 4
當 Begin 陳述式執行時，函數沒有來自管線的輸入。End 陳述式會在函數具有這
些值之後執行。
如果函數具有 Process 關鍵字，則函數會讀取 $input 中的資料。下列範例具有
Process 陳述式清單：
function PipelineInput
{
process {"正在處理：$_ " }
end {"結束：輸入為：$input" }
}
在此範例中，每個經由管道輸出至函數的物件都會傳送到 Process 陳述式清單。
Process 陳述式會在每個物件上執行，一次執行一個物件。當函數到達 End 關鍵
字時，$input 自動變數是空的。
C:\PS> 1,2,4 | PipelineInput
正在處理：1
正在處理：2
正在處理：4
結束：輸入為：
篩選器
篩選器是在管線中的每個物件上執行的函數類型。篩選器類似於所有陳述式都位於
Process 區塊中的函數。
篩選器的語法如下所示：
filter [<範圍:>]<名稱> {<陳述式清單>}
下列的篩選器會從管線取得記錄項目，然後再顯示整個項目或只顯示項目的訊息部
分：
filter ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message } else
{ $_ }
}
函數範圍
函數會存在於當初建立時所在的範圍。
如果函數是指令碼的一部分，則該函數可提供該指令碼內的陳述式使用。根據預
設，指令碼中的函數不可用於命令提示字元。
您可以指定函數的範圍。例如，在下列範例中，函數會新增到全域範圍：
function global:get-dependentsvs { get-service | where
{$_.dependentservices} }
當函數位於全域範圍時，您可以在指令碼、函數和命令提示字元使用函數。
函數通常會建立範圍。在函數中建立的項目 (例如變數) 只能存在於函數範圍中。
如需 Windows PowerShell 中的範圍的詳細資訊，請參閱 about_Scope。
使用 Function: 磁碟機尋找及管理函數：在 Windows PowerShell 中所有的函數和篩
選器都會自動儲存在 Function: 磁碟機中。這個磁碟機會由 Windows PowerShell
Function 提供者公開。
參考 Function: 磁碟機時，請在 Function 之後輸入冒號，就如同您在參照電腦的
C 或 D 磁碟機時的做法。
下列命令會顯示 Windows PowerShell 目前工作階段中的所有函數：
C:\PS> dir function:
函數中的命令會以指令碼區塊的形式儲存在函數的定義屬性中。例如，若要顯示
Windows PowerShell 所隨附的 Help 函數中的命令，請輸入：
(dir function:help).definition
如需 Function: 磁碟機的詳細資訊，請參閱 Function。
在新的工作階段中重複使用函數
在 Windows PowerShell 命令提示字元輸入函數時，該函數就會變成目前工作階段的
一部分， 在該工作階段結束之前都可以使用。
若要在所有的 Windows PowerShell 工作階段中使用某函數，請將其新增到
Windows PowerShell 設定檔。如需設定檔的詳細資訊，請參閱 about_Profiles。
您也可以將函數儲存在 Windows PowerShell 指令檔中。請在文字檔中輸入函數，
然後以 .ps1 副檔名儲存該檔案。
撰寫函數的說明
Get-Help Cmdlet 會取得函數以及 Cmdlet、提供者和指令碼的說明。若要取得函數
的說明，請輸入 Get-Help，後面接著函數名稱。
例如，若要取得 MyDisks 函數的說明，請輸入：
get-help MyDisks
您可以使用下列兩種方法之一來撰寫函數的說明：
-- 以註解為基礎的函數說明
您可以在註解中使用特殊的關鍵字來建立說明主題。若要建立以註解為基礎的函
數說明，註解必須放在函數主體的起始或結尾處，或放在函數關鍵字之前的行
中。如需以註解為基礎之說明的詳細資訊，請參閱 about_Comment_Based_Help。
-- 以 XML 為基礎的函數說明
您可以建立以 XML 為基礎的說明主題，例如通常會為 Cmdlet 所建立的說明類
型。如果您要將說明主題當地語系化為多種語言，就必須使用以 XML 為基礎的說
明。
若要將函數與以 XML 為基礎的說明主題建立關聯，請使用 .ExternalHelp 說明
註解關鍵字。如需 ExternalHelp 關鍵字的詳細資訊，請參閱
about_Comment_Based_Help。如需以 XML 為基礎之說明的詳細資訊，請參閱
MSDN 中的＜如何撰寫 Cmdlet 說明＞。
請參閱
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function (提供者)