about_Functions
適用於: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
主題
about_Functions
簡短描述
說明如何在 Windows PowerShell® 中建立並使用函式。
詳細描述
函式是 Windows PowerShell 陳述式的清單，具有您指派的名稱。當執行函式時，您會輸入函式名稱。清單中的陳述式會如同您在命令提示字元中輸入般執行。
函式可以像是下列範例一樣簡單：
function Get-PowerShellProcess {Get-Process PowerShell}
或者如同 Cmdlet 或應用程式一樣複雜。
函式像 Cmdlet 一樣，可以具有參數。參數可以是具名、位置、切換或動態參數。函式參數可以從命令列或管線讀取。
函數可以傳回值，該值可以顯示、指派給變數，或傳遞到其他函式或 Cmdlet。
函式的陳述式清單可以包含不同類型的陳述式清單，其中具有關鍵字 Begin、Process 和 End。這些陳述式清單以不同方式處理來自管線的輸入。
篩選是一種特殊的函式，使用關鍵字 Filter。
函式也可以像是 Cmdlet。您可以不使用 C# 程式設計的方式來建立和 Cmdlet 運作方式相同的函式。如需詳細資訊，請參閱 about_Functions_Advanced (https://go.microsoft.com/fwlink/?LinkID=144511)。
語法
函式的語法如下：
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
函式包含下列項目：
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
如需有關 Dynamicparam 關鍵字和函式中的動態參數的詳細資訊，請參閱 about_Functions_Advanced_Parameters。
簡單的函式
函式不需要太複雜就很有用。最簡單的函式具有下列格式：
function <function-name> {statements}
例如，下列函式使用 [以系統管理員身分執行] 選項，啟動 Windows 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 {$_.LastWriteTime -gt $Start}
}
您可以建立有用小函式的工具箱。如 about_Profiles 中與本主題稍後所述，將這些函式新增至您的 Windows PowerShell 設定檔。
函式名稱
您可以為函式指派任何名稱，但是與其他人共用的函式應該遵循為所有 Windows PowerShell 命令建立的命名規則。
函式名稱應該包含動詞-名詞配對，其中動詞會識別函式執行的動作，而名詞會識別此 Cmdlet 執行其動作所在的項目。
函式應該使用對所有 Windows PowerShell 命令已核准的標準動詞。這些動詞會幫助我們讓命令名稱保持簡單、一致且方便使用者了解。
如需有關標準 Windows PowerShell 動詞的詳細資訊，請參閱 MSDN 上的＜Cmdlet 動詞＞，位於：https://go.microsoft.com/fwlink/?LinkID=160773。
具有參數的函式
您可以對函式使用參數，包括具名的參數、位置參數、切換參數和動態參數。如需函式中動態參數的詳細資訊，請參閱 about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173)。
具名的參數
您可以定義任何數目的具名參數。您可以如本主題稍後所述來包含具名參數的預設值。
您可以定義大括弧內具有 Param 關鍵字的參數，如下列範例語法所示：
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
您也可以定義大括弧外沒有 Param 關鍵字的參數，如下列範例語法所示：
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
這兩個方法之間沒有任何差異。使用您偏好的方法。
當您執行此函式時，會將您對參數提供的值指派給包含參數名稱的變數。該變數的值可用於函式中。
下列範例是稱為 Get-SmallFiles 的函式。此函式具有 $size 參數。函式會顯示小於 $size 參數值的所有檔案，並且會排除目錄：
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
在函式中，您可以使用 $size 變數，這是針對參數定義的名稱。
若要使用此函式，輸入下列命令：
C:\PS> function Get-SmallFiles –Size 50
您也可以輸入不含參數名稱的具名參數的值。例如，下列命令會提供與命名 Size 參數之命令相同的結果：
C:\PS> function Get-SmallFiles 50
若要定義參數的預設值，在參數名稱後面輸入等號和值，如 Get-SmallFiles 範例的下列變數中所示：
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
如果您輸入 "Get-SmallFiles" 時沒有值，函式會指派 100 給 $size。如果您提供值，函式會使用該值。
(選擇性) 您可以提供描述參數預設值的簡短說明字串，方法是將 PSDefaultValue 屬性新增至您的參數描述，並指定 PSDefaultValue 的 Help 屬性。若要提供說明字串，描述 Get-SmallFiles 函式中 Size 參數的預設值 (100)，請新增 PSDefaultValue 屬性，如下列範例所示。
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$size = 100
)
如需有關 PSDefaultValue 屬性類別的詳細資訊，請參閱 MSDN 上的＜PSDefaultValue 屬性成員＞。(https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx
位置參數
位置參數是不含參數名稱的參數。Windows PowerShell 會使用參數值順序讓每個參數值與函式中的參數產生關聯。
當您使用位置參數時，請在函式名稱後面輸入一或多個值。位置參數值會指派給 $args 陣列變數。接在函式名稱後面的值會指派至 $args 陣列 $args[0] 的第一個位置。
下列 Get-Extension 函式會將 .txt 副檔名新增至您提供的檔案名稱：
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
切換參數
切換參數是不需要值的參數。而是您輸入函式名稱後面接續切換參數的名稱。
若要定義切換參數，指定參數名稱前面的類型 [切換參數]，如下列範例所示：
function Switch-Item {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
當您在函式名稱後面輸入 On 切換參數時，函式會顯示「開啟」。沒有切換參數時，它會顯示「關閉」。
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
當您執行函式時，您也可以將布林值指派給切換參數，如下列範例所示：
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
使用 Splatting 代表命令參數
您可以使用展開來代表命令的參數。此功能是在 Windows PowerShell 3.0 中引進。
在工作階段中呼叫命令的函式中使用這項技術。您不需要宣告或列舉命令參數，或在命令參數變更時變更函式。
下列範例函式會呼叫 Get-Command Cmdlet。命令會使用 @Args 代表 Get-Command 的參數。
function Get-MyCommand { Get-Command @Args }
當您呼叫 Get-MyCommand 函式時，可以使用 Get-Command 的所有參數。參數和參數值會傳遞給使用 @Args 的命令。
PS C:\>Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
@Args 功能會使用 $Args 自動參數，其代表剩餘的引數中未宣告的 Cmdlet 參數和值。
如需展開的相關詳細資訊，請參閱 about_Splatting (https://go.microsoft.com/fwlink/?LinkId=262720)。
將物件輸送至函式
任何函式可以接受來自管線的輸入。您可以使用 Begin、Process 和 End 關鍵字，控制函式如何處理來自管線的輸入。下列範例語法顯示三個關鍵字：
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Begin 陳述式清單只會在函式的開頭執行一次。
Process 陳述式清單會對管線中的每個物件各執行一次。執行 Process 區塊時，會將每個管線物件指派給 $_ 自動變數，一次一個管線物件。
函式接收管線中的所有物件之後，End 陳述式清單就會執行一次。如果未使用 Begin、Process 或 End 關鍵字，所有陳述式會被視為 End 陳述式清單。
下列函式使用 Process 關鍵字。函式會顯示來自管線的範例：
function Get-Pipeline
{
process {"The value is: $_"}
}
為了示範這個函式，請如下列範例所示輸入以逗號分隔的數字清單：
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
當您在管線中使用函式時，輸送至函式的物件會指派給 $input 自動變數。函式會在管線輸出任何物件之前，執行具有 Begin 關鍵字的陳述式。函式會在從管線接收所有物件之後，執行具有 End 關鍵字的陳述式。
下列範例顯示具有 Begin 和 End 關鍵字的 $input 自動變數。
function Get-PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
如果此函式是藉由使用管線來執行，它會顯示下列結果：
C:\PS> 1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Begin 陳述式執行時，函式沒有來自管線的輸入。End 陳述式會在函式具有值之後執行。
如果函式具有 Process 關鍵字，則函式會讀取 $input 中的資料。下列範例具有 Process 陳述式清單：
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
在此範例中，每個輸送至函式的物件會傳送至 Process 陳述式清單。Process 陳述式會在每個物件上執行，一次一個物件。當函式達到 End 關鍵字時，$input 自動變數是空的。
C:\PS> 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 {$_.DependentServices} }
當函式在全域範圍中時，您可以在指令碼、函式以及命令列中使用函式。
函式通常會建立一個範圍。函式中建立的項目 (例如變數) 僅存在於函式範圍。
如需 Windows PowerShell 中範圍的詳細資訊，請參閱 about_Scopes (https://go.microsoft.com/fwlink/?LinkID=113260)。
使用函式尋找和管理函式：磁碟機
Windows PowerShell 中的所有函式和篩選會自動儲存於函式：。此磁碟機由 Windows PowerShell 函式提供者公開。
參照函式：磁碟機時，就在函式後面輸入冒號，就像您參照電腦的 C 或 D 磁碟機一樣。
下列命令會顯示 Windows PowerShell 目前工作階段中的所有函式：
Get-ChildItem function:
函式中的命令會儲存為函式定義屬性中的指令碼區塊。例如，若要顯示 Windows PowerShell 隨附的 Help 函式中的命令，輸入：
(Get-ChildItem function:help).Definition
如需函式：磁碟機的詳細資訊，請參閱函式提供者的說明主題。輸入 "Get-Help Function" 或在 TechNet Library 中進行檢視，位於：https://go.microsoft.com/fwlink/?LinkID=113436。
在新的工作階段中重複使用函式
當您在 Windows PowerShell 命令提示字元中輸入函式時，函式會成為目前工作階段的一部分。到工作階段結束為止可以使用。
若要在所有 Windows PowerShell 工作階段中使用您的函式，將函式新增至您的 Windows PowerShell 設定檔。如需設定檔的詳細資訊，請參閱 about_Profiles (https://go.microsoft.com/fwlink/?LinkID=113729)。
您也可以在 Windows 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_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
函式 (提供者)