Súgó írása a PowerShell-szkriptekhez és -függvényekhez

A PowerShell-szkripteket és -függvényeket teljes mértékben dokumentálni kell, amikor megosztják őket másokkal. A Get-Help parancsmag ugyanolyan formátumban jeleníti meg a szkript- és függvénysúgó témaköröket, mint a parancsmagok súgója, és az összes Get-Help paraméter működik a szkript- és függvénysúgón. témákat.

A PowerShell-szkriptek tartalmazhatnak egy súgótémát a szkriptről és súgótémaköröket a szkript egyes funkcióiról. A szkriptektől függetlenül megosztott függvények saját súgótémáikat tartalmazhatnak.

Ez a dokumentum elmagyarázza a súgótémák formátumát és helyes elhelyezését, valamint irányelveket javasol a tartalomhoz.

A szkript- és függvénysúgó típusai

Megjegyzés alapú segítség

A parancsfájlt vagy függvényt leíró súgótémakör megjegyzések halmazaként valósítható meg a szkripten vagy függvényen belül. Amikor megjegyzésalapú súgót ír egy szkripthez és a szkriptben lévő függvényekhez, ügyeljen a megjegyzés alapú súgó elhelyezésére vonatkozó szabályokra. Az elhelyezés határozza meg, hogy a Get-Help parancsmag társítja-e a súgótémát a szkripthez vagy egy függvényhez. A megjegyzésalapú súgótémak írásával kapcsolatos további információkért lásd: about_Comment_Based_Help.

XML-alapú parancssúgó

A parancsfájlt vagy függvényt leíró súgótémakör olyan XML-fájlban valósítható meg, amely a parancssúgó sémát használja. A szkript vagy függvény XML-fájlhoz való társításához használja az ExternalHelp megjegyzés kulcsszót, majd az XML-fájl elérési útját és nevét.

Ha jelen van az ExternalHelp megjegyzés kulcsszó, az elsőbbséget élvez a megjegyzésalapú súgóval szemben, még akkor is, ha a Get-Help nem talál olyan súgófájlt, amely megfelel a ExternalHelp kulcsszót.

Online Súgó

A súgótémáit közzéteheti az interneten, majd a Get-Help segítségével megnyithatja a témákat. A megjegyzésalapú súgótémakör írásával kapcsolatos további információkért lásd: Az online súgó támogatása.

Nincs bevett módszer a szkriptek és funkciók fogalmi ("Névjegy") témák írásához. Mindazonáltal közzétehet fogalmi témákat az interneten. A témakörök és URL-címeik listája egy parancssúgó témakör Kapcsolódó hivatkozások szakaszában található.

Tartalmi szempontok a szkript- és függvénysúgóhoz

• Ha egy nagyon rövid súgótémát ír, amely csak néhány rendelkezésre álló parancssúgó-szakaszt tartalmaz, feltétlenül adja meg a parancsfájl vagy a függvény paramétereinek egyértelmű leírását. Adjon meg egy vagy két mintaparancsot is a példák szakaszban, még akkor is, ha úgy dönt, hogy elhagyja a példaleírásokat.

• Minden leírásban hivatkozzon a parancsra mint parancsfájlra vagy függvényre. Ez az információ segít a felhasználónak a parancs megértésében és kezelésében.

  A következő részletes leírás például azt állítja, hogy a New-Topic parancs egy parancsfájl. Ez emlékezteti a felhasználókat, hogy a futtatás során meg kell adniuk az elérési utat és a teljes nevet.

  "A New-Topic szkript létrehoz egy üres fogalmi témát a bemeneti fájl minden témakörének nevéhez..."

  A következő részletes leírás szerint a Disable-PSRemoting egy függvény. Ez az információ különösen hasznos a felhasználók számára, ha a munkamenet több, azonos nevű parancsot tartalmaz, amelyek közül néhányat elrejthet egy magasabb prioritású parancs.

  A Disable-PSRemoting funkció letiltja az összes munkamenet-konfigurációt a helyi számítógépen...

• A szkript súgótémakörében magyarázza el, hogyan kell a szkriptet egészében használni. Ha súgótémaköröket is ír a szkriptben lévő függvényekhez, említse meg a függvényeket a szkript súgótémakörében, és hivatkozzon a függvény súgótémáira a szkript súgótémakör Kapcsolódó hivatkozások szakaszában. Ezzel szemben, ha egy függvény egy szkript része, magyarázza el a függvénysúgó témakörben, hogy a függvény milyen szerepet játszik a szkriptben, és hogyan használható önállóan. Ezután sorolja fel a szkript súgótémáját a függvény súgótémakör Kapcsolódó hivatkozások részében.

• Amikor példákat ír egy script súgótémakörhöz, ügyeljen arra, hogy a példa parancsban szerepeljen a szkriptfájl elérési útja. Ez emlékezteti a felhasználókat, hogy kifejezetten meg kell adniuk az elérési utat, még akkor is, ha a szkript az aktuális könyvtárban van.

• A függvény súgótémakörében emlékeztesse a felhasználókat arra, hogy a függvény csak az aktuális munkamenetben létezik, és más munkamenetekben való használatához hozzá kell adnia, vagy hozzá kell adnia egy PowerShell-profilt.

• A Get-Help csak akkor jeleníti meg a szkript vagy függvény súgótémakörét, ha a szkriptfájl és a súgótéma fájlok a megfelelő helyre vannak mentve. Ezért nem hasznos a PowerShell telepítésére, illetve a szkript vagy függvény mentésére vagy telepítésére vonatkozó utasításokat belefoglalni egy szkript vagy függvény súgótémakörébe. Ehelyett a szkript vagy függvény terjesztéséhez használt telepítési utasításokat adjon meg a dokumentumban.

Lásd még

Megjegyzés-alapú súgótémák írása