Szükséges fejlesztési irányelvek

A parancsmagok írásakor a következő irányelveket kell követni. Ezek a parancsmagok tervezésére és a parancsmagkód írására vonatkozó irányelvekre vannak elválasztva. Ha nem tartja be ezeket az irányelveket, a parancsmagok sikertelenek lehetnek, és előfordulhat, hogy a felhasználók rossz felhasználói élményt tapasztalnak a parancsmagok használatakor.

Ebben a témakörben

Tervezési irányelvek

Kód irányelvei

Tervezési irányelvek

A parancsmagok tervezésekor a következő irányelveket kell követni, hogy egységes felhasználói élmény legyen a parancsmagok és más parancsmagok használata között. Ha olyan tervezési útmutatót talál, amely az Ön helyzetére vonatkozik, mindenképpen tekintse meg a kódra vonatkozó irányelveket a hasonló irányelvekhez.

Csak jóváhagyott igék használata (RD01)

A Parancsmag attribútumban megadott igének a PowerShell Windows által biztosított felismert igékből kell származnia. Nem lehet a tiltott szinonimák egyike. A parancsmag-igék megadásához használja az alábbi számbavételek által definiált állandó sztringeket:

A jóváhagyott igenevekkel kapcsolatos további információkért lásd a Parancsmag-parancsmagok parancsmag-parancsmagjait.

A felhasználóknak felderíthető és várt parancsmagnevekre van szükségük. Használja a megfelelő igét, hogy a felhasználó gyorsan felmérhesse a parancsmagok által végzett műveleteket, és könnyen felfedezhesse a rendszer képességeit. Az alábbi parancssori parancs például lekéri a rendszer összes parancsának listáját, amelynek a neve "Start" néven kezdődik. Get-Command Start-* A parancsmagok főneveit használva megkülönböztetheti a parancsmagokat a többi parancsmagtól. A főnév azt az erőforrást jelöli, amelyen a műveletet végre fogja hajtani. Magát a műveletet az ige jelöli.

Parancsmagok nevei: Nem használható karakterek (RD02)

A parancsmagok elnevezésekor ne használja az alábbi speciális karakterek egyikét sem.

