ค้นหาเว็บไซต์

เกี่ยวกับฟังก์ชันวิธีการขั้นสูง

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

อธิบายวิธีที่ฟังก์ชันที่ระบุแอตทริบิวต์ CmdletBinding สามารถใช้วิธีการและคุณสมบัติที่พร้อมใช้งานสำหรับ cmdlets ที่คอมไพล์แล้ว

คำอธิบายยาว

ฟังก์ชันที่ระบุแอตทริบิวต์ CmdletBinding สามารถเข้าถึงวิธีการและคุณสมบัติเพิ่มเติมผ่านตัวแปร $PSCmdlet วิธีการเหล่านี้รวมถึงวิธีการต่อไปนี้:

  • วิธีการประมวลผลอินพุตแบบเดียวกันใช้ได้กับทุกฟังก์ชัน
  • วิธีการ ShouldProcess และ ShouldContinue ที่ใช้ในการรับความคิดเห็นจากผู้ใช้ก่อนดำเนินการ
  • วิธีการ ThrowTerminatingError สำหรับการสร้างบันทึกข้อผิดพลาด
  • วิธีการ Write หลายวิธีที่ส่งคืนเอาต์พุตประเภทต่างๆ

วิธีการและคุณสมบัติทั้งหมดของคลาส PSCmdlet พร้อมใช้งานสำหรับฟังก์ชันขั้นสูง สำหรับข้อมูลเพิ่มเติม โปรดดูที่ System.Management.Automation.PSCmdlet

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับแอตทริบิวต์ CmdletBinding โปรดดู about_Functions_CmdletBindingAttribute สำหรับคลาส CmdletBindingAttribute โปรดดู System.Management.Automation.Cmdlet.CmdletBindingAttribute

วิธีการประมวลผลอินพุต

วิธีการที่อธิบายไว้ในส่วนนี้เรียกว่าวิธีการประมวลผลอินพุต สำหรับฟังก์ชัน วิธีการทั้งสามนี้จะแสดงด้วยบล็อก begin, process และ end ของฟังก์ชัน PowerShell 7.3 เพิ่มวิธีกระบวนการบล็อก clean

คุณไม่จำเป็นต้องใช้บล็อกเหล่านี้ในฟังก์ชันของคุณ หากคุณไม่ได้ใช้บล็อกที่มีชื่อ PowerShell จะวางโค้ดไว้ในบล็อก end ของฟังก์ชัน อย่างไรก็ตาม หากคุณใช้บล็อกที่มีชื่อเหล่านี้ หรือกำหนดบล็อก dynamicparam คุณต้องใส่โค้ดทั้งหมดลงในบล็อกที่มีชื่อ

ตัวอย่างต่อไปนี้แสดงโครงร่างของฟังก์ชันที่มีบล็อก begin สำหรับการประมวลผลล่วงหน้าครั้งเดียว บล็อก กระบวนการ สำหรับการประมวลผลหลายบันทึก และ end บล็อกสำหรับการประมวลผลภายหลังเพียงครั้งเดียว

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

บันทึก

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

<รหัส>เริ่มต้น

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

<รหัส>กระบวนการ

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

ตัวแปรอัตโนมัติ $_ หรือ $PSItem มีออบเจ็กต์ปัจจุบันในไปป์ไลน์เพื่อใช้ในบล็อก process ตัวแปรอัตโนมัติ $input มีตัวแจงนับที่ใช้ได้กับฟังก์ชันและบล็อกสคริปต์เท่านั้น สำหรับข้อมูลเพิ่มเติม โปรดดู about_Automatic_Variables

  • การเรียกใช้ฟังก์ชันที่จุดเริ่มต้นหรือภายนอกไปป์ไลน์ จะดำเนินการบล็อก process หนึ่งครั้ง
  • ภายในไปป์ไลน์ บล็อก กระบวนการ จะดำเนินการหนึ่งครั้งสำหรับแต่ละออบเจ็กต์อินพุตที่เข้าถึงฟังก์ชัน

  • หากอินพุตไปป์ไลน์ที่เข้าถึงฟังก์ชันว่างเปล่า บล็อก กระบวนการ จะไม่ ดำเนินการ

    • บล็อก begin, end และ clean ยังคงทำงานอยู่

มันเป็นสิ่งสำคัญ

หากพารามิเตอร์ฟังก์ชันได้รับการตั้งค่าให้ยอมรับอินพุตไปป์ไลน์ และไม่ได้กำหนดบล็อก กระบวนการ การประมวลผลแบบบันทึกต่อบันทึกจะล้มเหลว ในกรณีนี้ ฟังก์ชันของคุณจะดำเนินการเพียงครั้งเดียว โดยไม่คำนึงถึงอินพุต

