簡短描述
介紹使用腳本建立 Cmdlet 的進階函式。
完整描述
Cmdlet 是參與 PowerShell 管線語意的單一命令。 這包括二進位 Cmdlet、PowerShell 進階函式和 CDXML Cmdlet。
進階函式可讓您建立撰寫為 PowerShell 函式的 Cmdlet。 進階函式可讓您更輕鬆地建立 Cmdlet，而不需要撰寫和編譯二進位 Cmdlet。 二進位 Cmdlet 是以 .NET 語言撰寫的 .NET 類別，例如 C#。
進階函式會使用 CmdletBinding 屬性，將其識別為類似 Cmdlet 的函式。
CmdletBinding 屬性類似於在編譯的 Cmdlet 類別中使用的 Cmdlet 屬性，以將類別識別為 Cmdlet。 如您要此屬性的詳細資訊，請參閱 about_Functions_CmdletBindingAttribute。
函式的參數是在 param() 語句中宣告的變數。 您可以單獨使用選擇性的 [Parameter()] 屬性，或與 [Alias()] 屬性或任何參數驗證屬性搭配使用。 如需如何宣告參數的詳細資訊，請參閱 about_Functions_Advanced_Parameters。
下列範例顯示接受名稱的函式，然後使用提供的名稱列印問候語。 另請注意，此函式定義的名稱包含一個動詞（Send）和名詞（Greeting）組合，如同已編譯 Cmdlet 的動詞-名詞組合。 不過，函式不需要有動詞名詞名稱。
function Send-Greeting
{
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[string]$Name
)
process
{
Write-Host ("Hello " + $Name + "!")
}
}
此函式會在 process 區塊中執行工作，這相當於編譯 Cmdlet 中使用的 ProcessingRecord 方法。
process 區塊和其他具名區塊會在 about_Functions_Advanced_Methods中描述。
進階函式與已編譯的 Cmdlet 不同，方式如下：
- 當字串陣列系結至布爾值參數 時，進階函式參數系結不會擲回例外狀況。
-
ValidateSet屬性和ValidatePattern屬性無法傳遞具名參數。 - 進階函式不能用於交易。
PIPELINESTOP代幣
從 PowerShell 7.6-preview.4 開始，$PSCmdlet 包含 PipelineStopToken 屬性，允許存取系結至 PowerShell 停止事件來源的 CancellationToken。 當 PowerShell 管線收到停止的要求時，就會觸發令牌。 將它與 .NET 方法搭配使用，這個方法會接受 CancellationToken 多載，以在要求時結束方法，而不是等到方法傳回為止。
在下列範例中，函式會呼叫 HttpClient.GetStringAsync，當網路速度緩慢或傳回大量數據時，可能需要時間回應。
function Invoke-CancelableWebRequest {
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[string]
$Url
)
$client = [System.Net.Http.HttpClient]::new()
$client.GetStringAsync(
$Url,
$PSCmdlet.PipelineStopToken).GetAwaiter().GetResult()
}
Invoke-CancelableWebRequest -Url https://httpbin.org/delay/10
# Press ctrl+c to cancel
