เกี่ยวกับฟังก์ชัน CmdletBindingAttribute

คำอธิบายสั้น ๆ

อธิบายแอตทริบิวต์ที่ทำให้ฟังก์ชันทำงานเหมือนกับ cmdlet ที่คอมไพล์แล้ว

คำอธิบายยาว

แอตทริบิวต์ CmdletBinding เป็นแอตทริบิวต์ของฟังก์ชันที่ทำให้ทำงานเหมือนกับ cmdlet ที่คอมไพล์แล้วที่เขียนด้วย C# ให้การเข้าถึงคุณลักษณะของ cmdlets

เมื่อคุณใช้แอตทริบิวต์ CmdletBinding PowerShell จะเพิ่มพารามิเตอร์ทั่วไปโดยอัตโนมัติ คุณไม่สามารถสร้างพารามิเตอร์ใดๆ ที่ใช้ชื่อเดียวกันกับพารามิเตอร์ทั่วไปได้ สำหรับข้อมูลเพิ่มเติม โปรดดู about_CommonParameters

PowerShell ผูกพารามิเตอร์ของฟังก์ชันที่มีแอตทริบิวต์ CmdletBinding ในลักษณะเดียวกับที่ผูกพารามิเตอร์ของ cmdlets ที่คอมไพล์แล้ว ตัวแปรอัตโนมัติ $PSCmdlet พร้อมใช้งานสำหรับฟังก์ชันที่มีแอตทริบิวต์ CmdletBinding แต่ไม่มีตัวแปร $Args

ในฟังก์ชันที่มีแอตทริบิวต์ CmdletBinding พารามิเตอร์ที่ไม่รู้จักและอาร์กิวเมนต์ตำแหน่งที่ไม่มีพารามิเตอร์ตำแหน่งที่ตรงกันทำให้การรวมพารามิเตอร์ล้มเหลว

ไวยากรณ์

ตัวอย่างต่อไปนี้แสดงรูปแบบของฟังก์ชันที่ระบุอาร์กิวเมนต์ทางเลือกทั้งหมดของแอตทริบิวต์ CmdletBinding คำอธิบายโดยย่อของแต่ละอาร์กิวเมนต์เป็นไปตามตัวอย่างนี้

{
    [CmdletBinding(ConfirmImpact=<String>,
    DefaultParameterSetName=<String>,
    HelpURI=<URI>,
    SupportsPaging=<Boolean>,
    SupportsShouldProcess=<Boolean>,
    PositionalBinding=<Boolean>)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

ประเภทอาร์กิวเมนต์บูลีนของแอตทริบิวต์ CmdletBinding มีค่าเริ่มต้นเป็น False เมื่อละเว้นจากแอตทริบิวต์ CmdletBinding ตั้งค่าอาร์กิวเมนต์เป็น $true หรือเพียงแสดงรายการอาร์กิวเมนต์ตามชื่อ ตัวอย่างเช่น แอตทริบิวต์ CmdletBinding ต่อไปนี้เทียบเท่ากัน

{
    [CmdletBinding(SupportsPaging=$true)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

ConfirmImpact

อาร์กิวเมนต์ ConfirmImpact ระบุว่าเมื่อใดควรยืนยันการทำงานของฟังก์ชันโดยการเรียกเมธอด ShouldProcess การเรียกใช้เมธอด ShouldProcess จะแสดงพร้อมท์การยืนยันเฉพาะเมื่ออาร์กิวเมนต์ ConfirmImpact เท่ากับหรือมากกว่าค่าของตัวแปรการตั้งค่า $ConfirmPreference . (ค่าเริ่มต้นของอาร์กิวเมนต์คือ ปานกลาง) ระบุอาร์กิวเมนต์นี้เฉพาะเมื่อมีการระบุอาร์กิวเมนต์ SupportsShouldProcess ด้วย

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับคำขอยืนยัน โปรดดูที่การขอการยืนยัน

DefaultParameterSetName

อาร์กิวเมนต์ DefaultParameterSetName ระบุชื่อของชุดพารามิเตอร์ที่ PowerShell จะพยายามใช้เมื่อไม่สามารถระบุได้ว่าจะใช้ชุดพารามิเตอร์ใด คุณสามารถหลีกเลี่ยงปัญหานี้ได้โดยการกำหนดให้พารามิเตอร์เฉพาะของแต่ละพารามิเตอร์ตั้งค่าพารามิเตอร์บังคับ

ช่วยเหลือURI

อาร์กิวเมนต์ HelpURI ระบุที่อยู่อินเทอร์เน็ตของหัวข้อวิธีใช้เวอร์ชันออนไลน์ที่อธิบายฟังก์ชัน ค่าของอาร์กิวเมนต์ HelpURI ต้องขึ้นต้นด้วย "http" หรือ "https"

ค่าอาร์กิวเมนต์ HelpURI ใช้สำหรับค่าของคุณสมบัติ HelpURI ของออบเจ็กต์ CommandInfo ที่ Get-Command ส่งคืน สำหรับฟังก์ชั่น

อย่างไรก็ตาม เมื่อมีการติดตั้งไฟล์วิธีใช้บนคอมพิวเตอร์และค่าของลิงก์แรกในส่วน RelatedLinks ของไฟล์วิธีใช้คือ URI หรือค่าของ .Link คำสั่งในความช่วยเหลือตามความคิดเห็นคือ URI โดย URI ในไฟล์วิธีใช้จะถูกใช้เป็นค่าของคุณสมบัติ HelpUri ของฟังก์ชัน

Get-Help cmdlet ใช้ค่าของคุณสมบัติ HelpURI เพื่อค้นหาเวอร์ชันออนไลน์ของหัวข้อวิธีใช้ฟังก์ชันเมื่อพารามิเตอร์ Online ของ Get-Help ถูกระบุในคำสั่ง

SupportsPaging

อาร์กิวเมนต์ SupportsPaging จะเพิ่มพารามิเตอร์ First, Skip และ IncludeTotalCount ให้กับฟังก์ชัน พารามิเตอร์เหล่านี้อนุญาตให้ผู้ใช้เลือกเอาต์พุตจากชุดผลลัพธ์ที่มีขนาดใหญ่มาก อาร์กิวเมนต์นี้ออกแบบมาสำหรับ cmdlet และฟังก์ชันที่ส่งคืนข้อมูลจากที่เก็บข้อมูลขนาดใหญ่ที่รองรับการเลือกข้อมูล เช่น ฐานข้อมูล SQL

อาร์กิวเมนต์นี้ถูกนำมาใช้ใน Windows PowerShell 3.0

• อันดับแรก: รับเฉพาะวัตถุ 'n' ตัวแรกเท่านั้น
• ข้าม: ละเว้นวัตถุ 'n' แรกแล้วรับวัตถุที่เหลือ
• IncludeTotalCount: รายงานจำนวนออบเจ็กต์ในชุดข้อมูล (จำนวนเต็ม) ตามด้วยออบเจ็กต์ หาก cmdlet ไม่สามารถระบุจำนวนรวมได้ ระบบจะส่งกลับ "จำนวนรวมที่ไม่รู้จัก"

PowerShell ประกอบด้วย NewTotalCount ซึ่งเป็นวิธีการช่วยเหลือที่รับค่าการนับรวมที่จะส่งคืน และรวมถึงการประมาณความแม่นยำของค่าการนับทั้งหมด

ฟังก์ชันตัวอย่างต่อไปนี้แสดงวิธีการเพิ่มการสนับสนุนสำหรับพารามิเตอร์การเพจให้กับฟังก์ชันขั้นสูง

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    param()

    $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
    $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
      $FirstNumber - 1, 100)

    if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
        $TotalCountAccuracy = 1.0
        $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
          $TotalCountAccuracy)
        Write-Output $TotalCount
    }
    $FirstNumber .. $LastNumber | Write-Output
}