เมื่อคุณสร้างฟังก์ชันที่ยอมรับอินพุตไปป์ไลน์และใช้ CmdletBinding บล็อก กระบวนการ ควรใช้ตัวแปรพารามิเตอร์ที่คุณกำหนดไว้สำหรับอินพุตไปป์ไลน์แทน $_ หรือ <รหัส>$PSItem ตัวอย่างเช่น:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1,2,3,4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

<รหัส>สิ้นสุด

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

<รหัส>สะอาด

มีการเพิ่มบล็อก clean ใน PowerShell 7.3

บล็อก clean เป็นวิธีที่สะดวกสำหรับผู้ใช้ในการล้างทรัพยากรที่ครอบคลุมทั่วทั้ง begin, process และ end บล็อก ความหมายคล้ายกับบล็อก สุดท้าย ซึ่งครอบคลุมบล็อกที่มีชื่ออื่นๆ ทั้งหมดของฟังก์ชันสคริปต์หรือ cmdlet ของสคริปต์ การล้างข้อมูลทรัพยากรถูกบังคับใช้สำหรับสถานการณ์ต่อไปนี้:

  1. เมื่อการดำเนินการไปป์ไลน์เสร็จสิ้นตามปกติโดยไม่มีข้อผิดพลาดในการยกเลิก
  2. เมื่อการดำเนินการไปป์ไลน์ถูกขัดจังหวะเนื่องจากข้อผิดพลาดในการยกเลิก
  3. เมื่อไปป์ไลน์ถูกหยุดโดย Select-Object -First
  4. เมื่อไปป์ไลน์ถูกหยุดโดย Ctrl+c หรือ StopProcessing()

บล็อกที่สะอาดจะละทิ้งเอาต์พุตใดๆ ที่เขียนไปยังสตรีม Success

คำเตือน

การเพิ่มบล็อก clean เป็นการเปลี่ยนแปลงที่ไม่สมบูรณ์ เนื่องจาก clean ถูกแยกวิเคราะห์เป็นคำหลัก จึงป้องกันไม่ให้ผู้ใช้เรียกคำสั่งที่ชื่อ clean โดยตรงเป็นคำสั่งแรกในบล็อกสคริปต์ อย่างไรก็ตาม ก็ไม่น่าจะเป็นปัญหา คำสั่งยังคงสามารถเรียกใช้ได้โดยใช้โอเปอเรเตอร์การโทร (& clean)

วิธีการยืนยัน

ShouldProcess

วิธีการนี้ถูกเรียกเพื่อขอการยืนยันจากผู้ใช้ก่อนที่ฟังก์ชันจะดำเนินการที่จะเปลี่ยนแปลงระบบ ฟังก์ชันสามารถดำเนินการต่อได้โดยยึดตามค่าบูลีนที่ส่งคืนโดยเมธอด วิธีนี้สามารถเรียกได้จากภายในบล็อก Process{} ของฟังก์ชันเท่านั้น แอตทริบิวต์ CmdletBinding ต้องประกาศว่าฟังก์ชันรองรับ ShouldProcess (ดังที่แสดงในตัวอย่างก่อนหน้านี้)

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีการนี้ ดู System.Management.Automation.Cmdlet.ShouldProcess

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

ShouldContinue

วิธีการนี้เรียกว่าเพื่อขอข้อความยืนยันครั้งที่สอง ควรถูกเรียกเมื่อเมธอด ShouldProcess ส่งคืน $true สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีการนี้ ดู System.Management.Automation.Cmdlet.ShouldContinue

วิธีการผิดพลาด

ฟังก์ชันสามารถเรียกวิธีการที่แตกต่างกันได้สองวิธีเมื่อเกิดข้อผิดพลาด เมื่อเกิดข้อผิดพลาดที่ไม่สิ้นสุด ฟังก์ชันควรเรียกใช้เมธอด WriteError ซึ่งอธิบายไว้ในส่วนวิธีการ Write เมื่อเกิดข้อผิดพลาดในการยุติและฟังก์ชันไม่สามารถดำเนินการต่อได้ ควรเรียกใช้เมธอด ThrowTerminatingError คุณยังสามารถใช้คำสั่ง Throw เพื่อยุติข้อผิดพลาด และ Write-Error cmdlet สำหรับข้อผิดพลาดที่ไม่ยุติ

สำหรับข้อมูลเพิ่มเติม ดู System.Management.Automation.Cmdlet.ThrowTerminatingError

เขียนวิธีการ

ฟังก์ชันสามารถเรียกใช้เมธอดต่อไปนี้เพื่อส่งคืนเอาต์พุตประเภทต่างๆ โปรดสังเกตว่าไม่ใช่ว่าเอาต์พุตทั้งหมดจะไปที่คำสั่งถัดไปในไปป์ไลน์ คุณยังสามารถใช้ cmdlets Write ต่างๆ ได้ เช่น Write-Error

