Javasolt fejlesztői útmutató

  • Cikk

Ez a szakasz azokat az irányelveket ismerteti, amelyek a parancsmagok írhatóak. Ezek a parancsmagok tervezésének irányelvei és a parancsmagkód megírásának irányelvei szerint vannak elválasztva. Előfordulhat, hogy ezek az irányelvek nem minden forgatókönyvre vonatkoznak. Ha azonban érvényesek, és Ön nem követi ezeket az irányelveket, a felhasználók rossz élményben lehetnek a parancsmagok használata során.

Tervezési irányelvek

A következő irányelveket kell követnie a parancsmagok tervezésekor, hogy a parancsmagok és más parancsmagok használata során egységes felhasználói élményt biztosítsunk. Ha az adott helyzetre vonatkozó tervezési útmutatót talál, mindenképpen nézze meg a hasonló irányelvekre vonatkozó kód-irányelveket.

Parancsmag nevének (SD01) használata egy adott főnévvel

A parancsmagok elnevezésében használt főneveknek nagyon specifikusnak kell lennie, hogy a felhasználó felfedezze a parancsmagokat. Általános főnevek ( például "kiszolgáló" ) előtagja a terméknév rövid verziójával. Ha például egy főnév egy olyan kiszolgálóra hivatkozik, amely a név egy példányát Microsoft SQL Server, használjon főnév, például "SQLServer". Az egyes főnevek és a jóváhagyott műveletek rövid listája együttesen lehetővé teszi, hogy a felhasználó gyorsan felderítsen és előre ássa a funkciókat, miközben elkerüli a parancsmagok nevei közötti duplikálást.

A felhasználói élmény javítása érdekében a parancsmag nevéhez választott főnévnek egyes számnak kell lennie. Használja például a nevet a Get-Process Get-Processes helyett. Ez a szabály minden parancsmagnévre vonatkozik, még akkor is, ha egy parancsmag valószínűleg több elemre is vonatkozik.

A Parancsmagok neveinek (SD02) használata a Parancsmagok neveihez

A paraméternevekhez használja a Kis- és a Nagy- és a Nagy Más szóval nagy betűvel írhatja be az ige első betűjét és a főnévben használt összes szót. Például: „Clear-ItemProperty”.

Paramétertervezési irányelvek (SD03)

A parancsmagok olyan paramétereket használnak, amelyek megkapják azokat az adatokat, amelyeken működniük kell, valamint olyan paraméterekre, amelyek a művelet jellemzőinek meghatározásához használt információkat jelzik. Egy parancsmag például olyan paraméterrel is lehet, amely adatokat fogad a folyamattól, a parancsmag pedig egy olyan paraméterrel, amely azt jelzi, hogy a parancsmag kényszerítve lehet a művelet Name Force elvégzésére. A parancsmagok által definiálható paraméterek száma nincs korlátozva.

Szabványos paraméternevek használata

A parancsmagnak szabványos paraméterneveket kell használnia, hogy a felhasználó gyorsan megállapítsa, mit jelent egy adott paraméter. Ha pontosabb névre van szükség, használjon standard paraméternevet, majd adjon meg egy konkrétabb nevet aliasként. A parancsmag például rendelkezik egy paraméterrel, amely egy általános névvel ( ) és egy pontosabb Get-Service Name aliast ( ) ServiceName használ. Mindkét kifejezés használható a paraméter megadásához.

A paraméternevekkel és adattípusaikkal kapcsolatos további információkért lásd: Parancsmag paraméternevének és funkciós irányelveinek.

Egyes paraméternevek használata

Kerülje a többes számú neveket olyan paraméterekhez, amelyeknek az értéke egyetlen elem. Ez magában foglalja a tömbök vagy listák lekért paramétereit, mert a felhasználó egy tömböt vagy listát is meg lehet kiosztása egyetlen elemmel.

A többes számú paraméternevek csak olyan esetekben használhatók, ahol a paraméter értéke mindig többelemű érték. Ezekben az esetekben a parancsmagnak ellenőriznie kell, hogy több elem van-e megadva, és a parancsmagnak figyelmeztetést kell megjelenítenie a felhasználó számára, ha több elem nincs megadva.

