วิธีเขียนสคริปต์และฟังก์ชัน PowerShell

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

สคริปต์ PowerShell สามารถรวมหัวข้อวิธีใช้เกี่ยวกับสคริปต์และหัวข้อวิธีใช้เกี่ยวกับแต่ละฟังก์ชันในสคริปต์ ฟังก์ชันที่แชร์โดยไม่ขึ้นอยู่กับสคริปต์สามารถรวมหัวข้อวิธีใช้ของตนเองได้

เอกสารนี้อธิบายรูปแบบและตำแหน่งที่ถูกต้องของหัวข้อวิธีใช้ และแนะนำแนวทางสำหรับเนื้อหา

ประเภทของสคริปต์และวิธีใช้ฟังก์ชัน

ความช่วยเหลือตามความคิดเห็น

หัวข้อวิธีใช้ที่อธิบายสคริปต์หรือฟังก์ชันสามารถนำมาใช้เป็นชุดความคิดเห็นภายในสคริปต์หรือฟังก์ชันได้ เมื่อเขียนวิธีใช้ตามความคิดเห็นสำหรับสคริปต์และสำหรับฟังก์ชันในสคริปต์ ให้ใส่ใจกฎเกณฑ์ในการวางวิธีใช้ตามความคิดเห็นอย่างระมัดระวัง ตำแหน่งจะกำหนดว่า cmdlet Get-Help เชื่อมโยงหัวข้อวิธีใช้กับสคริปต์หรือฟังก์ชันหรือไม่ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการเขียนหัวข้อวิธีใช้ตามความคิดเห็น โปรดดู about_Comment_Based_Help

วิธีใช้คำสั่งแบบ XML

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

เมื่อมีคีย์เวิร์ดความคิดเห็น ExternalHelp ปรากฏ จะมีลำดับความสำคัญเหนือกว่าความช่วยเหลือตามความคิดเห็น แม้ว่า Get-Help จะไม่พบไฟล์วิธีใช้ที่ตรงกับค่าของ < รหัส>ความช่วยเหลือภายนอก คำหลัก

ความช่วยเหลือออนไลน์

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

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

ข้อควรพิจารณาเกี่ยวกับเนื้อหาสำหรับสคริปต์และวิธีใช้ฟังก์ชัน

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

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

  ตัวอย่างเช่น คำอธิบายโดยละเอียดต่อไปนี้ระบุว่าคำสั่ง New-Topic เป็นสคริปต์ สิ่งนี้จะเตือนผู้ใช้ว่าจำเป็นต้องระบุเส้นทางและชื่อเต็มเมื่อเรียกใช้

  "สคริปต์หัวข้อใหม่สร้างหัวข้อแนวคิดที่ว่างเปล่าสำหรับชื่อหัวข้อแต่ละหัวข้อในไฟล์อินพุต..."

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

  ฟังก์ชัน Disable-PSRemoting จะปิดใช้งานการกำหนดค่าเซสชันทั้งหมดบนเครื่องคอมพิวเตอร์...

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

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

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

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

ดูเพิ่มเติม

การเขียนหัวข้อความช่วยเหลือตามความคิดเห็น