เขียนคำสั่งรายละเอียด

สำหรับข้อมูลเกี่ยวกับเมธอด WriteCommandDetails โปรดดูที่ System.Management.Automation.Cmdlet.WriteCommandDetail

WriteDebug

เพื่อให้ข้อมูลที่สามารถใช้เพื่อแก้ไขปัญหาฟังก์ชัน ให้ฟังก์ชันเรียกใช้เมธอด WriteDebug วิธีการ WriteDebug จะแสดงข้อความการดีบักให้กับผู้ใช้ สำหรับข้อมูลเพิ่มเติม ดู System.Management.Automation.Cmdlet.WriteDebug

WriteError

ฟังก์ชันควรเรียกใช้เมธอดนี้เมื่อข้อผิดพลาดที่ไม่ยุติเกิดขึ้น และฟังก์ชันได้รับการออกแบบให้ประมวลผลบันทึกต่อไป สำหรับข้อมูลเพิ่มเติม ดู System.Management.Automation.Cmdlet.WriteError

บันทึก

หากมีข้อผิดพลาดในการยุติเกิดขึ้น ฟังก์ชันควรเรียกใช้เมธอด ThrowTerminatingError

WriteObject

วิธีการ WriteObject อนุญาตให้ฟังก์ชันส่งวัตถุไปยังคำสั่งถัดไปในไปป์ไลน์ ในกรณีส่วนใหญ่ WriteObject คือวิธีการใช้เมื่อฟังก์ชันส่งคืนข้อมูล สำหรับข้อมูลเพิ่มเติม โปรดดู System.Management.Automation.PSCmdlet.WriteObject

WriteProgress

สำหรับฟังก์ชันที่มีการดำเนินการที่ใช้เวลานานจึงจะเสร็จสมบูรณ์ เมธอดนี้อนุญาตให้ฟังก์ชันเรียกใช้เมธอด WriteProgress เพื่อแสดงข้อมูลความคืบหน้า ตัวอย่างเช่น คุณสามารถแสดงเปอร์เซ็นต์ที่เสร็จสมบูรณ์ได้ สำหรับข้อมูลเพิ่มเติม โปรดดู System.Management.Automation.PSCmdlet.WriteProgress

WriteVerbose

หากต้องการให้ข้อมูลโดยละเอียดเกี่ยวกับฟังก์ชันที่กำลังทำ ให้ฟังก์ชันเรียกใช้เมธอด WriteVerbose เพื่อแสดงข้อความแบบละเอียดให้กับผู้ใช้ ตามค่าเริ่มต้น ข้อความรายละเอียดจะไม่แสดง สำหรับข้อมูลเพิ่มเติม โปรดดูที่ System.Management.Automation.PSCmdlet.WriteVerbose

WriteWarning

เพื่อให้ข้อมูลเกี่ยวกับเงื่อนไขที่อาจทำให้เกิดผลลัพธ์ที่ไม่คาดคิด ให้เรียกใช้ฟังก์ชันเมธอด WriteWarning เพื่อแสดงข้อความเตือนแก่ผู้ใช้ ตามค่าเริ่มต้น ข้อความเตือนจะแสดงขึ้น สำหรับข้อมูลเพิ่มเติม โปรดดู System.Management.Automation.PSCmdlet.WriteWarning

บันทึก

คุณยังสามารถแสดงข้อความเตือนโดยการกำหนดค่าตัวแปร $WarningPreference หรือโดยใช้ตัวเลือกบรรทัดคำสั่ง Verbose และ Debug สำหรับข้อมูลเพิ่มเติมเกี่ยวกับตัวแปร $WarningPreference โปรดดู about_Preference_Variables

วิธีการและคุณสมบัติอื่น ๆ

สำหรับข้อมูลเกี่ยวกับวิธีการและคุณสมบัติอื่นๆ ที่สามารถเข้าถึงได้ผ่านตัวแปร $PSCmdlet โปรดดูที่ System.Management.Automation.PSCmdlet

ตัวอย่างเช่น คุณสมบัติ parameterSetName ช่วยให้คุณเห็นชุดพารามิเตอร์ที่กำลังใช้งานอยู่ ชุดพารามิเตอร์ช่วยให้คุณสร้างฟังก์ชันที่ดำเนินงานต่างๆ ตามพารามิเตอร์ที่ระบุไว้เมื่อเรียกใช้ฟังก์ชันได้

ดูเพิ่มเติม

  • about_Automatic_Variables
  • about_Functions
  • about_Functions_ขั้นสูง
  • about_Functions_Advanced_Parameters
  • about_Functions_CmdletBindingAttribute
  • about_Functions_OutputTypeAttribute
  • about_Preference_Variables

บทความที่เกี่ยวข้อง