วิธีเขียนสำหรับโมดูล PowerShell

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

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

ประเภทของวิธีใช้โมดูล

โมดูลสามารถรวมวิธีใช้ประเภทต่อไปนี้

วิธีใช้ Cmdlet หัวข้อวิธีใช้ที่อธิบาย cmdlet ของโมดูลในโมดูลคือไฟล์ XML ที่ใช้คำสั่งวิธีใช้ schema
ความช่วยเหลือของผู้ให้บริการ หัวข้อวิธีใช้ที่อธิบายผู้ให้บริการในโมดูลคือไฟล์ XML ที่ใช้สคีมาวิธีใช้ของผู้ให้บริการ
วิธีใช้ฟังก์ชัน หัวข้อวิธีใช้ที่อธิบายฟังก์ชันในโมดูลอาจเป็นไฟล์ XML ที่ใช้สคีมาวิธีใช้คำสั่งหรือหัวข้อวิธีใช้ตามความคิดเห็นภายในฟังก์ชัน หรือสคริปต์หรือโมดูลสคริปต์
วิธีใช้สคริปต์ หัวข้อวิธีใช้ที่อธิบายสคริปต์ในโมดูลอาจเป็นไฟล์ XML ที่ใช้คำสั่งวิธีใช้ Schema หรือหัวข้อวิธีใช้ตามความคิดเห็นในสคริปต์หรือโมดูลสคริปต์
ความช่วยเหลือเชิงแนวคิด ("เกี่ยวกับ") คุณสามารถใช้หัวข้อวิธีใช้เชิงแนวคิด ("เกี่ยวกับ") เพื่ออธิบายโมดูลและสมาชิก และเพื่ออธิบายวิธีการใช้สมาชิกร่วมกันเพื่อดำเนินงานต่างๆ หัวข้อวิธีใช้เชิงแนวคิดคือไฟล์ข้อความที่มีการเข้ารหัส Unicode (UTF-8) ชื่อไฟล์ต้องใช้รูปแบบ about_.help.txt เช่น about_MyModule.help.txt ตามค่าเริ่มต้น PowerShell จะมีหัวข้อเกี่ยวกับวิธีใช้เชิงแนวคิดเหล่านี้มากกว่า 100 หัวข้อ และจะมีการจัดรูปแบบตามตัวอย่างต่อไปนี้
```
TOPIC
    about_<subject or module name>

SHORT DESCRIPTION
    A short, one-line description of the topic contents.

LONG DESCRIPTION
    A detailed, full description of the subject or purpose of the module.

EXAMPLES
    Examples of how to use the module or how the subject feature works in practice.

KEYWORDS
    Terms or titles on which you might expect your users to search for the information in this topic.

SEE ALSO
    Text-only references for further reading. Hyperlinks can't work in the PowerShell console.
```

ไฟล์สคีมาทั้งหมดสามารถพบได้ในโฟลเดอร์ $PSHOME\Schemas\PSMaml

ตำแหน่งของวิธีใช้โมดูล

Get-Help cmdlet ค้นหาไฟล์หัวข้อวิธีใช้ของโมดูลในไดเร็กทอรีย่อยเฉพาะภาษาของไดเร็กทอรีโมดูล

ตัวอย่างเช่น แผนภาพโครงสร้างไดเร็กทอรีต่อไปนี้แสดงตำแหน่งของหัวข้อวิธีใช้สำหรับโมดูล SampleModule

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

บันทึก

ในตัวอย่าง ตัวยึดตำแหน่ง <ModulePath> แสดงถึงหนึ่งในเส้นทางในตัวแปรสภาพแวดล้อม PSModulePath เช่น $HOME\Documents\Modules $PSHOME\Modules หรือเส้นทางแบบกำหนดเองที่ผู้ใช้ระบุ

การรับความช่วยเหลือเกี่ยวกับโมดูล

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

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

เริ่มต้นใน PowerShell 3.0 การรันคำสั่ง Get-Help สำหรับ cmdlet หรือฟังก์ชันจะทริกเกอร์การนำเข้าโมดูลโดยอัตโนมัติ Get-Help cmdlet จะแสดงเนื้อหาของหัวข้อความช่วยเหลือในโมดูลทันที

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

รองรับความช่วยเหลือที่อัปเดตได้

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

ผู้ใช้ที่อยู่หลังไฟร์วอลล์และผู้ที่ไม่มีอินเทอร์เน็ตก็สามารถใช้ Updateable Help ได้เช่นกัน ผู้ดูแลระบบที่สามารถเข้าถึงอินเทอร์เน็ตได้ใช้ Save-Help cmdlet เพื่อดาวน์โหลดและติดตั้งไฟล์วิธีใช้ใหม่ล่าสุดในการแชร์ไฟล์ จากนั้น ผู้ใช้ใช้พารามิเตอร์ Path ของ Update-Help cmdlet เพื่อรับไฟล์วิธีใช้ใหม่ล่าสุดจากการแชร์ไฟล์

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

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

สนับสนุนความช่วยเหลือออนไลน์

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

Get-Help cmdlet ใช้ค่าของคุณสมบัติ HelpUri ของ cmdlet หรือฟังก์ชันเพื่อค้นหาเวอร์ชันออนไลน์ของหัวข้อความช่วยเหลือ

เริ่มต้นใน PowerShell 3.0 คุณสามารถช่วยให้ผู้ใช้ค้นหาเวอร์ชันออนไลน์ของ cmdlet และหัวข้อวิธีใช้ฟังก์ชันได้โดยการกำหนดแอตทริบิวต์ HelpUri บนคลาส cmdlet หรือคุณสมบัติ HelpUri ของแอตทริบิวต์ CmdletBinding . ค่าของแอตทริบิวต์คือค่าของคุณสมบัติ HelpUri ของ cmdlet หรือฟังก์ชัน

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ การสนับสนุนวิธีใช้ออนไลน์

ดูเพิ่มเติม

การเขียนโมดูล PowerShell
รองรับความช่วยเหลือที่อัปเดตได้
สนับสนุนความช่วยเหลือออนไลน์