Karakter Név
# számjel
, vessző
( ) Zárójel
{ } kapcsos zárójelek
[ ] Zárójelben
& és jel
- kötőjel
/ perjel
\ fordított perjel
$ dollárjel
^ caret
; Pontosvessző
: colon
" dupla idézőjel
' egyetlen idézőjel
< > szögletes zárójelek
| függőleges sáv
? Kérdőjel
@ kukacjel
` vissza tick (sír ékezet)
* csillag
% százalékjel
+ pluszjel
= egyenlőségjel
~ tilde

Nem használható paraméternevek (RD03)

Windows PowerShell általános paraméterkészletet biztosít az összes parancsmaghoz, valamint az adott helyzetekben hozzáadott további paramétereket. Saját parancsmagok tervezésekor nem használhatja a következő neveket: Confirm, , Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WhatIfUseTransactionWarningActionWarningVariable, és .Verbose További információ ezekről a paraméterekről: Common Parameter Names.

Támogatási megerősítési kérések (RD04)

A rendszert módosító műveletet végrehajtó parancsmagok esetében meg kell hívniuk a System.Management.Automation.Cmdlet.ShouldProcess* metódust a megerősítés kéréséhez, speciális esetekben pedig a System.Management.Automation.Cmdlet.ShouldContinue* metódust. (A System.Management.Automation.Cmdlet.ShouldContinue* metódus csak a System.Management.Automation.Cmdlet.ShouldProcess* metódus meghívása után hívható meg.)

A hívások indításához a parancsmagnak meg kell adnia, hogy támogatja a megerősítési kéréseket a SupportsShouldProcess Parancsmag attribútum kulcsszójának beállításával. Az attribútum beállításáról további információt a Parancsmag attribútumdeklarációja című témakörben talál.

Note

Ha a parancsmagosztály Parancsmag attribútuma azt jelzi, hogy a parancsmag támogatja a System.Management.Automation.Cmdlet.ShouldProcess* metódus hívásait, és a parancsmag nem tudja meghívni a System.Management.Automation.Cmdlet.ShouldProcess* metódust, a felhasználó váratlanul módosíthatja a rendszert.

Bármilyen rendszermódosításhoz használja a System.Management.Automation.Cmdlet.ShouldProcess* metódust. Egy felhasználói beállítás és a WhatIf paraméter szabályozza a System.Management.Automation.Cmdlet.ShouldProcess* metódust. Ezzel szemben a System.Management.Automation.Cmdlet.ShouldContinue* hívás további ellenőrzést végez a potenciálisan veszélyes módosítások esetében. Ezt a metódust nem szabályozza semmilyen felhasználói beállítás vagy paraméter WhatIf . Ha a parancsmag meghívja a System.Management.Automation.Cmdlet.ShouldContinue* metódust, rendelkeznie kell egy Force olyan paraméterrel, amely átadja a hívásokat e két metódusnak, és amely folytatja a műveletet. Ez azért fontos, mert lehetővé teszi a parancsmag nem interaktív szkriptekben és gazdagépeken való használatát.

Ha a parancsmagok támogatják ezeket a hívásokat, a felhasználó meghatározhatja, hogy a műveletet ténylegesen végre kell-e hajtani. A Stop-Process parancsmag például meghívja a System.Management.Automation.Cmdlet.ShouldContinue* metódust, mielőtt leállítja a kritikus folyamatokat, például a System, a Winlogon és a Spoolsv folyamatokat.

A metódusok támogatásáról további információt a Megerősítés kérése című témakörben talál.

Támogatási kényszerítés paraméter interaktív munkamenetekhez (RD05)

Ha a parancsmag interaktívan van használva, mindig adjon meg egy Kényszerítési paramétert az interaktív műveletek felülbírálásához, például a kéréseket vagy a bemeneti sorok olvasását. Ez azért fontos, mert lehetővé teszi a parancsmag nem interaktív szkriptekben és gazdagépeken való használatát. Az alábbi módszereket egy interaktív gazdagép implementálhatja.

Dokumentumkimeneti objektumok (RD06)

Windows PowerShell a folyamatba írt objektumokat használja. Ahhoz, hogy a felhasználók kihasználhassák az egyes parancsmagok által visszaadott objektumokat, dokumentálnia kell a visszaadott objektumokat, és dokumentálnia kell, hogy a visszaadott objektumok tagjai mire használhatók.

A kód irányelvei

A parancsmagkód írásakor a következő irányelveket kell követni. Ha talál egy, a helyzetére vonatkozó kód-útmutatót, mindenképpen tekintse meg a hasonló irányelvekre vonatkozó tervezési irányelveket.

Származtatás a parancsmag- vagy PSCmdlet-osztályokból (RC01)

A parancsmagnak a System.Management.Automation.Cmdlet vagy a System.Management.Automation.PSCmdlet alaposztályból kell származnia. A System.Management.Automation.Cmdlet osztályból származó parancsmagok nem függnek a PowerShell-futtatókörnyezet Windows. Közvetlenül bármely Microsoft .NET keretrendszernyelvről meghívhatók. A System.Management.Automation.PSCmdlet osztályból származó parancsmagok a PowerShell-futtatókörnyezet Windows függnek. Ezért futtatásuk egy futtató térben történik.

Minden implementált parancsmagosztálynak nyilvános osztályoknak kell lennie. Ezekről a parancsmagosztályokról további információt a Parancsmag áttekintése című témakörben talál.

Adja meg a parancsmag attribútumot (RC02)

Ahhoz, hogy egy parancsmagot felismerjen Windows PowerShell, a .NET Framework osztályát a Parancsmag attribútummal kell díszíteni. Ez az attribútum a parancsmag alábbi funkcióit határozza meg.

  • A parancsmagot azonosító ige és főnév pár.

  • A több paraméterkészlet megadásakor használt alapértelmezett paraméterkészlet. Az alapértelmezett paraméterkészlet akkor használatos, ha Windows PowerShell nem rendelkezik elegendő információval a használni kívánt paraméterkészlet meghatározásához.

  • Jelzi, hogy a parancsmag támogatja-e a System.Management.Automation.Cmdlet.ShouldProcess* metódus hívásait. Ez a metódus egy megerősítő üzenetet jelenít meg a felhasználónak, mielőtt a parancsmag módosítja a rendszert. A megerősítési kérelmek teljesítéséről további információt a Megerősítés kérése című témakörben talál.

  • A megerősítést kérő üzenethez társított művelet hatásszintjének (vagy súlyosságának) jelzése. A legtöbb esetben a Medium alapértelmezett értékét kell használni. Ha többet szeretne tudni arról, hogy a hatásszint hogyan befolyásolja a felhasználónak megjelenített megerősítési kéréseket, olvassa el a Megerősítés kérése című témakört.

A parancsmag attribútum deklarálásával kapcsolatos további információkért lásd: CmdletAttribute Deklaráció.

Bemeneti feldolgozási módszer (RC03) felülbírálása

Ahhoz, hogy a parancsmag részt vegyen a Windows PowerShell-környezetben, felül kell bírálnia az alábbi bemeneti feldolgozási módszerek legalább egyikét.

Adja meg az OutputType attribútumot (RC04)

Az OutputType attribútum (Windows PowerShell 2.0-s verziója) határozza meg azt a .NET Keretrendszertípust, amelyet a parancsmag visszatér a folyamathoz. A parancsmagok kimeneti típusának megadásával a parancsmag által visszaadott objektumok könnyebben felderíthetők lesznek más parancsmagok számára. A parancsmagosztály ezzel az attribútummal történő deklarálásáról további információt az OutputType attribútumdeklarációban talál.

Ne tartsa meg a kimeneti objektumok leíróit (RC05)

A parancsmag nem őrizhet meg semmilyen fogópontot a System.Management.Automation.Cmdlet.WriteObject* metódusnak átadott objektumoknak. Ezeket az objektumokat a rendszer a folyamat következő parancsmagjának továbbítja, vagy egy szkript használja őket. Ha megtartja a fogópontokat az objektumokon, két entitás fogja birtokolni az objektumokat, ami hibákat okoz.

Hibák hatékony kezelése (RC06)

A felügyeleti környezet eredendően észleli és végrehajtja a felügyelni kívánt rendszer fontos módosításait. Ezért létfontosságú, hogy a parancsmagok helyesen kezeljék a hibákat. A hibarekordokkal kapcsolatos további információkért lásd Windows PowerShell-hibajelentést.

A System.Management.Automation.ErrorRecord objektumhoz egy hibakategória is szükséges, amely a felhasználó hibáit csoportosítja. A felhasználó a kategória alapján tekintheti meg a hibákat, ha a $ErrorView rendszerhéjváltozó értékét CategoryView értékre állítja. A lehetséges kategóriákat a System.Management.Automation.ErrorCategory enumerálás határozza meg.

  • Ha egy parancsmag létrehoz egy új szálat, és ha a szálon futó kód kezeletlen kivételt okoz, Windows a PowerShell nem tudja elkapni a hibát, és leállítja a folyamatot.

  • Ha egy objektum kóddal rendelkezik a destruktorban, amely kezeletlen kivételt okoz, Windows PowerShell nem tudja elkapni a hibát, és leállítja a folyamatot. Ez akkor is előfordul, ha egy objektum nem kezelt kivételt okozó Ártalmatlanítás metódusokat hív meg.

Parancsmagok üzembe helyezése Windows PowerShell-modullal (RC07)

Hozzon létre egy Windows PowerShell-modult a parancsmagok csomagolásához és üzembe helyezéséhez. A modulok támogatása a Windows PowerShell 2.0-ban érhető el. A parancsmagosztályokat tartalmazó szerelvényeket közvetlenül bináris modulfájlokként használhatja (ez nagyon hasznos a parancsmagok tesztelése során), vagy létrehozhat egy moduljegyzéket, amely a parancsmag-szerelvényekre hivatkozik. A modulok használatakor meglévő beépülő modulok is hozzáadhatók. A modulokkal kapcsolatos további információkért lásd: Windows PowerShell-modul írása.

Lásd még

  • Last updated on