A Paraméternevek értékeként használjon Kis- és kis- és kis- és nagy adatokat

A paraméternevekhez használja a Kis- és a Nagy- és a Nagy Más szóval a paraméter nevének minden egyes szavának első betűje nagybetűvel, a név első betűjével együtt. A paraméter neve például ErrorAction a helyes kis- és nagybetűs adatokat használja. Az alábbi paraméternevekben helytelen kis- és nagybetűk vannak megadva:

  • errorAction
  • erroraction

Beállítások listáját felhozó paraméterek

Két módon hozhat létre olyan paramétert, amelynek értéke több beállításból is kiválasztható.

  • Definiálhat egy enumerálástípust (vagy használhat meglévő enumerálástípust), amely meghatározza az érvényes értékeket. Ezután az enumerálás típusának használatával hozzon létre egy ilyen típusú paramétert.

  • Adja hozzá a ValidateSet attribútumot a paraméterdeklarációhoz. További információ erről az attribútumról: ValidateSet Attribute Deklaráció.

Standard típusok használata paraméterekhez

A más parancsmagokkal való konzisztencia biztosítása érdekében használjon standard típusokat a paraméterekhez, ahol csak lehetséges. A különböző paraméterekhez használni szükséges típusokkal kapcsolatos további információkért lásd: Standard parancsmag-paraméternevek és -típusok. Ez a témakör számos olyan témakörre mutató hivatkozásokat tartalmaz, amelyek ismertetik a szabványos paraméterek .NET-keretrendszer, például a "tevékenységparaméterek" csoportjainak nevét és típustípusát.

A Strongly-Typed .NET-keretrendszer használata

A paramétereket típusként kell .NET-keretrendszer, hogy jobb paraméterellenőrzést biztosítson. Az értékkészletből egy értékre korlátozott paramétereket például enumerációs típusként kell definiálni. A paraméter Uniform Resource Identifier (URI) értékének támogatásához adja meg a paramétert System.Uri típusként. Kerülje az alapszintű sztringparamétereket az összes szabad szöveges tulajdonságon túl.

Konzisztens paramétertípusok használata

Ha ugyanazt a paramétert több parancsmag használja, mindig ugyanazt a paramétertípust használja. Ha például a paraméter egy System.Int16 típus az egyik parancsmaghoz, ne adja meg egy másik parancsmag paraméterét Process Process System.Uint16 típusként.

Igaz és hamis értékeket felhozó paraméterek

Ha a paraméter csak és értékeket vesz fel, adja meg a paramétert true false a következő típussal: System.Management.Automation.SwitchParameter. A kapcsolóparaméterek úgy true kezelhetők, mint amikor meg van adva egy parancsban. Ha a paraméter nem szerepel a parancsban, a Windows PowerShell a paraméter értékét a következőnek tekinti: false . Ne határozzon meg logikai paramétereket.

Ha a paraméternek 3 értéket kell megkülönböztetnie: $true, $false és a "nem meghatározott", akkor adjon meg egy Nullázható típusú <bool> paramétert. A harmadik, "nincs meghatározva" érték általában akkor szükséges, ha a parancsmag egy objektum logikai tulajdonságát tudja módosítani. Ebben az esetben a "nincs megadva" azt jelenti, hogy nem módosítja a tulajdonság aktuális értékét.

Paramétertömbök támogatása

A felhasználóknak gyakran több argumentumon is el kell végezniük ugyanazt a műveletet. Ezen felhasználók esetében a parancsmagnak el kell fogadnia egy tömböt paraméterbevitelként, hogy a felhasználó átadhatja az argumentumokat a paraméternek Windows PowerShell változóként. A Get-Process parancsmag például tömböt használ a lekérni szükséges folyamatok nevét azonosító sztringekhoz.

A PassThru paraméter támogatása