รองรับกระบวนการควร

อาร์กิวเมนต์ SupportsShouldProcess เพิ่มพารามิเตอร์ ยืนยัน และ WhatIf ให้กับฟังก์ชัน พารามิเตอร์ ยืนยัน จะแจ้งให้ผู้ใช้ก่อนที่จะรันคำสั่งกับแต่ละออบเจ็กต์ในไปป์ไลน์ พารามิเตอร์ WhatIf แสดงรายการการเปลี่ยนแปลงที่คำสั่งจะทำ แทนที่จะเรียกใช้คำสั่ง

PositionalBinding

อาร์กิวเมนต์ PositionalBinding กำหนดว่าพารามิเตอร์ในฟังก์ชันมีตำแหน่งตามค่าเริ่มต้นหรือไม่ ค่าเริ่มต้นคือ $True คุณสามารถใช้อาร์กิวเมนต์ PositionalBinding ที่มีค่า $False เพื่อปิดใช้งานการเชื่อมโยงตำแหน่ง

อาร์กิวเมนต์ PositionalBinding ถูกนำมาใช้ใน Windows PowerShell 3.0

เมื่อพารามิเตอร์อยู่ในตำแหน่ง ชื่อพารามิเตอร์จะเป็นทางเลือก PowerShell เชื่อมโยงค่าพารามิเตอร์ที่ไม่มีชื่อกับพารามิเตอร์ฟังก์ชันตามลำดับหรือตำแหน่งของค่าพารามิเตอร์ที่ไม่มีชื่อในคำสั่งฟังก์ชัน

เมื่อพารามิเตอร์ไม่อยู่ในตำแหน่ง (เป็น "ชื่อ") จำเป็นต้องมีชื่อพารามิเตอร์ (หรือตัวย่อหรือนามแฝงของชื่อ) ในคำสั่ง

เมื่อ PositionalBinding เป็น $True พารามิเตอร์ฟังก์ชันจะมีตำแหน่งตามค่าเริ่มต้น PowerShell กำหนดหมายเลขตำแหน่งให้กับพารามิเตอร์ตามลำดับที่ประกาศไว้ในฟังก์ชัน

เมื่อ PositionalBinding เป็น $False พารามิเตอร์ฟังก์ชันจะไม่ถูกกำหนดตำแหน่งตามค่าเริ่มต้น เว้นแต่จะมีการประกาศอาร์กิวเมนต์ ตำแหน่ง ของแอตทริบิวต์ พารามิเตอร์ บนพารามิเตอร์ ชื่อพารามิเตอร์ (หรือนามแฝงหรือตัวย่อ) จะต้องรวมไว้ด้วยเมื่อใช้พารามิเตอร์ในฟังก์ชัน

อาร์กิวเมนต์ ตำแหน่ง ของแอตทริบิวต์ พารามิเตอร์ จะมีความสำคัญเหนือกว่าค่าเริ่มต้น PositionalBinding คุณสามารถใช้อาร์กิวเมนต์ ตำแหน่ง เพื่อระบุค่าตำแหน่งสำหรับพารามิเตอร์ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับอาร์กิวเมนต์ ตำแหน่ง โปรดดู about_Functions_Advanced_Parameters

หมายเหตุ

อาร์กิวเมนต์ SupportsTransactions ไม่ได้รับการสนับสนุนในฟังก์ชันขั้นสูง

คำหลัก

about_Functions_CmdletBinding_Attribute

ดูเพิ่มเติม

• about_Functions
• about_Functions_ขั้นสูง
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_OutputTypeAttribute