Alapértelmezés szerint számos olyan parancsmag, amely módosítja a rendszert, például a Stop-Process parancsmag, "fogadóként" működik az objektumoknál, és nem ad vissza eredményt. Ezeknek a parancsmagnak implementálja a paramétert, amely arra kényszeríti a PassThru parancsmagot, hogy egy objektumot ad vissza. Ha a paraméter meg van adva, a parancsmag egy objektumot ad vissza PassThru a System.Management.Automation.Cmdlet.WriteObject metódus hívásával. A következő parancs például leállítja a calc folyamatot, és átadja az eredményül kapott folyamatot a folyamatnak.

Stop-Process calc -passthru

A legtöbb esetben az Add, Set és New parancsmagok támogatják a PassThru paramétert.

Paraméterkészletek támogatása

A parancsmagok egyetlen célt szolgálnak. A művelet vagy a műveleti cél leírásának azonban gyakran több módja is van. Egy folyamatot például a neve, azonosítója vagy egy folyamatobjektum azonosíthat. A parancsmagnak támogatnia kell a céljainak minden ésszerű ábrázolását. A parancsmag általában megfelel ennek a követelménynek az együttesen működő paraméterkészletek (más néven paraméterkészletek) megadásával. Egyetlen paraméter bármilyen számú paraméterkészlethez lehet tartozni. A paraméterkészletekkel kapcsolatos további információkért lásd: Parancsmag-paraméterkészletek.

Paraméterkészletek megadásakor a készletben csak egy paramétert állítson be ValueFromPipeline értékre. A Paraméter attribútum deklarál használatával kapcsolatos további információkért lásd: ParameterAttribute-deklaráció.

Paraméterkészletek használata esetén az alapértelmezett paraméterkészletet a Parancsmag attribútum határozza meg. Az alapértelmezett paraméterkészletnek tartalmaznia kell az interaktív munkamenetben legnagyobb valószínűséggel használni Windows PowerShell paramétereket. További információ a parancsmag attribútum deklarál lásd: CmdletAttribute Deklaráció.

Visszajelzés küldése a felhasználónak (SD04)

Az ebben a szakaszban található irányelvek alapján visszajelzést küldhet a felhasználónak. Ez a visszajelzés lehetővé teszi a felhasználó számára, hogy tisztában legyen azzal, mi történik a rendszerben, és jobb adminisztratív döntéseket hozzon.

A Windows PowerShell lehetővé teszi a felhasználó számára, hogy egy beállításváltozó beállításával megadja, hogyan kezelje a metódus egyes hívásának Write kimenetét. A felhasználó több preferenciaváltozót is beállíthat, például egy változót, amely meghatározza, hogy a rendszer megjelenítse-e az információkat, valamint egy változót, amely meghatározza, hogy a rendszer lekérdezi-e a felhasználót a további művelet előtt.

A WriteWarning, WriteVerbose és WriteDebug metódusok támogatása

A parancsmagnak meg kell hívnia a System.Management.Automation.Cmdlet.WriteWarning metódust, amikor a parancsmag olyan műveletet fog végrehajtani, amely nem szándékolt eredményt eredményezhet. Egy parancsmagnak például ezt a metódust kell hívnia, ha a parancsmag írási fájl felülírása előtt áll.

A parancsmagnak meg kell hívnia a System.Management.Automation.Cmdlet.WriteVerbose metódust, ha a felhasználónak bizonyos részletekre van szüksége a parancsmag által használt feladatokról. Egy parancsmagnak például akkor kell ezt az információt hívnia, ha a parancsmag szerzője úgy véli, hogy vannak olyan forgatókönyvek, amelyekhez további információra lehet szükség a parancsmag által végzünk.

A parancsmagnak akkor kell a System.Management.Automation.Cmdlet.WriteDebug metódust hívnia, ha egy fejlesztőnek vagy terméktámogatási mérnöknek tudnia kell, mi sérült a parancsmagműveletben. Nem szükséges, hogy a parancsmag ugyanabban a kódban hívja meg a System.Management.Automation.Cmdlet.WriteDebug metódust, amely a System.Management.Automation.Cmdlet.WriteVerbose metódust hívja meg, mert a paraméter mindkét információkészletet Debug tartalmazza.

A WriteProgress támogatása a hosszú ideig tartó műveletekhez

A hosszú ideig tartó és a háttérben nem futtatható parancsmag-műveleteknek támogatniuk kell a folyamatjelentést a System.Management.Automation.Cmdlet.WriteProgress metódus rendszeres hívásával.

A gazdaillesztők használata

Esetenként a parancsmagnak közvetlenül kell kommunikálnia a felhasználóval a System.Management.Automation.Cmdlet osztály által támogatott különböző Write vagy Should metódusok használata helyett. Ebben az esetben a parancsmagnak a System.Management.Automation.PSCmdlet osztályból kell származtatva a System.Management.Automation.PSCmdlet.Host* tulajdonságot használnia. Ez a tulajdonság különböző kommunikációs típusokat támogat, beleértve a PromptForChoice, a Prompt és a WriteLine/ReadLine típusokat. A legspecifikusabb szinten az egyes kulcsok olvasásának és írásának, valamint a pufferek megoldásának módját is biztosítja.

Hacsak egy parancsmagot nem kifejezetten grafikus felhasználói felület (GUI) létrehozásához terveztek, nem kerülheti meg a gazdagépet a System.Management.Automation.PSCmdlet.Host* tulajdonság használatával. Grafikus felhasználói felület létrehozásához tervezett parancsmag például az Out-GridView parancsmag.

Megjegyzés

A parancsmagok ne használják a System.Console API-t.

Parancsmag-súgófájl létrehozása (SD05)

Minden parancsmag-szerelvényhez hozzon létre egy Help.xml fájlt, amely a parancsmag információit tartalmazza. Az információk között szerepel többek között a parancsmag leírása, a parancsmag paramétereinek leírása, példák a parancsmag használatára.

Kódra vonatkozó irányelvek

A parancsmagok kódolása során az alábbi irányelveket kell követni, hogy egységes felhasználói élményt biztosítsunk a parancsmagok és más parancsmagok használata között. Ha az adott helyzetre vonatkozó kód-útmutatót talál, mindenképpen nézze meg a hasonló irányelvek tervezési útmutatóját.

Kódolási paraméterek (SC01)

Definiálhat egy paramétert a parancsmagosztály olyan nyilvános tulajdonságának deklarálva, amely a Parameter attribútummal van megadva. A paramétereknek nem kell statikus tagoknak lennie a parancsmag származtatott .NET-keretrendszer osztályában. A Paraméter attribútum deklarál használatával kapcsolatos további információkért lásd: Paraméterattribútum-deklaráció.

Támogatási Windows PowerShell elérési utak

A Windows PowerShell elérési út a névterek hozzáférésének normalizálásának mechanizmusa. Amikor hozzárendel egy Windows PowerShell egy paraméterhez a parancsmagban, a felhasználó meghatározhat egy egyéni "meghajtót", amely egy adott elérési út parancsikonjaként működik. Amikor egy felhasználó kijelöl egy ilyen meghajtót, a tárolt adatok, például a beállításjegyzék adatai konzisztens módon használhatók.

Ha a parancsmag lehetővé teszi, hogy a felhasználó megadzon egy fájlt vagy egy adatforrást, meg kell határoznia egy System.String típusú paramétert. Ha egynél több meghajtó támogatott, a típusnak tömbnek kell lennie. A paraméter nevének a következőnek kell Path lennie: , PSPath aliassal. Emellett a paraméternek Path támogatnia kell a helyettesítő karaktereket. Ha nem szükséges helyettesítő karakterek támogatása, definiálni kell egy LiteralPath paramétert.

Ha Windows PowerShell parancsmag által beolvasott vagy írt adatoknak fájlnak kell lennie, Windows PowerShell parancsmagnak el kell fogadnia egy elérési út bemenetét, és a parancsmagnak Windows PowerShell System.Management.Automation.Sessionstate.Path tulajdonságot kell használnia az Windows PowerShell-útvonalak a fájlrendszer által felismert elérési utakra történő lefordítása érdekében. Az egyes mechanizmusok a következő módszereket tartalmazzák:

Ha a parancsmag által beolvasott vagy írt adatok fájl helyett csak sztringek halmazai, a parancsmagnak a szolgáltató tartalominformációit (tag) kell használnia az olvasáshoz és Content íráshoz. Ez az információ a System.Management.Automation.Provider.CmdletProvider.InvokeProvider tulajdonságból szerezhető be. Ezek a mechanizmusok lehetővé teszik, hogy más adattárak is részt vegyenek az adatok olvasásakor és írásában.

Helyettesítő karakterek támogatása

Ha lehetséges, a parancsmagnak támogatnia kell a helyettesítő karaktereket. A helyettesítő karakterek támogatása a parancsmagok számos helyen történik (különösen akkor, ha egy paraméter egy sztringet vesz igénybe egy objektum objektumkészletből való azonosításához). A StopProc oktatóanyag minta parancsmagja például meghatároz egy paramétert a folyamatneveket képviselő Stop-Proc Name sztringek kezelésére. Ez a paraméter támogatja a helyettesítő karaktereket, így a felhasználó könnyen megadhatja a leállítható folyamatokat.

Ha a helyettesítő karakterek támogatottak, a parancsmagműveletek általában tömböt hoznak létre. Esetenként nincs értelme tömböt támogatni, mert a felhasználó egyszerre csak egyetlen elemet használhat. A Set-Location parancsmagnak például nem kell támogatnia a tömböt, mert a felhasználó csak egyetlen helyet ad meg. Ebben az esetben a parancsmag továbbra is támogatja a helyettesítő karaktereket, de egyetlen helyre kényszeríti a feloldásokat.

A helyettesítő karakteres mintákkal kapcsolatos további információkért lásd: Helyettesítő karakterek támogatása a parancsmag-paraméterekben.

Objektumok definiálása

Ez a szakasz irányelveket tartalmaz a parancsmagok objektumának meghatározásához és a meglévő objektumok kibővítéséhez.

Standard tagok meghatározása

Standard tagok definiálása az objektumtípus egyéni Types.ps1xml fájlban való kiterjesztéséhez (használja a Windows PowerShell Types.ps1xml fájlt sablonként). A standard tagokat egy PSStandardMembers nevű csomópont határozza meg. Ezek a definíciók lehetővé teszik, hogy más parancsmagok és a Windows PowerShell a runtime konzisztens módon működjön együtt az objektummal.

Paraméterekként használható ObjectMemberek definiálása

Ha egy parancsmaghoz tervez objektumot, győződjön meg arról, hogy annak tagjai közvetlenül az azt használni fogó parancsmagok paramétereihez vannak leképezve. Ez a leképezés lehetővé teszi, hogy az objektum könnyen elküldhető legyen a folyamatnak, és az egyik parancsmagból egy másikba legyen átküldve.

A parancsmagok .NET-keretrendszer által visszaadott, előre használt objektumok gyakran hiányoznak néhány fontos vagy kényelmes tagból, amelyekre a szkriptfejlesztő vagy a felhasználónak szüksége van. Ezek a hiányzó tagok különösen fontosak a megjelenítéshez és a megfelelő tagnevek létrehozásához, hogy az objektum megfelelően át legyen helyezve a folyamatnak. Hozzon létre egy egyéni Types.ps1xml fájlt a szükséges tagok dokumentálása érdekében. A fájl létrehozásakor a következő elnevezési konvenciót javasoljuk: <Your_Product_Name>. Types.ps1xml.

Hozzáadhat például egy script tulajdonságot a Mode System.IO.FileInfo típushoz, hogy egy fájl attribútumai jobban érthetőbbek le tudjanak jelenni. Emellett hozzáadhat egy aliastulajdonságokat a System.Array típushoz, hogy lehetővé tegye a tulajdonságnév konzisztens használatát Count (a Length helyett).

Az IComparable interfész implementálja

Implementálja a System.IComparable interfészt az összes kimeneti objektumon. Ez lehetővé teszi, hogy a kimeneti objektumok könnyedén átvehetők a különböző rendezési és elemzési parancsmagok számára.

Megjelenítési információk frissítése

Ha egy objektum megjelenítése nem a várt eredményeket adja meg, hozzon létre egy <YourProductName> egyéniet. Az objektum format.ps1xml fájlja.

Jól definiált folyamatbemenet (SC02) támogatása

Implementálja egy folyamat közepére

Implementálja a parancsmagot, feltételezve, hogy a folyamat közepéről lesz meghívva (vagyis más parancsmagok elő fogják készíteni a bemenetet vagy a kimenetet fogják fogyasztani). Tegyük fel például, hogy a parancsmag, mivel adatokat hoz létre, csak az első parancsmagként van Get-Process használva egy folyamatban. Mivel azonban ez a parancsmag egy folyamat közepére lett tervezve, ez a parancsmag lehetővé teszi a folyamat korábbi parancsmagainak vagy adatainak a lekérni kívánt folyamatok megadását.

A folyamat bemenetének támogatása

Egy parancsmag minden paraméterkészletében legalább egy olyan paramétert tartalmaz, amely támogatja a folyamat bemenetét. A folyamat bemenetének támogatása lehetővé teszi a felhasználó számára az adatok vagy objektumok lekérését, a megfelelő paraméterkészletbe való elküldését, valamint az eredmények közvetlen elküldését egy parancsmagnak.

A paraméter akkor fogad bemenetet a folyamattól, ha a Parameter attribútum tartalmazza a kulcsszót, a kulcsszóattribútumot vagy mindkét kulcsszót a ValueFromPipeline ValueFromPipelineByPropertyName deklarációban. Ha egy paraméterkészlet egyik paramétere sem támogatja a vagy a kulcsszót, a parancsmag nem helyezhető értelmesen egy másik parancsmag után, mert figyelmen kívül hagyja a folyamat ValueFromPipeline ValueFromPipelineByPropertyName bemenetét.

A ProcessRecord metódus támogatása

Ahhoz, hogy elfogadja a folyamat előző parancsmagja összes rekordját, a parancsmagnak implementálja a System.Management.Automation.Cmdlet.ProcessRecord metódust. Windows PowerShell a metódust többször is, egyszer a parancsmagnak küldött minden rekordhoz.

Egyetlen rekord írása a folyamatba (SC03)

Amikor egy parancsmag objektumokat ad vissza, a parancsmagnak a generáláskor azonnal meg kell írnia az objektumokat. A parancsmag nem tart ilyeneket ahhoz, hogy egy kombinált tömbbe pufferelje őket. Azok a parancsmagok, amelyek bemenetként kapják meg az objektumokat, képesek lesznek a kimeneti objektumok feldolgozására, megjelenítésére vagy feldolgozására, valamint a kimeneti objektumok késleltetés nélküli megjelenítésére. A kimeneti objektumokat egyszerre csak egyszer generáló parancsmagnak meg kell hívnia a System.Management.Automation.Cmdlet.WriteObject metódust. Egy parancsmag, amely kimeneti objektumokat hoz létre kötegben (például azért, mert egy mögöttes API kimeneti objektumok tömböt ad vissza), a System.Management.Automation.Cmdlet.WriteObject metódust kell hívnia a második paraméter true értékével.

Parancsmagok Case-Insensitive és Case-Preserving (SC04)

Alapértelmezés szerint a Windows PowerShell a kis- és a kis- és a nagy- és a nagy- és a kis- és a nagy- és kis Mivel azonban számos már használatban előtti rendszerrel foglalkozik, a Windows PowerShell megőrzi az esetet az egyszerű működés és kompatibilitás érdekében. Más szóval, ha egy karaktert nagybetűvel ad meg, a Windows PowerShell nagybetűkben tartja meg. Ahhoz, hogy a rendszerek megfelelően működjön, a parancsmagnak követnie kell ezt a konvenciót. Ha lehetséges, a kis- és a nagy- és kis- és a nagy- és kis- Meg kell azonban őriznie a parancsmagok eredeti esetét, amelyek később a parancsban vagy a folyamatban fordulnak elő.

Lásd még:

Kötelező fejlesztői útmutató

Tanácsolt fejlesztői útmutató

Windows PowerShell-parancsmag írása